claude-office: Instructions file for Claude Code

CLAUDE.md — Claude Office

What is this?

Claude Office is a statusline plugin for Claude Code that shows plan quota, real-time costs, monthly saving, tool activity, agent tracking, and todo progress. It runs as a stateless single-shot process invoked by Claude Code every ~300ms.

Hard rules

These rules are non-negotiable. Follow them exactly.

Bun only — zero Node.js APIs

• All file I/O must use Bun APIs: Bun.file(), Bun.write(), Bun.stdin, Bun.file().stream(), Bun.file().slice()
• NEVER use Node.js: no fs, no readline, no stream, no http, no child_process
• Exception: path and os from Node.js are fine (Bun provides compatible implementations)
• TypeScript runs directly via bun run — no build step, no bundler, no transpiler
• Use bun run typecheck (runs tsc -p tsconfig.json) to validate types

Performance budget: 300ms max

• Claude Code kills the statusline process after 300ms — every code path must complete within this
• Cache hit path must be <5ms — this is the common case (~95% of invocations)
• Cache miss path must be <200ms — network + file I/O + parsing
• Never block on a single slow operation — use Promise.all() to parallelize independent work
• Never do synchronous file I/O in the hot path

ANSI colors: 24-bit RGB only

• Use \x1b[38;2;r;g;bm format — no 16-color ANSI, no 256-color fallback
• All colors are defined in the C object in render.ts via the c(r, g, b) helper
• Always reset with \x1b[0m (the RST constant) after colored text

Non-breaking spaces

• Use \u00A0 (non-breaking space) between statusline elements to prevent terminal whitespace collapsing
• The S constant in render.ts is \u00A0 — use it instead of regular spaces in output

Project structure

src/
  statusline/               # Statusline plugin (stateless, single-shot)
    index.ts                # Entry: stdin -> config -> [quota, usage, transcript] -> render -> stdout
    stdin.ts                # Parse Claude Code's stdin JSON (model, context window, transcript path)
    config.ts               # Config loader with presets (full/minimal), mtime-cached
    usage-scanner.ts        # Token cost aggregation from JSONL files (30s cache, per-file mtime tracking)
    render.ts               # Modular ANSI renderer with extracted tools/agents/todos functions
    transcript.ts           # Incremental transcript parser (10s cache, byte-offset tracking)
  data/
    types.ts                # QuotaData type definition
    quota-api.ts            # Anthropic OAuth usage API + automatic token refresh (60s cache)
.claude-plugin/
  plugin.json               # Claude Code plugin metadata (name, commands, version)
  marketplace.json          # Plugin marketplace listing
skills/
  setup/
    SKILL.md                # /claude-office:setup — configures statusline in settings.json
  configure/
    SKILL.md                # /claude-office:configure — interactive display configuration