Tokenpool Scout

Tokenpool Scout is an opt-in macOS and Windows companion that reports Codex and Claude Code quota information to a Tokenpool server. It is open source, has zero runtime dependencies, and has no automatic update path.

Version 0.3.0 was the trust-reset release. The current approved 0.3.4 keeps that model, the bounded Claude Team CLI quota fallback and the macOS credential hardening, while adding deterministic repair and redacted diagnosis. A server response is data only: it cannot tell Scout to download a file, run a command, or replace its code. Every future update requires the employee to run an exact-version command.

Pairing is the employee's opt-in to collection and signed-in-team visibility. There is no separate private/admin telemetry mode; revoke the device to stop future accepted reports.

See SECURITY.md for the threat model and a plain-language explanation of the controls.

Requirements

• macOS or Windows
• Node.js 22.5 or newer
• Codex CLI for Codex quota data on Windows; on macOS Scout can also discover the Codex binary bundled with the ChatGPT app
• Claude Code for Claude quota data. Team subscriptions need the standalone native claude CLI for the fallback; Claude Desktop or a VS Code extension alone does not install the terminal command.

Install

Create a one-use pairing code on the Tokenpool profile page, then run the exact version shown by the site:

This is one line and works in both macOS Terminal and Windows PowerShell:

npx --yes --ignore-scripts @rockbite/[email protected] install --server https://tokenpool.example.com --code tkp_pair_...

The guided install does five visible things:

1. copies the exact npm package out of npx's temporary cache into a stable per-user app directory;
2. exchanges the one-use pairing code and stores the resulting device secret in the operating system's protected credential store;
3. connects Claude Code's local status line and permits the Team-only Claude CLI quota fallback when eligible;
4. registers a per-user background job.
5. runs an immediate collection cycle and reports success only after Tokenpool accepts the first authenticated heartbeat with HTTP 200.

If native credential storage fails after the one-use code is consumed, Scout uses the still-in-memory credential once to revoke the provisional server device. If that compensation cannot reach Tokenpool, the dashboard retains a visible setup-incomplete row instead of treating it as a working installation.

Use --without-claude if you do not want the Claude status line changed or the Team CLI fallback run. Scout can still read the two documented Claude plan-label fields locally. Local Claude transcript token-count collection is a separate permission and remains off unless --claude-transcripts is explicitly included.

Never replace the pinned version with @latest. The website should always give an exact approved version.

Commands

Run these through the same pinned package version:

# Show local state and collector health
npx --yes --ignore-scripts @rockbite/[email protected] status

# Verify the installed release files and show the complete trust/data report
npx --yes --ignore-scripts @rockbite/[email protected] verify

# Manually install an approved exact version, retaining pairing, queue and preferences
npx --yes --ignore-scripts @rockbite/[email protected] update

# Repair the package, durable Node runtime, OS job, queue and heartbeat
npx --yes --ignore-scripts @rockbite/[email protected] repair

# Print redacted diagnostics and return a stable machine-readable exit code
npx --yes --ignore-scripts @rockbite/[email protected] doctor

# Stop and later resume reporting
npx --yes --ignore-scripts @rockbite/[email protected] pause
npx --yes --ignore-scripts @rockbite/[email protected] resume

# Separate opt-in for local Claude transcript token-count totals
npx --yes --ignore-scripts @rockbite/[email protected] transcripts enable
npx --yes --ignore-scripts @rockbite/[email protected] transcripts disable

# Stop the background job and restore the previous Claude status line
npx --yes --ignore-scripts @rockbite/[email protected] uninstall

# Restore Claude's prior status line and remove app, state and credential
npx --yes --ignore-scripts @rockbite/[email protected] uninstall --purge

# Also ask the Tokenpool server to revoke this device before local deletion
npx --yes --ignore-scripts @rockbite/[email protected] uninstall --purge --revoke

update is intentionally just another command. Scout never invokes it itself. In 0.3.4 it performs the same comprehensive lifecycle recovery as repair: stage and verify the selected package, validate SQLite and the credential, repair the durable runtime and OS job, preserve local state, and require an accepted heartbeat. repair --server ... --code ... additionally replaces a missing or rejected credential using a fresh one-use pairing code. The state database is outside the app directory, so pairing, queued observations, cursors and preferences survive.

Install/update refuses to pin a Node executable from an npm extraction cache or temporary directory. It records a durable absolute Node path and uses that same runtime for Claude integration and the background-job definition; verify reports if the saved job no longer matches it.

Background behavior

New macOS installs use a per-user LaunchAgent that runs one collection cycle every 10 minutes. Windows uses a per-user, limited-privilege Scheduled Task with the same 10-minute run-once model. Neither needs administrator privileges and neither is a system service.

After a cycle has attempted its heartbeat, a running Scout verifies a background definition that is still present and repairs it if it is modified or unloaded. A completely absent job cannot run its own repair and remains a dashboard-guided repair case.

The one-time 0.2.5 to 0.3.0 migration deliberately leaves an existing macOS LaunchAgent in its compatible persistent-daemon mode. This avoids silently rewriting another machine setting during the final migration. The daemon is safe to keep: the 0.3.0 runtime contains no updater and ignores server version metadata. Running a later manual install or update command converts that job to the 10-minute run-once definition; no new Scout version is required.

The lower-level commands used by the jobs remain available:

tokenpool-scout run-once [--dry-run]
tokenpool-scout start
tokenpool-scout setup-claude
tokenpool-scout pair --server <url> --code <tkp_pair_...>

run-once --dry-run collects locally and prints the exact batch without making a Tokenpool ingest request. Eligible provider collectors still run, so the Claude CLI may contact Anthropic. start is the compatibility foreground daemon used by an existing pre-0.3.0 macOS LaunchAgent.

What is collected by default

From Codex, Scout starts a local codex app-server child over private stdio. It does not expose that server on a port, proxy arbitrary methods, read ~/.codex/auth.json, or call OpenAI directly. It invokes only:

• account/read, solely to derive a one-way account scope digest;
• account/rateLimits/read, for used percentage, reset times, window lengths, reset-credit count and plan label;
• account/usage/read, for provider-reported daily token totals.

From Claude Code, Scout collects:

• quota used percentage and reset times delivered to Claude's local status line command;
• for a logged-in Team subscription, the Current session and Current week (all models) quota windows returned by a bounded native Claude CLI fallback;
• a short plan label derived from exactly oauthAccount.organizationType and oauthAccount.organizationRateLimitTier in ~/.claude.json.

The status-line wrapper makes no network requests. It records only numeric quota windows and then renders the employee's previous status line, if one was configured. Setup preserves the complete original statusLine object, including fields Scout does not know, and keeps the prior command locally for chaining. Purge restores the full value only while Scout still owns the active command; an employee's later replacement is left untouched. Updating a 0.3.0 install recovers the full original value from its pre-install settings backup. Missing or contradictory legacy recovery evidence leaves the setting and backups untouched rather than guessing. Scout never prints, logs, or uploads the prior command/object.

The Team fallback first runs claude auth status --json, retaining only the logged-in flag, authentication method and subscription type. When that confirms a Claude.ai Team login, Scout runs:

claude --safe-mode -p /usage --output-format json --no-session-persistence

It runs without a shell, with a 30-second timeout, a 128 KiB output limit, a C locale and UTC timestamps, normally every 30–35 minutes. Scout accepts only a successful zero-turn, zero-API-duration, zero-cost result and discards all raw authentication and /usage output after parsing the two allowlisted windows. It never reads Claude credential files or persists a Claude session. The Claude-owned command may contact Anthropic. Scout refuses this fallback inside a nested Claude session or when API/provider-routing override variables are present; it does not remove or bypass those variables.

On Windows, Claude invokes a fixed PowerShell bridge which passes its UTF-8 JSON to the installed JavaScript wrapper with the saved Node path. It does not use Invoke-Expression, execute the JSON, or resolve a moving runtime from PATH.

Separate transcript permission

Claude's local JSONL transcripts can contain prompts, responses, tool output and file paths. Scout therefore does not open or enumerate the transcript directory by default.

An employee can explicitly run transcripts enable (or install with --claude-transcripts) to contribute daily Claude token-count totals. The allowlist parser retains only message/request ids, timestamp and four numeric token counters. It never stores or uploads line text. transcripts disable stops that access without disabling Claude quota reporting and immediately deletes queued Claude transcript rows, local message counters, cursors and the local acknowledgement cache. History already accepted by the server is not silently deleted by this local command.

What is never uploaded

• prompts, responses, tool calls or tool output;
• transcript text, file paths, projects, branches or model names;
• provider email addresses, raw account ids, raw machine ids or credit ids;
• raw Claude authentication or /usage command output;
• the Claude status-line command, Scout logs or local configuration contents.

The one-time pairing code is sent only to the HTTPS /pair endpoint. The resulting device credential is sent only in the HTTPS Authorization header for ingest and revocation. Neither secret is placed in a telemetry payload, Scout log or local configuration file. The short-lived, single-use pairing code necessarily appears in the install command the employee chooses to run.

Absence of data is reported as unknown, stale, disabled or opted out; never as a fabricated zero.

Local storage

macOS

• App: ~/Library/Application Support/Tokenpool Scout/app
• State/queue/logs: ~/.tokenpool-scout
• Background job: ~/Library/LaunchAgents/com.rockbite.tokenpool-scout.plist
• Device credential: macOS user Keychain, service tokenpool-scout

The old ~/.tokenpool-scout state location is retained on purpose so the final 0.2.5-to-0.3.0 delivery keeps its pairing and queued data.

Windows

• App: %LOCALAPPDATA%\TokenpoolScout\app
• State/queue/logs: %LOCALAPPDATA%\TokenpoolScout
• Background job: per-user Scheduled Task TokenpoolScout
• Device credential: DPAPI current-user ciphertext under the state credential directory; only the same Windows user can decrypt it

TOKENPOOL_SCOUT_HOME, TOKENPOOL_SCOUT_APP_HOME and TOKENPOOL_SCOUT_PLIST_PATH override paths for isolated library-level tests. They must not be used for ordinary installs. All install, update, pause, resume and uninstall CLI operations refuse to run while any override is set, so an environment variable cannot turn Scout into a generic installer or recursive delete tool. Test sandboxes must be cleaned up explicitly by their tests.

Verification

verify reports:

• installed version and app path;
• source repository and protected release-tag reference;
• SHA-256 of the embedded release manifest;
• every missing, modified or unexpected shipped file;
• whether the background job, Claude status line and native Claude CLI are active;
• upload origin and native credential-store type;
• each enabled/disabled data category;
• the permanent automatic-update-off invariant.

An npm name@version is immutable after publication. The package is public and MIT licensed, has a strict files allowlist, zero dependencies and no install, postinstall or other lifecycle script. Because the source repository is private, npm provenance is not claimed for 0.3.4. The release tag, reviewed source and published manifest hash are the comparison points instead.

Complete removal

uninstall --purge stops the job, restores the complete previous Claude statusLine value only if the current command is still Scout-owned, removes Scout-created Claude backup files, deletes the native credential, state directory, stable app and the well-known legacy ~/tokenpool-scout managed install when applicable.

If another tool or the employee changed Claude's status line after Scout was installed, purge leaves that newer command untouched. --revoke attempts server revocation first; a network failure never prevents explicit local deletion and is clearly reported so the device can be revoked on the profile.

Development

cd tokenpool-scout
node --test test/*.test.js
node bin/scout.js --version

The package uses only Node built-ins and has no build step.