Skip to content

AGENTS.md

Latest commit

 

History

History
94 lines (66 loc) · 4.96 KB

AGENTS.md

File metadata and controls

94 lines (66 loc) · 4.96 KB
Raw

BEGIN PROMPTIFY MANAGED BLOCK

Promptify for Codex

Adapter skill: /Users/blingabc/.promptify/current/adapters/codex/skills/promptify/SKILL.md Fallback instructions: /Users/blingabc/.promptify/current/adapters/codex/instructions/promptify.md Shared rules: /Users/blingabc/.promptify/current/shared

END PROMPTIFY MANAGED BLOCK

Codex-Claude-Monitor Repository Guide

Project Overview

Codex-Claude-Monitor is a local VS Code extension that shows the current Codex or Claude Code context usage percentage in the status bar.

The project uses CommonJS, Node built-in modules, and the vscode API. There is no build step and no runtime dependency beyond VS Code.

Commands

Run all tests:

npm test

Run one test file:

node --test test/claudeUsage.test.js

Local development install:

ln -s /path/to/codex-claude-monitor ~/.vscode/extensions/codex-claude-monitor

Then run Developer: Reload Window in VS Code.

Architecture

Data flow:

local session JSONL files -> provider parsers -> latest active provider -> VS Code status bar

Workspace filtering is handled outside the VS Code entry point where possible. readLatestAgentUsage accepts optional workspaceFolders as absolute paths. Empty or missing workspaceFolders means no filtering.

  • src/sessionFiles.js: shared provider utilities for recursive file scanning, mtime sorting, JSONL parsing, context percentage calculation, and cached last-matching-event reads.
  • src/codexUsage.js: scans ~/.codex/sessions for rollout-*.jsonl, reads the latest token_count event, and uses last_token_usage.input_tokens / model_context_window.
  • src/claudeUsage.js: scans ~/.claude/projects for .jsonl, reads the latest assistant message.usage, and infers the context window from the model name. Files without an assistant usage entry (e.g. probe sessions) are skipped, trying the newest 10 by mtime.
  • src/claudeRateLimits.js: probes Claude subscription usage by running claude -p "/usage" asynchronously and parsing the "Current session" / "Current week (all models)" lines into the Codex-shaped rateLimits object, including the trailing resets … text parsed into resets_at (Unix seconds, machine-local wall clock, nearest-year inference); resolves the CLI path across common install locations. Failures resolve null.
  • src/agentUsage.js: aggregation and formatting layer. It reads provider candidates, selects the most recent updatedAt, attaches probed claudeRateLimits when Claude wins, and formats status bar text (provider, context percent, and compact rate-limit segments using codicon icons, e.g. Codex $(comment) 3% · $(history) 45% · $(calendar) 23% or Claude $(comment) 50% · $(history) 25% · $(calendar) 8%), tooltip text, usage severity (low/medium/high, used by extension.js for status bar coloring), model details, and rate-limit rows. The friendly model name and rate-limit reset times (absolute time plus a relative countdown, e.g. Reset at 14:32 (in 2h 13m)) are kept out of the status bar and surfaced only in the tooltip.
  • src/extension.js: the only file that depends on the vscode API. It owns the status bar item, refresh timer, the Claude usage probe timer (default 15 min, claudeUsageProbeIntervalMs, 0 disables, minimum 5 min to avoid tripping Anthropic's rate limiting), configuration reads, workspace folder extraction, and agentTokenStatus.refresh.

Provider contract:

{
  provider,
  sessionFile,
  updatedAt,
  contextTokens,
  contextWindow,
  contextPercent,
  ...
}

New providers should implement that shape and be added to the candidate list in src/agentUsage.js. Formatting should remain in the aggregation layer.

Coding Guidelines

  • Keep parsing and formatting logic independent from the vscode API so it can be tested with Node's built-in test runner.
  • Keep changes small and scoped to the requested behavior.
  • Do not introduce a build system, bundler, or dependency unless the task explicitly requires it.
  • Preserve public command ids and configuration keys such as agentTokenStatus.refresh, agentTokenStatus.sessionsRoot, agentTokenStatus.claudeRoot, agentTokenStatus.refreshIntervalMs, agentTokenStatus.claudeUsageProbeIntervalMs, and agentTokenStatus.claudeCliPath.
  • When adding support for new Claude model context windows, update inferClaudeContextWindow in src/claudeUsage.js.
  • Test fixtures should use test/testUtils.js helpers such as makeTempDir, writeJsonl, and setMtime.

Verification

For behavior or parser changes, run:

npm test

For UI-facing text changes, update the matching expectations in test/agentUsage.test.js and verify the extension manually in VS Code when practical:

  1. Run Developer: Reload Window.
  2. Confirm the status bar shows the active provider, context percentage, and the severity color (green / yellow / red).
  3. Hover the status bar item to inspect tooltip details.
  4. Click the status bar item and confirm it refreshes without opening a notification.