Stop blaming the model. Fix the process.
Quest is a portable framework that coordinates specialized AI agents (planner, reviewers, builder) in isolated contexts with human approval gates. Two different models (Claude + GPT) review independently, an arbiter filters noise, and you approve before anything gets built.
Copy it into any repo. Tear it apart and study it. It's built for learning, experimentation, and real work.
Part of the Candid Talent Edge initiative by KjellKod
Watch the Quest Demo | Read the Honest Analysis | View the Portfolio Dashboard
You → Planner → Reviewers → Arbiter ──→ Builder → Reviewers → Arbiter → Done
(Claude) │ ▲ (Claude) │ ▲
(Codex) │ │ (Codex) ▼ │
iterate ───────┘ │ Fixer ────────┘ │
│ │
GATE: you approve GATE: you approve
Where you spend your time: The beginning and the end. You shape the plan, approve it, then validate the built result. Before build starts, Quest now presents a concise plan summary and can work with you to sharpen it diligently: challenging assumptions, walking tradeoffs, and locking down what will actually be built. That improves the plan and, as a useful side effect, gives the orchestrator a sharper understanding of the implementation before it hands work to the builder. Quest handles the middle.
For lighter tasks, solo mode uses a single reviewer, same pipeline, fewer stages, faster turnaround.
Make sure you have claude and/or codex installed. Ideally you have both, but you'll do fine with one of them.
Download the installer
curl -fsSL https://raw.githubusercontent.com/KjellKod/quest/main/scripts/quest_installer.sh -o quest_installer.shGive it permission to execute
chmod +x quest_installer.shRun the installer, you can preview without changes if you add --check
./quest_installer.sh In claude code/cli:
/quest "Add a loading skeleton to the user list"In codex cli:
$quest "Add a loading skeleton to the user list"That's it. Quest evaluates complexity, asks clarifying questions if needed, and routes to solo or full workflow. Before implementation, you get a plan summary menu: walk through the phases, sharpen the plan with adversarial Q&A, or proceed to build. You approve at each gate.
Recommended: Add both Codex CLI and Claude CLI for dual-model reviews. See the Setup Guide for full instructions, which include using either Codex or Claude as the orchestrator.
⚠️ Don't skip the one-time machine setup. When Codex orchestrates, Claude roles default to the background-agent transport (claude --bg), which bills to your Claude subscription. Quest sends the initial bg prompt over stdin (required since Claude Code 2.1.191). Without the one-time setup —claude login, accept bypass mode once, CLI ≥ 2.1.143 — Quest stops and asks you to fix bg or explicitly choose theclaude --printbridge, which bills to the metered API pool after June 15, 2026.
Quest enforces spec → plan → build. You can start rough, Quest asks clarifying questions to fill gaps.
| Input level | What you provide | What happens |
|---|---|---|
| Rough idea | "add dark mode" |
Quest asks questions (max 10), then plans |
| Idea with context | "add dark mode, persist in localStorage, respect OS preference, toggle in header" |
Plans with clear direction |
| Structured spec | Doc with intent, constraints, acceptance criteria | Tight plan on first pass |
Say "just go with it" anytime to skip questions and proceed with assumptions. See the Input Routing Guide for details.
# Scale from simple to complex
/quest "Add a loading spinner to the save button"
/quest "Implement user preferences with localStorage, follow idea document <path> and our RFC ..."
/quest "Build a real-time collaboration system, plan phases first, don't implement yet"
# Resume, redirect, swap models
/quest feature-x_2026-02-04__1430
/quest feature-x_2026-02-04__1430 "re-plan using only claude"
/quest feature-x_2026-02-04__1430 "re-plan using <model-id>"
/quest 2026-02-04_1430__feature-x "Don't resume from building-phase, read <doc> and let's re-plan with this insight"
# Point to specs, tickets, or docs
/quest "implement docs/specs/notifications.md"
/quest "implement PROJ-1234" # with Jira MCP
# Generate competing plans and pick the best
/quest "migrate to SQLite, zero-downtime, dual-write pattern"
/quest "migrate to SQLite, minimal changes, feature-flag cutover"Quest IDs default to feature-x_2026-02-04__1430; set quest_id_format to date-first in .ai/allowlist.json to create new IDs like 2026-02-04_1430__feature-x. Resume accepts both formats.
Abort anytime, resume later. State persists in .quest/<id>/state.json.
Quest is artifact-driven, not chat-history driven. state.json, handoff.json, plans, reviews, and logs are the durable contract, so a run can recover after an outage, token/session exhaustion, crash, or context loss. If Claude is unavailable, start Codex and run $quest <quest-id>; if Codex is unavailable, start Claude Code and run /quest <quest-id>. Quest resumes from .quest/<id>/state.json and the existing phase artifacts instead of depending on the original transcript.
Resume applies to in-flight quests (directories under .quest/<id>/). A completed quest is archived to .quest/archive/<id>/ with its journal entry in docs/quest-journal/ — archived quests are finished history, not resumable runs; start a new quest to build on their outcome.
For advanced patterns (phased execution, plan comparison, model mixing), see the Quest Presentation.
Kjell: My personal approach for things like doc2md or the multiple MCP and CLI tools I've built, is to collect references, ideas and start with an analysis quest with the stated goal of creating a roadmap that delivers the
functionalityor the whole feature or app. Then use each phase in the roamap as a new quest.
| Role | What it does |
|---|---|
| Planner | Explores the codebase and writes the implementation plan |
| Plan Reviewer A / B | Independently challenge the plan |
| Arbiter | Synthesizes plan reviews and decides approve or iterate |
| Builder | Implements the approved plan and runs validation |
| Code Reviewer A / B | Independently review the implementation |
| Review Arbiter | Converts review findings into canonical decisions |
| Fixer | Applies bounded fixes before the next review pass |
See .ai/allowlist.json for the current role models and Codex reasoning effort.
Edit model policy in .ai/allowlist.json. In the Quest source repository, run python3 scripts/quest_sync_model_defaults.py after changing models or codex_fallback_model; this generates the compatibility DEFAULT_MODELS block in scripts/quest_runtime/orchestration.py and the static OpenCode role assignments. CI checks for drift. Do not hand-edit these generated model assignments. Installed projects may customize their allowlist independently; shipped fallbacks still fill omitted roles.
At startup, Quest expands the allowlist, applies per-quest overrides, and saves models and codex_reasoning_effort in .quest/<id>/orchestration.json. That file is the effective source of truth for that quest, so changing the allowlist does not rewrite an in-flight run.
Choose Customize for this quest only at startup to change one or more roles without editing repo defaults. The chooser accepts either format:
planner=<codex-model-id>, builder=<claude-model-id>
{
"models": {
"planner": "<codex-model-id>",
"builder": "<claude-model-id>"
}
}A direct JSON role map and a copied "models": {...} fragment are accepted too. Omitted roles keep their defaults. The chooser sends the submission to Quest's deterministic parser CLI instead of interpreting it conversationally. Quest rejects duplicate roles and applies the same model-token rules to both formats, then validates runtime-family availability and whether a role is used in the selected solo/full mode. A concrete model ID can still be rejected later by its provider if that account or client does not support it.
Model IDs select the runtime family: claude and claude-* use Claude; gemini and gemini-* use Antigravity; other IDs use Codex. Replace the example placeholders above with model IDs supported by your account. Runtime preflight does not prove access to every concrete model.
Claude-led Codex dispatch passes the saved model and effort through MCP. Codex-led dispatch passes them to local subagents using the controls exposed by the session. If explicit selection is unavailable, inheritance is acceptable only when the parent settings match; otherwise stop with the mismatch instead of silently using a different model. See the canonical dispatch contract.
codex_fallback_model supplies standalone /gpt defaults and the generated compatibility fallback for explicitly approved single-runtime continuation.
codex_reasoning_effort applies to all Codex roles. Set it in the allowlist for new quests, or explicitly edit the saved quest setting to change effort for subsequent dispatches. Supported levels depend on the selected model and runtime. Legacy quests with no setting retain runtime-default effort; resume never imports the current allowlist effort. Claude reasoning remains controlled by its runtime.
OpenCode uses generated static role models with its existing opencode/ provider prefix. Verify those IDs with your provider before use. Its static configuration does not automatically apply per-quest overrides or Codex effort; reconcile supported runtime settings with the saved quest configuration before dispatch, or stop on a mismatch. The primary orchestrator uses the model selected by the user.
Solo mode skips Reviewer B and the Arbiter. Same pipeline, just faster.
- Artifact-driven, agents communicate through written artifacts, not conversation. No chat history, no accumulated drift, no hallucinated context. Each agent reads evidence and produces evidence
- Clean context, each agent starts fresh with only the artifacts it needs
- Dual-model review, different models catch different blind spots
- Human gates, you approve before anything gets built
- Smart routing, evaluates complexity/risk, routes to solo or full workflow
- Smart intake, asks structured questions when your input needs more detail
- Full audit trail, every artifact saved in
.quest/ - Auditable replanning, every completed plan iteration is sealed before current artifacts are reused, and human changes invalidate prior approval through validated state transitions
- Multi-runtime, runs from Claude Code (
/quest), Codex ($quest), or OpenCode - Built-in UX rigor, when the router sees UI work it auto-attaches a canonical UX guidebook to the planner/builder/fixer and runs a stress-test rubric in code review. Invoke
/ux-reviewon any file, URL, or screenshot to get a P0–P3 critique with principle citations.
Autonomy is earned through constraints, not granted by capability. Context contamination is a system failure, not a user habit. Speed without rigor only accelerates failure.
Engineering principles baked into every agent:
- KISS — Prefer simple solutions over clever ones
- DRY — Extract common patterns, but not prematurely
- YAGNI — Don't add features until they're needed
- SRP — Each change, function or module should focusing on doing one thing
These aren't guidelines — they're the first thing every agent reads. AGENTS.md shapes how agents think, plan, review, and build. The process enforces the philosophy; the philosophy produces the quality.
Quest is built on a conviction: scaling AI output without scaling engineering discipline is a dead end. We don't trust single outputs, human or machine. We trust repeatable processes backed by evidence. The system makes correct behavior easy and incorrect behavior hard.
We're not replacing human judgment. We're amplifying it.
Read the full philosophy.
Per repo (recommended): Use the installer above.
Workspace umbrella (multi-repo): Install once in a parent directory, all repos underneath inherit Quest's config. See the Setup Guide.
Not recommended, but possible is also a manual copy: Grab .ai/, .skills/, .agents/, .claude/, .cursor/, .codex/, .opencode/, AGENTS.md, and DOCUMENTATION_STRUCTURE.md. See the Setup Guide.
- Setup Guide, prerequisites, Codex MCP, allowlist customization, one-time background-agent transport setup (subscription vs API billing)
- Quest Presentation, how it works with diagrams
- Input Routing Guide, complexity/risk evaluation and solo vs full workflow
- Philosophy, the full manifesto
- OpenCode Field Notes, multi-model testing and architecture comparison
- Architecture, platform direction and runtime contracts
- Portfolio Dashboard, live quest outcomes and journal entries
- UX Guidebook, canonical UX standards bundled with the ux-context skill so they travel with the install; auto-loaded for UI work
Public Domain (Unlicense). No warranty. See LICENSE.