TokenTrace VS Code companion
Thin extension for dashboard handoff, one-use collector enrollment, and encrypted outbox status. It does not scan workspaces, start a background daemon, expose a localhost control server, or claim native vendor adapter support.
Quick start
- Install the independent TokenTrace collector for your operating system. This extension does not bundle it or your coding agent.
- Open TokenTrace in the activity bar and choose Set up TokenTrace. The extension finds the collector on PATH or in a standard installation directory. If it cannot find it, select the installed executable in the file picker.
- Approve this computer in the opened browser. Compare the browser code with the code in the TokenTrace Setup output panel. Setup uses the hosted TokenTracing service; choose Change service URL for your own service.
- Select your agent and choose Launch. This opens its normal interactive terminal with tracking alongside it. Exit the agent to see the tracking summary.
The collector creates database and credential paths and keeps encryption keys in the operating system credential store. Guided setup and status require no manual paths, key environment variable, or VS Code restart. Setup is cancellable; retry the button to resume an interrupted approval. Existing managed state and keys are reused.
The collector currently supports fixture-tested adapters for Codex, Claude Code, OpenCode, and Gemini CLI. Live vendor/version certification is pending. Recorded usage covers supported agents launched through the collector; it does not measure all AI activity on your computer.
The TokenTrace activity bar icon opens a sidebar that follows the web workspace design (same tokens, light and dark):
- Status checks the managed local outbox after setup, on first sidebar opening, and when you press Refresh. There is no background polling. An active agent owns the profile lock; stop it before checking the queue. An inaccessible profile does not invalidate a previously verified connection.
- Connect this computer provides guided setup, a custom service option, agent selection, and launch.
- Advanced contains readiness details, diagnostics, manual settings, and legacy manual pairing and queue inspection.
The webview has no network access, no inline script or style, and renders everything with textContent. It sends only fixed message types; the extension host rebuilds every terminal command from settings and a fixed agent list, so the webview can never supply command text.
Develop and test
Build with npm run build --workspace=tokentrace-vscode. Unit tests (npm test -- apps/vscode-extension) cover the collector boundary and the view model. To try the UI, open this directory in VS Code and press F5 (.vscode/launch.json builds first and starts an Extension Development Host).
Advanced manual configuration
The application-scoped tokentrace.endpoint and collectorPath settings override the hosted service and automatic collector discovery. The workspace must be trusted before running the collector.
For the legacy manual workflow only, configure absolute databasePath and authPath settings and launch VS Code with TOKENTRACE_OUTBOX_KEY set (64 hex characters). Never store this secret in settings. Under Advanced, enter a one-use dashboard pairing code and choose Pair collector. Manual pairing does not start collection or migrate existing data into a managed profile.
Use the matching Windows, macOS or Linux executable; see platform setup. The portable build command places it in collector/bin/tokentrace.exe on Windows and collector/bin/tokentrace on macOS/Linux. Select that file during guided setup. Rebuild or update an older collector to use status --managed.
Use Check manual queue or TokenTrace: Manual Collector Status for the explicitly configured database. TokenTrace: Collector Status also uses the manual queue when databasePath is configured; the sidebar Refresh always checks the managed queue. Pairing codes travel through the child process environment, never command arguments or extension logs.
TokenTrace: Collector Status describes the local outbox queue only. Pending counts, quarantines, and blocked state do not establish adapter health or complete telemetry coverage. No authenticated IPC protocol is implemented in this MVP.
