software-factory
AGENTS.md6 starsChanged 2 days agoMITView on GitHub
This guide covers installing, signing in and configuring each supported coding agent CLI (Claude Code, Codex, OpenCode and Pi) for the factory. See models.md for model routing and harness-contract.md for the adapter contract. To bring your own CLI, see Bring your own agent.
- Reads credentials
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- merge-policySkill
- run-evalsSkill
- verifySkill
The file
Show its rules and text
We split this agents.md into the rules it gives an agent
19 rules. About 1 is common, 5 are distinctive, and 13 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 59
Run factory doctor in the repo.
- Very specific: line 92
Run factory doctor in the repo.
- Very specific: line 145
Run factory doctor in the repo.
- Very specific: line 178
Run factory doctor in the repo.
- Distinctive: line 194
No permission, gate or merge rule is relaxed.
- Very specific: line 204
Use this when Claude Code is the only agent you have.
- Very specific: line 224
Use this when Codex is the only agent you have.
- Very specific: line 245
Use this with an OpenCode Go subscription (the pinned model is served as opencode-go/deepseek-v4.1-flash).
- Distinctive: line 247
Do not switch off every provider: that empties the boss tier and the config fails to load.
- Distinctive: line 264
Put DeepSeek V4 Pro on PLAN (the boss tier) and the cheaper V4 Flash on BUILD and CHECK (worker/checker) when plan quality and bulk-work …
- Common: line 284
Create an OpenRouter API key with zero data retention (ZDR) enforced, by guardrail or account setting.
- Very specific: line 286
Check the key: pi auth check --model openrouter/deepseek/deepseek-v4.1-flash --no-refresh must print ready.
- Very specific: line 300
Run factory doctor, then factory models --doctor.
- Very specific: line 310
Use this to run on local models only.
- Distinctive: line 329
Use this to put each phase on the agent that suits it: Claude plans and triages, Codex builds, and a local Ollama model checks.
- Very specific: line 353
Put the harness, a model on it and the pins in one .factory/config.yaml:
- Very specific: line 384
Leave route unset; the factory derives command from the build pin.
- Very specific: line 419
Start the factory with factory run.
- Distinctive: line 423
If you would rather have the factory ship the adapter, open a Request support for a coding agent issue.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Coding agent setup
This guide covers installing, signing in and configuring each supported coding agent CLI (Claude Code, Codex, OpenCode and Pi) for the factory. See models.md for model routing and harness-contract.md for the adapter contract. To bring your own CLI, see Bring your own agent.
Harness matrix
| Agent | Harness id | Install and auth | Phases | Sandbox | Usage and cost | Rate-limit classification | CI coverage | Status |
| Claude Code | claude-cli | claude on PATH; /login in claude or ANTHROPIC_API_KEY | PLAN, BUILD (build_claude), CHECK, review, triage | Yes, the command is wrapped in the outer sandbox | Tokens, cache tokens, turns, durations and cost from the JSON result envelope | classifyFailure, plus unavailable for a zero-token error result | Contract tests in the required ci check; nightly evals install Claude Code | supported |
| Codex | codex-cli | codex on PATH; codex login, codex login --with-api-key or codex login --device-auth | PLAN, BUILD (build_codex), CHECK, review, triage | Outer OS sandbox where available; Codex's own sandbox is off by default (--sandbox danger-full-access), sandbox.codexSandbox: workspace-write opts in | Tokens from turn.completed events; no cost field, so cost uses registry price | classifyFailure | Contract tests in the required ci check | supported |
| OpenCode | opencode | opencode on PATH; opencode auth login, OPENCODE_API_KEY optional | PLAN, BUILD (build_opencode), CHECK, review, triage when pinned; needs FACTORY_EXPERIMENTAL=1 | No, the adapter does not take the sandbox request | Tokens and cost summed from step_finish events | classifyFailure | Contract tests in the required ci check | experimental |
| Pi | pi | pi on PATH; provider keys such as OPENROUTER_API_KEY in the environment | PLAN, BUILD (build_command, commit-only), CHECK, review, triage when pinned | Yes, the command is wrapped in the outer sandbox | Tokens and cost summed from assistant message_end events | Every non-clean finish is error for now | Contract tests in the required ci check | experimental |
| Ollama (prompt-only) | ollama-http | Ollama server running locally, no login | PLAN, CHECK, review, triage; not BUILD (not agentic) | No, it makes no file edits | Not reported | classifyFailure on the HTTP status and body | Contract tests in the required ci check | experimental |
| Ollama (agentic) | ollama-agentic | Ollama server running locally, no login | BUILD plus the other phases (agentic) | No | Not reported | classifyFailure | Contract tests in the required ci check | experimental |
| Declared custom harness | command | Your CLI on PATH, declared under harnesses: with an optional probe | PLAN, CHECK, review, triage; BUILD (build_command) only when declared agentic: true | Yes, the command is wrapped in the outer sandbox | usage: jsonl or none | Declared errorPatterns, then classifyFailure | Contract tests in the required ci check | supported |
ollama-command-agent is a retired alias. Models that name it, or set codex: true with provider: ollama and no harness, run on ollama-agentic, and the router logs a one-time warning (#3445).
Choosing and routing agents
Models whose CLI is not installed are skipped. On a machine with one CLI, every phase runs on that CLI's
models and PLAN picks its build route. With several CLIs, pin a phase in .factory/config.yaml
(models.pins.plan, build, checker, triage), set route, or reorder tiers.
factory triage --model <id> picks the triage model for one run. See models.md.
The feedback_triage role is a tool-less JSON call on the triage_cheap tier. A feedback round (factory respond <pr>
or a queued review rework) uses it to sort each unhandled trusted PR comment into actionable, question or
out-of-scope, and to flag feedback that changes the spec so PLAN runs again (#3910).
Claude Code
Install and log in
Install the CLI, for example npm install -g @anthropic-ai/claude-code. Then run claude and complete
/login to use your Claude subscription, or set ANTHROPIC_API_KEY to use API billing, which suits
automation and CI.
On macOS, an unattended service (LaunchAgent) that uses a subscription login needs login-keychain access: see the optional recipe. An API key or a non-macOS host does not need it.
Minimal .factory/config.yaml
version: 2
models:
pins:
plan: claude-sonnet-5
build: claude-sonnet-5
checker: claude-sonnet-5
triage: claude-sonnet-5
route: claudeVerify with factory doctor
Run factory doctor in the repo. Look for a coding agent line showing claude found, plus
the Claude Code section with claude installed (it shows the CLI version), and claude signed in (local login evidence only, no model call; run factory doctor --probe-inference to also send one real claude -p prompt).
Version tested: 2.1.296 (Claude Code)
Codex
Install and log in
On Linux, install firejail first (for example sudo apt install firejail). It is the OS sandbox the factory
wraps agent runs in. Without it, Codex still runs with --sandbox danger-full-access by default; set
sandbox.codexSandbox: workspace-write to opt in to its --sandbox workspace-write sandbox.
Install the CLI, for example npm install -g @openai/codex, and sign in once:
codex loginsigns in with ChatGPT and uses your Plus or Pro plan, with no API key. Runs count toward your plan limits; manage them in ChatGPT settings.codex login --with-api-keyuses API billing instead, which suits automation and CI.codex login --device-authsigns in on a headless machine.
Minimal .factory/config.yaml
version: 2
models:
pins:
plan: gpt-5.6-terra-high
build: gpt-5.6-terra-medium
route: codexVerify with factory doctor
Run factory doctor in the repo. Look for the Codex section with codex installed (it shows the CLI
version), and the codex signed in line (it names the sign-in method). The codex installed line also says whether sandboxed builds are available. It also says that Codex runs without its own sandbox (--sandbox danger-full-access) unless sandbox.codexSandbox: workspace-write is set. Without an OS sandbox runtime it reports the preflight result and how to opt in to Codex's workspace-write sandbox.
Codex sandbox mode and full access
By default (sandbox.codexSandbox unset or danger-full-access) Codex runs with
--sandbox danger-full-access -c approval_policy=never, the same containment Claude runs under; the OS
sandbox still wraps it where available. Set sandbox.codexSandbox: workspace-write in
.factory/config.yaml to keep Codex's own sandbox with the network allowlist and writable roots.
sandbox.codexFullAccessTasks only matters under workspace-write: tasks listed there still get
--sandbox danger-full-access, logged once per task. FACTORY_CODEX_FULL_ACCESS=1 alone cannot grant full
access: an unlisted task stays in --sandbox workspace-write, and the refusal is logged. Under the default both
settings have no effect and the run logs that once.
Version tested: codex-cli 0.155.1
OpenCode
Install and log in
Install OpenCode following opencode.ai, then run opencode auth login.
OPENCODE_API_KEY is an optional override. OpenCode models are experimental, so set
FACTORY_EXPERIMENTAL=1 in the factory's environment.
Minimal .factory/config.yaml
version: 2
models:
pins:
plan: opencode-deepseek-v4-flash
build: opencode-deepseek-v4-flash
checker: opencode-deepseek-v4-flash
triage: opencode-deepseek-v4-flash
route: opencodeEffort
models.efforts for an OpenCode model is passed as --variant <effort> on OpenCode 1.x, and as
--model '<provider/model>#<effort>' on 2.x. The factory reads opencode --version once per
harness instance (for every OpenCode run, not only when an effort is set); when the version is unknown it uses the 1.x form. On 2.x a model with no providerModel
runs without effort.
Isolation
On OpenCode 2.x the factory passes --standalone to opencode run, so each run starts a private
server and never attaches to the shared per-user background server. On 1.x, or when the version is
unknown, the flag is omitted.
Verify with factory doctor
Run factory doctor in the repo. The coding agent line lists opencode, and the OpenCode section
shows opencode installed and opencode signed in. factory models --doctor probes OpenCode reachability.
Supported OpenCode versions are >=1.18.0 <2.3.0. Doctor warns, without failing, when the installed
version is outside that range. OpenCode 1.x is the npm line: install the tested version with
npm install -g opencode-ai@1.18.28. OpenCode 2.x ships outside npm (Homebrew or the installer), runs
through the v2 flag path (--standalone, #<effort>), and is tested at 2.2.5.
Version tested: 1.18.28
Pi
Install and log in
Install the CLI with npm install -g @earendil-works/pi-coding-agent. Then run pi and complete
/login <provider>, or export the provider key, for example OPENROUTER_API_KEY. Pi models are
experimental, so set FACTORY_EXPERIMENTAL=1 in the factory's environment.
Minimal .factory/config.yaml
version: 2
models:
pins:
plan: pi-openrouter-deepseek-v4-flash
build: pi-openrouter-deepseek-v4-flash
checker: pi-openrouter-deepseek-v4-flash
triage: pi-openrouter-deepseek-v4-flash
route: piVerify with factory doctor
Run factory doctor in the repo. The coding agent line lists pi, and the Pi section shows
pi installed and pi signed in. Sign-in evidence is OPENROUTER_API_KEY, OPENCODE_API_KEY or
AZURE_OPENAI_API_KEY in the environment. factory models --doctor runs
pi auth check --model <providerModel> --no-refresh for each pinned Pi model (exit 0 is ready, 1 is
not ready, 2 is invalid).
Running in the current checkout
On a disposable, one-job container the clone is already the isolation boundary. factory run-issue <N> --in-place (or FACTORY_WORKSPACE=in-place) runs plan, build, check and ship in the current checkout on the normal factory branch, with no second worktree and no second install. It refuses to start, before PLAN, unless the checkout is clean and on the default branch at the fetched origin/<default> tip; the refusal names each dirty file with its git status code (for example M README.md, ?? new.txt). The size gate is off in place, and --base-branch and --stack are refused. Worktree mode stays the default. A host whose disk does not survive the run adds --json (the final result as one schemaVersion 3 object on the last stdout line, progress on stderr; schema in packages/cli/schemas/run-result.schema.json) and --export <dir> (the run's state file, events and cost records, written on every exit path); both also work on run-brief and ship, for one run only.
Repairing a red base
No base-health check runs before PLAN. Every run enters PLAN, and CHECK runs the full verify once and is the only test gate. A failing test, including one already red on main, goes back to BUILD until CHECK is green; it is never waived against a base baseline.
FACTORY_BASE_HEALTH_REPAIR=1is deprecated.factory run-issueonly prints a warning and carries on; the flag will be removed once callers migrate.- Non-test checkers (compile, lint, custom checkers) that also fail on the base can still release the run as an environment failure at CHECK.
- No permission, gate or merge rule is relaxed.
Recipes
Each recipe is a complete, minimal .factory/config.yaml. Copy it to the repo, then run factory doctor.
The Version tested: line names the CLI versions the recipe was checked with. CI loads every recipe
and fails if it stops parsing or pins an unknown model.
Recipe: Claude-only
Use this when Claude Code is the only agent you have. The pins and providers switches keep every tier on Claude.
version: 2
models:
pins:
plan: claude-sonnet-5
build: claude-sonnet-5
checker: claude-sonnet-5
triage: claude-sonnet-5
route: claude
providers:
openai: false
ollama: falseVersion tested: 2.1.296 (Claude Code)
Recipe: Codex-only
Use this when Codex is the only agent you have. Triage runs the pinned triage model, so on a
Codex-only host it runs through Codex and does not need claude.
version: 2
models:
pins:
plan: gpt-5.6-terra-high
build: gpt-5.6-terra-medium
checker: gpt-5.6-luna-high
triage: gpt-5.6-luna-high
route: codex
providers:
anthropic: false
ollama: falseVersion tested: codex-cli 0.155.1
Recipe: OpenCode Go-only
Use this with an OpenCode Go subscription (the pinned model is served as opencode-go/deepseek-v4.1-flash).
Set FACTORY_EXPERIMENTAL=1 in the factory's environment and sign in with opencode auth login, or set OPENCODE_API_KEY.
Do not switch off every provider: that empties the boss tier and the config fails to load. The pins keep it OpenCode-only.
version: 2
models:
pins:
plan: opencode-deepseek-v4-flash
build: opencode-deepseek-v4-flash
checker: opencode-deepseek-v4-flash
triage: opencode-deepseek-v4-flash
route: opencodeVersion tested: 1.18.28
Recipe: OpenCode Go — DeepSeek V4 Pro boss + V4 Flash worker/checker
Put DeepSeek V4 Pro on PLAN (the boss tier) and the cheaper V4 Flash on BUILD and CHECK (worker/checker) when plan quality and bulk-work cost both matter. Pro has a lower Go monthly quota, so keep it on the boss phase only.
version: 2
models:
pins:
plan: opencode-deepseek-v4-pro
build: opencode-deepseek-v4-flash
checker: opencode-deepseek-v4-flash
triage: opencode-deepseek-v4-flash
route: opencodeVersion tested: 1.18.28
Recipe: DeepSeek on Pi through OpenRouter
DeepSeek runs on Pi only through OpenRouter, never the native deepseek/ provider or DEEPSEEK_API_KEY
(ADR-0163 refuses both, and the harness removes DEEPSEEK_API_KEY from Pi's environment).
- Create an OpenRouter API key with zero data retention (ZDR) enforced, by guardrail or account setting.
- Export it:
export OPENROUTER_API_KEY=..., and setFACTORY_EXPERIMENTAL=1. - Check the key:
pi auth check --model openrouter/deepseek/deepseek-v4.1-flash --no-refreshmust printready. - Pin the model in
.factory/config.yaml:
version: 2
models:
pins:
plan: pi-openrouter-deepseek-v4-flash
build: pi-openrouter-deepseek-v4-flash
checker: pi-openrouter-deepseek-v4-flash
triage: pi-openrouter-deepseek-v4-flash
route: pi- Run
factory doctor, thenfactory models --doctor.
Why --no-approve is forced: the factory runs Pi non-interactively in an untrusted worktree, so it always
passes --no-approve (with --no-extensions, --no-skills, --no-prompt-templates and --no-mcp). Pi never
loads or approves repo-local .pi/ config, extensions, skills or MCP servers that a PR could plant.
Version tested: Pi 0.1.0 (recorded shim; real-run behavior unverified)
Recipe: Local Ollama
Use this to run on local models only. Set FACTORY_EXPERIMENTAL=1, start the server with ollama serve, and
ollama pull each model (qwen2.5-coder:14b, qwen3.5:9b). BUILD uses the ollama-agentic harness, which
is codex-eligible, so the route is codex.
version: 2
models:
pins:
plan: qwen2.5-coder:14b
build: codex-ollama-qwen3.5:9b
checker: qwen3.5:9b
triage: qwen2.5-coder:14b
route: codexVersion tested: ollama (version not recorded: ollama --version was not available on the build host; run it and compare)
Recipe: Mixed
Use this to put each phase on the agent that suits it: Claude plans and triages, Codex builds, and a local Ollama model checks.
version: 2
models:
pins:
plan: claude-sonnet-5
build: gpt-5.6-terra-medium
checker: qwen3.5:9b
triage: claude-sonnet-5
route: codexVersion tested: 2.1.296 (Claude Code), codex-cli 0.155.1, ollama (version not recorded, see the local Ollama recipe)
Bring your own agent
Any CLI that reads a prompt and edits the worktree can run through the built-in command harness. No code
change is needed: you declare the command, point a model at it, pin the model and check it. The field
reference is "Declaring a custom harness" in models.md. The contract is in
harness-contract.md.
1. Declare the harness and a model
Put the harness, a model on it and the pins in one .factory/config.yaml:
version: 2
harnesses:
my-agent:
command: ./scripts/my-agent.sh
prompt: stdin
output: jsonl-last-message
agentic: true
usage: none
errorPatterns:
rate_limit: '429|rate limit'
probe: my-agent --version
models:
registry:
my-agent-model:
provider: custom
harness: my-agent
tier: worker
costPerMtokInput: 0
costPerMtokOutput: 0
contextWindow: 200000
capabilities: [implementation]
envKey: null
pins:
plan: my-agent-model
build: my-agent-model
checker: my-agent-modelLeave route unset; the factory derives command from the build pin.
The command can be a small wrapper that reads the prompt on stdin, runs the agent in the worktree (the
working directory) and prints one JSON line per message. For example, scripts/my-agent.sh:
#!/usr/bin/env bash
# Read the prompt on stdin, run the agent in the worktree (cwd), print one JSON line per message.
set -euo pipefail
prompt=$(cat)
reply=$(my-agent --non-interactive "$prompt")
jq -cn --arg text "$reply" '{type: "message", text: $text}'With output: jsonl-last-message the factory returns the text of the last JSON line that carries text,
result, message or content, so progress lines before it are ignored.
2. Pin plan, build and checker
The pins in the block above send PLAN, BUILD and CHECK to your model. BUILD needs agentic: true; a
non-agentic build pin is refused when config loads. BUILD runs the build_command task and leaves commits
only. SHIP publishes.
3. Run factory doctor
factory doctor runs the probe command and reports the harness as available, unavailable or unverified.
It counts an agentic declared harness as the coding agent when the first word of command is on PATH.
4. Run factory harness check my-agent
factory harness check my-agent runs the contract scenarios against your declared CLI and reports pass or
fail per scenario. See Testing a harness.
5. Run factory run
Start the factory with factory run. PLAN, BUILD and CHECK use the pinned model on your harness.
Request support instead
If you would rather have the factory ship the adapter, open a
Request support for a coding agent
issue. The form is defined in .github/ISSUE_TEMPLATE/agent-support.yml.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

