Complete builder documentation
This guide covers installation, provider setup, slash-command navigation, project initialization, planning, autonomous execution, analysis, profiling, recovery, security controls, and release checks.
npm install -g codethon-clict/init/execute <goal>Quick Start
CodeThon is distributed as the `codethon-cli` npm package. Install it globally, then run `ct` from any project directory.
npm install -g codethon-cli
ctIf no provider is configured, CodeThon opens guided setup before entering the interactive workspace. After `ct` opens, use slash commands like `/init`, `/plan`, `/execute`, `/analyze`, and `/profile`.
Onboarding
First-run setup is designed for global npm users. It does not require editing `.env` files or browsing the repository source.
Interactive REPL
Running `ct` with no command opens the interactive workspace. Use `/` for command discovery and `/p` to narrow to planning/profile commands.
/Open slash-command suggestions./pFilter matching commands such as /plan and /profile./helpShow categorized help inside the REPL./initCreate or register the active project workspace./planStream roadmap and architecture output./execute <goal>Run the autonomous execution workspace./analyzeShow analysis stages and stream the project summary./profileRun static performance and maintainability profiling./inspectInspect the latest execution journal./replayReplay the latest event timeline.Commands
/onboardRun the full first-run provider setup wizard./auth addAdd and validate provider credentials./auth listShow configured providers and active model./auth test [provider]Verify provider credentials and reachability./auth switchSwitch active provider and model./modelBrowse available models and update the active model./doctorRun local environment, config, network, auth, and project checks./initCreate or register a project workspace./plan [goal]Stream roadmap and architecture generation./roadmapGenerate project phases, milestones, and priorities./architectDesign architecture, data flow, and technical choices./analyze [dir]Scan project structure and stream an AI summary./explain <file>Explain a file's purpose, risks, and architecture role./summarizeSummarize project health, blockers, and next actions./execute <goal>Run the autonomous OLED workspace with mission feed, trace, context, diff, and receipt./build [goal]Generate and apply code with build-error repair./autofixRun build/type checks and apply targeted fixes./debugAnalyze errors and stream fix guidance./run <cmd>Run a shell command through CodeThon policy gates./scaffold [dir]Generate a starter project from templates./profileFind performance issues and maintainability risks./reviewInspect current git changes./diffShow the full git diff./checkpointSave, list, and restore recovery points./recoverRebuild project context from local files./inspect [runId]Inspect a saved execution journal./replay [runId]Replay a run's event timeline./memory [query]Explore persistent project memory./analyticsShow execution reliability and productivity metrics./graph [dir]Visualize repository structure and dependency signals./deployGenerate deployment guidance./readmeGenerate or refresh README.md./launchGenerate demo script, submission copy, and launch assets./startupAnalyze product and go-to-market potential./learnAsk a concept question and get a guided tutorial.Providers
OPENAI_API_KEYStrong general coding and tool-use workflows.ANTHROPIC_API_KEYLong-context reasoning and doc-heavy projects.NVIDIA_API_KEYFree-tier friendly hosted open models.GROQ_API_KEYFast hosted inference for quick builder loops.DEEPSEEK_API_KEYReasoning-heavy planning and implementation.TOGETHER_API_KEYBroad hosted open-model catalog.nonePrivate local runtime at localhost.noneOpenAI-compatible local server workflows.Execution Loop
`/execute` runs the autonomous OLED workspace with a mission feed, mission-info panel, live activity stream, context inspector, diff inspector, agent matrix, execution journal, checkpoints, and final completion receipt.
/execute implement the pricing page and add tests
/inspect
/replay
/debug
/autofixThe workspace keeps the run on screen while drawers open over the current session. The footer now uses direct labels only: `Ctrl+M Mission` and `Ctrl+I Context`.
Ctrl+MOpen Mission Control: goal, progress, active agent, current file, and checkpoints.Ctrl+TOpen the live activity trace with tool calls, commands, results, and durations.Ctrl+IOpen Context Inspector to see files, memory entries, and context usage.Ctrl+DOpen Diff Inspector for files touched during the run.Ctrl+AOpen the agent matrix for Planner, Scout, Research, Builder, and Verifier status.EscClose the active drawer. If no drawer is open, cancel the active execution and return to the REPL.Ctrl+CCancel the active execution gracefully. A second deliberate press force-quits only if the command is stuck.Analysis And Profiling
`/analyze` shows the stages it is running and streams a formatted AI summary. `/profile` scans source files for complexity, deep nesting, long functions, memory leaks, N+1 patterns, and bundle-size risks.
/analyze
/profile
/summarizeSafety
Configuration
CodeThon stores CLI state outside the project source. Project recovery snapshots are local to the project when needed.
~/.codethonGlobal CLI config and project state.~/.codethon/projectsTracked CodeThon project metadata..codethon/recoveryProject-local recovery snapshots.OS keychainCredential storage when available, with fallback handling.Publishing
Before publishing a major version, run the same checks used for this release path.
npm run typecheck
npm test
npm run build
cd apps/cli && npm pack --dry-run
npm publish --access public