@tokentop/agent-copilot-cli

tokentop agent plugin for GitHub Copilot CLI (GitHub's terminal coding agent). Parses session data, tracks token usage, and provides real-time activity monitoring.

Capabilities

| Capability | Status | |-----------|--------| | Session parsing | Yes | | Credential reading | No | | Real-time tracking | Yes | | Multi-provider | No |

How It Works

This plugin reads GitHub Copilot CLI's local session files from ~/.copilot/session-state/ and process logs from ~/.copilot/logs/ to extract:

• Session metadata (start time, project path, summary)
• Token usage per message (estimated from CompactionProcessor deltas in process logs; real assistant.usage data when available)
• Model identification from any event's data.model field — no hardcoded model list required
• Real-time file watching for live session updates

Token Estimation

Copilot CLI marks token-bearing events (assistant.usage, session.shutdown) as ephemeral — they're tracked in-memory for the /usage command but never written to events.jsonl (see copilot-cli#1152). To work around this, the plugin parses CompactionProcessor entries from process logs (~/.copilot/logs/process-*.log), which report the running token count of the conversation context before each model request.

Token estimation uses a priority chain:

1. Real usage data — assistant.usage events (used automatically if Copilot CLI begins persisting them)
2. CompactionProcessor deltas — input tokens from the CP entry, output tokens from the delta between consecutive entries
3. Content-length fallback — content.length / 4 heuristic (last resort when no process log is available)

Each process log maps 1:1 to a session via the Workspace initialized: {session-uuid} line. The compaction index is built once and cached for 60 seconds.

Model Tracking

The plugin identifies models generically by scanning all event types for a data.model field — no hardcoded model names or event types. This means new models (e.g. gpt-5.3-codex) are picked up automatically without code changes. The resolution priority is:

1. assistant.message → data.model
2. session.model_change timeline (timestamp-based)
3. Any event with data.model (e.g. tool.execution_complete)
4. Process log Using default model: line
5. 'unknown'

If a user switches models mid-session, each model segment appears as a separate entry — matching the behavior of the Claude Code and OpenCode plugins.

Install

This plugin is bundled with tokentop — no separate install needed. If you need it standalone:

bun add @tokentop/agent-copilot-cli

Requirements

• GitHub Copilot CLI installed (~/.copilot directory must exist)
• Bun >= 1.0.0
• @tokentop/plugin-sdk ^1.3.0 (peer dependency)

Permissions

| Type | Access | Paths | |------|--------|-------| | Filesystem | Read | ~/.copilot/session-state/, ~/.copilot/logs/ |

Development

bun install
bun run build
bun test
bun run typecheck

Contributing

See the Contributing Guide. Issues for this plugin should be filed on the main tokentop repo.

License

MIT