ralphctl CLAUDE.md

RalphCTL — Agent Harness for AI Coding Tasks

Node.js 24 + TypeScript + Ink TUI. Five AI provider backends (Claude Code / GitHub Copilot / OpenAI Codex / OpenCode / Grok). Grok is xai-grok, binary grok. OpenCode is an aggregator — its model ids are provider/model and its catalog is discovered at runtime via opencode models, so it is the one backend whose reachable models are not a static list. The TUI is the primary surface; the CLI exposes inspection + one-shot operations only.

Version is read from package.json via JSON import attribute in src/business/version/cli-metadata.ts. Both commander.version() and the npm-update poll consume the same constant — bin and registry cannot drift.

Build & Run

pnpm install
pnpm dev <command>     # tsx, no build needed
pnpm dev               # bare → Ink TUI (primary surface)
pnpm build             # tsup + tsx scripts/build-assets.ts → dist/cli.mjs + dist/{prompts,skills,manifest.json}
pnpm typecheck         # tsc --noEmit
pnpm lint              # ESLint
pnpm test              # vitest
pnpm coverage          # vitest run --coverage (ad-hoc threshold check; not in verify)
pnpm verify:coverage   # alias for pnpm coverage
pnpm format:check      # prettier
pnpm deadcode          # knip (clean tree exits 0)
pnpm skills:update     # re-vendor upstream SKILL.md into scripts/vendor/skills/ for review (maintainers only)

Before every commit, run /verify (wraps pnpm typecheck && pnpm lint && pnpm test). All three must pass. Pre-commit hook runs lint-staged (ESLint + Prettier on staged files); pnpm lint:fix / pnpm format patch.

Requirements: Node.js 24+ (managed via mise.toml), pnpm 10+, one of the supported AI CLIs in PATH and authenticated.

Read on demand

Not auto-imported — open with the Read tool when the work touches the area.

• .claude/docs/ARCHITECTURE.md — module layout, ports, repository interfaces, data models, error tables
• .claude/docs/KERNEL-DESIGN.md — chain framework reference (element / leaf / sequential / loop / guard)
• .claude/docs/WORKFLOWS.md — sprint lifecycle + state table, two-phase planning, gen-eval loop, TUI navigation, setup/verify, branch management
• .claude/docs/AI-SETTINGS.md — settings.ai shape, effort resolution, presets, fail-fast PATH check
• .claude/docs/SECURITY.md — permission model, cross-process lock, spawning, AbortError rule, skills, refine write-back, file-based provider contract
• .claude/docs/PERFORMANCE.md — scheduler / parallel waves, rate-limit retry, iteration budget, plateau escalation, progress journal, learning ledger, env vars, release procedure
• .claude/docs/REQUIREMENTS.md — acceptance-criteria checklist
• .claude/docs/DESIGN-SYSTEM.md — TUI tokens, components, copy rules
• .claude/docs/MANUAL-TEST-PLAYBOOK.md — manual smoke-test script
• .claude/docs/HARNESS-PRINCIPLES.md — distilled harness research (Anthropic + martinfowler.com); consult before structural changes to the chain framework, flow registry, or provider engine
• .claude/docs/RESEARCH-REFERENCES.md — verified source table (papers/articles → claims → where used), adopted techniques, and rejected ideas with reasons; consult before adding a citation or re-proposing a technique
• .claude/docs/diagrams/ — Mermaid sequence / data-flow diagrams: chain framework, flow lifecycle, sprint lifecycle, task lifecycle, AI-session data flow