ralphctl: Instructions file for Claude Code

RalphCTL — Agent Harness for AI Coding Tasks

Node.js 26 (published floor 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)
pnpm eval <check|run|compare|report>  # opt-in prompt/model eval harness (scripts/eval/); never part of verify — see .claude/docs/EVALS.md

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: contributors get Node 26 + pnpm 12 from mise.toml; the published package supports Node 24+ (engines.node). 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.