cc-connect/docs/plans/2026-03-12-usage.md

Usage Command Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add a built-in /usage command with a generic agent usage-reporting interface, and implement the first provider-backed version for Codex using ChatGPT OAuth quota data.

Architecture: The engine gains a new built-in command that depends only on an optional UsageReporter interface. Agents that implement the interface return a generic UsageReport; the engine formats that into text. The Codex agent reads ChatGPT OAuth credentials from ~/.codex/auth.json, calls the wham/usage endpoint, and maps the response into the generic structure.

Tech Stack: Go, built-in command dispatch in core/engine.go, optional agent interfaces in core/interfaces.go, HTTP/JSON via Go standard library, table-driven tests.

---

Task 1: Add generic usage-reporting types

Files:

• Modify: core/interfaces.go

Step 1: Add the failing interface usage surface

Define:

• UsageReporter
• UsageReport
• UsageBucket
• UsageWindow
• UsageCredits

The structure should cover provider identity, plan/tier, generic allowed/limit-reached flags, one or more windows, and credits metadata.

Step 2: Run targeted compile check

Run: go test ./core/... Expected: compile failures in engine/tests until the command layer is wired.

Step 3: Keep the types minimal

Do not add provider-specific fields unless they are broadly useful.

Step 4: Re-run compile check

Run: go test ./core/... Expected: still failing only because /usage command is not yet fully integrated.

Task 2: Add /usage built-in command and output formatter

Files:

• Modify: core/engine.go
• Modify: core/i18n.go
• Test: core/engine_test.go

Step 1: Write/extend failing tests

Add tests for:

• /usage dispatch to a supporting agent
• unsupported-agent message
• successful output formatting with representative report data

Step 2: Run the targeted tests

Run: go test ./core/... -run 'Test.*Usage|TestHandleCommand' Expected: FAIL because the command is not registered yet.

Step 3: Implement command plumbing

Update:

• built-in command registration
• command dispatch switch
• bot command listing
• help/i18n text

Add a cmdUsage implementation that:

• type-asserts UsageReporter
• fetches usage with timeout
• formats a concise text response

Step 4: Run the targeted tests again

Run: go test ./core/... -run 'Test.*Usage|TestHandleCommand' Expected: PASS

Task 3: Implement Codex usage retrieval against ChatGPT OAuth

Files:

• Modify: agent/codex/codex.go
• Add or Modify: agent/codex/usage.go
• Test: agent/codex/usage_test.go

Step 1: Write failing tests for the mapper/fetcher

Cover:

• successful parsing of a representative wham/usage payload
• missing auth.json
• missing token/account fields
• HTTP error response

Step 2: Run the targeted tests

Run: go test ./agent/codex -run 'Test.*Usage' Expected: FAIL because the implementation does not exist yet.

Step 3: Implement minimal production code

Add:

• auth file path resolver
• auth JSON loader
• HTTP request builder
• response DTOs
• mapping into core.UsageReport

Prefer dependency injection for:

• auth file path / reader
• HTTP client / transport

So tests avoid live network and real user files.

Step 4: Run the targeted tests again

Run: go test ./agent/codex -run 'Test.*Usage' Expected: PASS

Task 4: End-to-end verification and cleanup

Files:

• Modify: README.md
• Modify: README.zh-CN.md
• Modify: CHANGELOG.md

Step 1: Document the new command

Add /usage to command lists and a short explanation that support depends on the current agent.

Step 2: Run focused test suites

Run: go test ./core/... ./agent/codex Expected: PASS

Step 3: Run broader verification

Run: go test ./... Expected: PASS, or identify unrelated pre-existing failures clearly.

Step 4: Commit

Run:

git add core/interfaces.go core/engine.go core/i18n.go core/engine_test.go agent/codex/codex.go agent/codex/usage.go agent/codex/usage_test.go README.md README.zh-CN.md CHANGELOG.md docs/plans/2026-03-12-usage-design.md docs/plans/2026-03-12-usage.md
git commit -m "feat: add usage command for codex oauth"