Agentstat
Agentstat is a local-first VS Code extension for understanding usage of AI coding agents. It aggregates provider-owned metadata into a compact dashboard without an account, API key, external server, telemetry, prompts, responses, or source-code contents.
Supported providers
- Codex CLI: reads rollout JSONL files below
CODEX_HOME/sessions and CODEX_HOME/archived_sessions (default ~/.codex).
- Claude Code: reads top-level session JSONL files below
CLAUDE_CONFIG_DIR/projects (default ~/.claude/projects), excluding subagent directories.
Detection and parsing are intentionally separate. If a provider is installed but does not expose readable session files, the dashboard reports that state and leaves unavailable metrics blank.
Metrics
When present in local provider data, Agentstat shows total tokens, sessions, provider/model/project breakdowns, daily activity, recent session metadata, request counts, and session duration. Token fields remain optional; missing values are never silently changed to zero.
Privacy model
Provider files are read-only. Agentstat parses only metadata needed for aggregation and never stores prompt text, response text, source code, credentials, API keys, or environment secrets. The normalized cache is stored in VS Code global storage, outside repositories, and can be rebuilt or discarded at any time. No data leaves the machine.
The extension does not read Codex or Claude browser databases, account files, billing APIs, or desktop-app databases. It also does not estimate cost or quota usage.
Development
npm install
npm run lint
npm run test
npm run build
The build bundles the extension and creates agentstat-<version>.vsix at the repository root.
Press F5 in VS Code to launch an Extension Development Host. Open the Command Palette and run Agentstat: Open Dashboard.
Release
Every push to main runs the release workflow. It validates the repository, assigns the next patch version, builds and retains a .vsix artifact, publishes that exact package to the Visual Studio Marketplace through GitHub Actions OIDC, and attaches it to a GitHub Release. Re-running the same commit reuses its existing version and release.
Configure a trusted publisher policy for the atxme/agentstat repository and the Release VSIX workflow. To start a new major or minor release line, set a higher stable version in package.json; otherwise the workflow increments the latest release tag's patch number. Keep CHANGELOG.md current before merging to main.
Architecture
Provider discovery finds read-only source files. Provider adapters parse their formats into the provider-independent UsageRecord model. UsageService isolates provider failures and writes a recoverable normalized cache. Analytics aggregates records by period, provider, model, project, and day. The dashboard and Activity Bar summary consume only normalized aggregates and safe session metadata.
Current limitations
- Provider file formats can evolve; malformed or unsupported sessions are skipped and logged to the Agentstat output channel.
- The extension does not attempt to reconstruct usage from desktop-app SQLite databases.
- Cost, quota limits, reasoning tokens, and cached-token semantics are shown only when the provider writes reliable local fields.
- A refresh currently reparses discovered provider files. The cache protects the dashboard from startup work and is designed for future file-signature-based incremental collection.
Marketplace configuration
The package is configured for the atxme Marketplace publisher and the atxme/agentstat repository. The atxme publisher must exist in Visual Studio Marketplace before the release workflow can publish; the required trusted publisher policy is described in the release section above.
