ACAP lets you point Claude at a requirements document and walk away. It handles the full pipeline: turning your PRD into structured prompt files, detecting your tech stack, and running coding agents that build your app feature by feature across as many sessions as it takes.
Pick the method for your platform.
macOS, Linux, or WSL (recommended, auto-updates):
curl -fsSL https://claude.ai/install.sh | bashWindows PowerShell (auto-updates):
irm https://claude.ai/install.ps1 | iexWindows CMD:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmdWindows also needs Git for Windows if you don't have it.
Homebrew (macOS/Linux):
brew install --cask claude-codeHomebrew won't auto-update. Run brew upgrade claude-code now and then to stay current.
WinGet (Windows):
winget install Anthropic.ClaudeCodeWinGet won't auto-update. Run winget upgrade Anthropic.ClaudeCode to get the latest.
VS Code or Cursor:
Install the Claude Code extension from the marketplace, or just search "Claude Code" in the Extensions panel (Cmd+Shift+X on Mac, Ctrl+Shift+X on Windows/Linux).
JetBrains (IntelliJ, PyCharm, WebStorm, etc.): Install the Claude Code plugin from the JetBrains Marketplace, then restart your IDE.
Check it worked:
claude --versionRun this once. Your credentials get stored and all ACAP scripts will use them automatically.
claude loginuv venv
source .venv/bin/activate
uv syncYou can skip activation and run directly with uv run ... if you prefer.
These plugins are optional but significantly boost what the coding agents can do — enabling systematic workflows, specialist subagents, and parallel execution across multiple context windows.
Superpowers gives the coding agents structured workflows for planning, TDD, debugging, code review, and subagent-driven development. It is installed as a slash command inside a Claude Code session (not in your terminal):
# Inside any Claude Code session (start one with: claude):
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
Takes effect in new sessions after install.
127+ specialist agents (TypeScript, Python, Rust, Go, React, backend, frontend, etc.) that the coding agents can delegate to automatically. Install via your terminal:
# Language specialists (TypeScript, Python, Rust, Go, React, etc.)
claude plugin install voltagent-lang
# Infrastructure & DevOps (Docker, Kubernetes, CI/CD, cloud, etc.)
claude plugin install voltagent-infraInstall both for full coverage. Once installed, the coding agents will automatically delegate to
the right specialist — e.g. a TypeScript project will use the typescript-pro subagent for
type-heavy work.
When enabled, the coding agent can spin up a lead plus multiple specialist teammates working in parallel (frontend dev + backend dev + QA), each in their own context window. Token cost is higher but wall-clock time drops significantly for large features.
To enable, set this environment variable before running ACAP:
# Add to your shell profile or set before running ACAP:
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1On first run, ACAP asks which agent CLI provider to use (claude, codex, omp, or opencode) and saves it to .env as AGENT_CLI_ID.
Step 1: Generate your prompts/ files from a PRD or product brief
# Interactive: paste your requirements and answer a few questions
uv run python3 acaps.py --prompt
# Or point it at a file
uv run python3 acaps.py --prompt --prompt-files ./my_prd.txtStep 2: Detect your tech stack and write the config
uv run python3 acaps.py --configure --project-dir ./my_projectStep 3: Run the coding agents
uv run python3 acaps.py --project-dir ./my_projectYou can also do all three steps in one go:
uv run python3 acaps.py --prompt --prompt-files ./my_prd.txt \
--configure --project-dir ./my_projectOr initialize and run in one-shot style:
uv venv
uv sync
uv run python3 acaps.py --project-dir ./my_projectBy default, the generated app is a Turborepo monorepo using Bun, with a pnpm fallback.
You can run a keyboard-first Textual interface for prompt generation and configuration:
uv run python3 tui_app.pyOptional startup flags:
uv run python3 tui_app.py \
--prompt-files ./my_prd.txt \
--project-dir ./my_project \
--agent-cli codex \
--model gpt-5-codexInside the TUI:
Up/Down+Enternavigate menusEtoggles field editing modeN/Pmove between refinement questionsSsubmits the questionnaire and continues generationLtoggles phase view vs streaming output log paneHhands off to the coding agent command after prep completesQquits- Clickable action buttons are available for start/prompt-only/configure-only/quit and Q&A controls.
If --prompt-files are provided, the requirements textbox is hidden and those files are treated as source of truth. The TUI then focuses on clarifying question refinement.
The TUI is additive: existing acaps.py --prompt, --configure, and full-run CLI flows remain unchanged.
Run logging for refinement is enabled by default in TUI mode. Each run writes structured JSONL output to logs/ (configurable) and includes prep-phase events plus post-handoff coding-agent stdout/stderr.
Related env keys:
AGENT_RUN_LOGGING_ENABLED=true|false(default:true)AGENT_RUN_LOG_DIR=logs(default:logs)
Quickly fetch the latest run log path (and optional tail preview):
uv run python3 latest_run_log.py
uv run python3 latest_run_log.py --tail 60This is the starting point. Give it your requirements document and it spits out the three files the coding agents need. Here is what happens under the hood:
- Collect - reads your file(s) or lets you paste text directly in the terminal
- Analyze - a quick AI pass reads your requirements and comes up with 3 to 7 clarifying questions about anything that is vague or missing
- Q&A - you answer the questions in the terminal (just hit Enter to skip any)
- Generate - a second AI pass writes all three files based on your answers
- Write - saves
prompts/app_spec.txt,prompts/initializer_prompt.md, andprompts/coding_prompt.md
Prompt generation now prefers structured templates when present:
prompts/app_spec-template.txtprompts/initializer_prompt-template.mdprompts/coding_prompt-template.md
If you want to redo this and replace files that already exist, add --prompt-overwrite.
Reads your prompts/ files and figures out your tech stack automatically, then writes a .env config file so you do not have to set anything up by hand.
What it writes to .env:
FRAMEWORK- e.g.laravel,django,react,genericPACKAGE_MANAGER- e.g.bun+pnpm,pip,composer+pnpmDEV_SERVER_CMDandDEV_SERVER_PORT- how to start the appAGENT_SYSTEM_PROMPT- a custom system prompt tuned for your stack
Run --configure again any time you edit prompts/ to refresh the config.
Agent 1 - Initializer (runs once): Reads app_spec.txt, writes feature_list.json with 200 end-to-end test cases, sets up the project folders, and makes the first git commit.
Agent 2 - Coding Agent (runs every session after that): Picks up from where the last session ended, implements one feature at a time using browser automation to verify it works, and marks it as passing in feature_list.json.
- Every session starts with a fresh context window
- Progress is tracked in
feature_list.jsonand git commits so nothing gets lost - The system automatically starts the next session after a 3 second pause
- Hit
Ctrl+Cto stop at any time. Run the same command again to pick back up.
Heads up: this runs for a long time.
- First session: Writing 200 test cases takes a few minutes and may look like it froze. It has not. Watch for
[Tool: ...]lines to confirm it is running. - Each coding session: Roughly 5 to 15 minutes per feature depending on complexity.
- Full app: Completing all 200 features takes many hours across many sessions.
If you just want to try it out quickly, open prompts/initializer_prompt.md and change "200" to something like 20 or 50.
The agents only have access to what they need (see security.py and client.py):
- Sandbox - bash commands run in an isolated environment at the OS level
- Filesystem - file operations are locked to the project directory only
- Command allowlist - only specific commands are allowed to run:
- Browsing files:
ls,cat,head,tail,wc,grep - Node.js:
bun,pnpm,node - Git:
git - Process management:
ps,lsof,sleep,pkill(dev processes only)
Anything not on the list gets blocked automatically.
When using non-Claude providers, some sandbox/approval controls may not have native CLI parity. ACAP applies prompt-based guardrails and emits warnings when running in degraded-capability mode.
acap/
├── acaps.py # Main entry point
├── agent.py # Agent session logic
├── client.py # Claude SDK client setup
├── configure.py # Stack detection and .env writing
├── prompter.py # Prompt wizard (turns your PRD into prompts/)
├── security.py # Command allowlist and validation
├── progress.py # Progress tracking
├── prompts.py # Prompt file loading
├── prompts/
│ ├── app_spec.txt # Your app specification (XML)
│ ├── initializer_prompt.md # Instructions for the first agent session
│ └── coding_prompt.md # Instructions for all sessions after that
├── pyproject.toml # Python project metadata + dependencies
└── uv.lock # Optional lockfile (generated by uv sync)
Once it starts building, your project folder will look like this:
my_project/
├── feature_list.json # The master list of test cases
├── app_spec.txt # Copy of your spec
├── init.sh # Script to start the dev environment
├── claude-progress.txt # Notes from previous sessions
├── .claude_settings.json # Security settings
└── [your app files]
Once the agents have built something (or you want to check on progress):
cd generations/my_project
# Use the setup script the agent wrote
./init.sh
# Or start it manually (most Node.js apps):
bun install
bun run dev
# If Bun is unavailable, fall back to pnpm:
pnpm install
pnpm devIt will usually be at http://localhost:3000. Check init.sh or the agent output for the exact URL.
| Option | What it does | Default |
|---|---|---|
--project-dir |
Where to put the project | ./autonomous_demo_project |
--max-iterations |
Cap on agent sessions | None |
--model |
Which Claude model to use | from .env or claude-sonnet-4-6 |
--configure |
Detect stack and write .env |
off |
--configure-model |
Model for stack detection | from .env or haiku |
--prompt |
Run the prompt wizard | off |
--prompt-files |
File(s) to feed the wizard | interactive |
--prompt-overwrite |
Overwrite existing prompt files | off |
--agent-cli |
Override provider for this run (claude|codex|omp|opencode) |
from .env/first-run prompt |
--save-agent-cli |
Persist --agent-cli to .env |
off |
# Override provider for one run
uv run python3 acaps.py --agent-cli codex --project-dir ./my_project
# Override and persist as future default
uv run python3 acaps.py --agent-cli opencode --save-agent-cli --project-dir ./my_projectProvider parity is best-effort. Some harnesses may not expose native equivalents for system prompt injection, tool allowlists, sandbox policies, or approval policies. In those cases ACAP uses prompt-based shims and prints warnings. Expect possible regressions or enhancements depending on provider/model behavior.
Run the wizard again with new requirements:
uv run python3 acaps.py --prompt --prompt-files ./new_prd.txt --prompt-overwriteOr just edit prompts/app_spec.txt directly.
Edit prompts/initializer_prompt.md and change "200 features" to whatever number you want.
Edit ALLOWED_COMMANDS in security.py.
It looks frozen on the first run
It is not frozen. Writing 200 test cases just takes a while. Look for [Tool: ...] lines in the output to confirm it is still working.
"Command blocked by security hook"
The agent tried to run something that is not on the allowlist. That is the security system doing its job. If you need that command, add it to ALLOWED_COMMANDS in security.py.
"Not authenticated"
Run claude login. You can also set ANTHROPIC_API_KEY in your environment if you prefer that route.
Internal Anthropic use.