Architecture

🏗️ Architecture

Component-Service architecture with clean data flow from auth to display.

---

📁 Project Structure

opencode-codex-quota/
├── package.json
├── tsconfig.json
├── biome.json
├── src/
│   ├── index.ts              # Plugin entry point, tool definition
│   ├── types.ts              # All TypeScript interfaces + DisplayMode
│   ├── services/
│   │   ├── auth-reader.ts    # Read auth.json, parse JWT, extract account_id + email
│   │   └── api-client.ts     # Call wham/usage endpoint, return typed QuotaResponse
│   └── formatter/
│       ├── markdown.ts       # Transform QuotaResponse → raw Markdown string
│       └── errors.ts         # Error codes → Markdown error messages
└── tests/
    ├── auth-reader.test.ts
    ├── api-client.test.ts
    ├── markdown.test.ts
    ├── errors.test.ts
    ├── index.test.ts
    └── integration.test.ts

---

🔄 Data Flow

User/Agent → /codex_quota [mode?]
  │
  ├─ Slash command path:
  │   └─ command.execute.before hook
  │       └─ Injects wrapper instruction with mode argument
  │           └─ LLM calls codex_quota tool
  │
  └─ Direct tool path:
      └─ Plugin tool execute()
          │
          ├─ 1. AuthReader.read()
          │     └─ Read auth.json
          │         └─ Find OAuth entry (codex → openai → chatgpt → opencode)
          │             └─ Parse JWT → { token, accountId, email }
          │
          ├─ 2. ApiClient.query(token, accountId)
          │     └─ GET chatgpt.com/backend-api/wham/usage
          │         └─ Validate response → QuotaResponse
          │
          └─ 3. Formatter.format(response, mode)
                └─ Build Markdown sections
                    └─ Conditional includes
                        └─ Raw Markdown string → OpenCode TUI (Glamour)

---

🧩 Components

AuthReader (src/services/auth-reader.ts)

Reads ~/.local/share/opencode/auth.json, finds OAuth credentials, parses JWT.

Function	Purpose
readAuth(path?)	Read auth.json, find valid provider, return AuthResult
parseJwt(token)	Decode JWT payload, extract chatgpt_account_id + email

Provider key priority: codex → openai → chatgpt → opencode (first-match-wins)

ApiClient (src/services/api-client.ts)

Calls the ChatGPT quota API with OAuth token.

Function	Purpose
queryQuota(token, accountId)	GET wham/usage, validate schema, return ApiResult

Timeout: 10 seconds (AbortController)

Formatter (src/formatter/markdown.ts)

Transforms typed API response into display Markdown.

Function	Purpose
formatQuota(response, mode)	Main entry — routes to compact or full formatter
buildProgressBar(percent)	12-char progress bar with clamping
formatResetClock(timestamp)	Local clock string (same-day or with date)

Error Formatter (src/formatter/errors.ts)

Maps error codes to user-friendly Markdown messages.

Function	Purpose
formatError(code, partialData?)	E1–E11 → formatted Markdown error

---

🔌 Plugin API Contract

Entry Point (src/index.ts)

export default {
  id: "opencode-codex-quota",
  server: codexQuotaServer,
} satisfies PluginModule

Hooks

Hook	Purpose
config	Registers /codex_quota command with template: "" and subtask: true
command.execute.before	Reads input.arguments, injects wrapper instruction with mode
tool.codex_quota	The actual quota tool — accepts optional mode arg

Slash Command Flow

User types: /codex_quota compact
  ↓
command.execute.before hook fires
  ↓
Reads arguments → "compact"
  ↓
Resolves mode → "compact"
  ↓
Injects instruction: "Call the codex_quota tool now with mode=compact..."
  ↓
LLM receives instruction, calls tool
  ↓
Tool returns Markdown → TUI renders

---

🔧 Tech Stack

Aspect	Detail
Language	TypeScript (strict)
Runtime	Node.js >= 18
Plugin SDK	@opencode-ai/plugin (Zod-based tool.schema)
Test Framework	Vitest
Linter	Biome
Build	tsc → dist/
Dependencies	Zero runtime — only @opencode-ai/plugin (peer)

---

📖 Next Steps

• Usage — See the plugin in action
• Technical-Reference — Detailed type definitions and API spec
• Development — Set up for local development