agentleFS
on-paron-par/software-factory/docs/agents.md

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.

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
  1. Very specific:

    Run factory doctor in the repo.

    line 59
  2. Very specific:

    Run factory doctor in the repo.

    line 92
  3. Very specific:

    Run factory doctor in the repo.

    line 145
  4. Very specific:

    Run factory doctor in the repo.

    line 178
  5. Distinctive:

    No permission, gate or merge rule is relaxed.

    line 194
  6. Very specific:

    Use this when Claude Code is the only agent you have.

    line 204
  7. Very specific:

    Use this when Codex is the only agent you have.

    line 224
  8. Very specific:

    Use this with an OpenCode Go subscription (the pinned model is served as opencode-go/deepseek-v4.1-flash).

    line 245
  9. Distinctive:

    Do not switch off every provider: that empties the boss tier and the config fails to load.

    line 247
  10. Distinctive:

    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 …

    line 264
  11. Common:

    Create an OpenRouter API key with zero data retention (ZDR) enforced, by guardrail or account setting.

    line 284
  12. Very specific:

    Check the key: pi auth check --model openrouter/deepseek/deepseek-v4.1-flash --no-refresh must print ready.

    line 286
  13. Very specific:

    Run factory doctor, then factory models --doctor.

    line 300
  14. Very specific:

    Use this to run on local models only.

    line 310
  15. Distinctive:

    Use this to put each phase on the agent that suits it: Claude plans and triages, Codex builds, and a local Ollama model checks.

    line 329
  16. Very specific:

    Put the harness, a model on it and the pins in one .factory/config.yaml:

    line 353
  17. Very specific:

    Leave route unset; the factory derives command from the build pin.

    line 384
  18. Very specific:

    Start the factory with factory run.

    line 419
  19. Distinctive:

    If you would rather have the factory ship the adapter, open a Request support for a coding agent issue.

    line 423

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
agents.md

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

AgentHarness idInstall and authPhasesSandboxUsage and costRate-limit classificationCI coverageStatus
Claude Codeclaude-cliclaude on PATH; /login in claude or ANTHROPIC_API_KEYPLAN, BUILD (build_claude), CHECK, review, triageYes, the command is wrapped in the outer sandboxTokens, cache tokens, turns, durations and cost from the JSON result envelopeclassifyFailure, plus unavailable for a zero-token error resultContract tests in the required ci check; nightly evals install Claude Codesupported
Codexcodex-clicodex on PATH; codex login, codex login --with-api-key or codex login --device-authPLAN, BUILD (build_codex), CHECK, review, triageOuter OS sandbox where available; Codex's own sandbox is off by default (--sandbox danger-full-access), sandbox.codexSandbox: workspace-write opts inTokens from turn.completed events; no cost field, so cost uses registry priceclassifyFailureContract tests in the required ci checksupported
OpenCodeopencodeopencode on PATH; opencode auth login, OPENCODE_API_KEY optionalPLAN, BUILD (build_opencode), CHECK, review, triage when pinned; needs FACTORY_EXPERIMENTAL=1No, the adapter does not take the sandbox requestTokens and cost summed from step_finish eventsclassifyFailureContract tests in the required ci checkexperimental
Pipipi on PATH; provider keys such as OPENROUTER_API_KEY in the environmentPLAN, BUILD (build_command, commit-only), CHECK, review, triage when pinnedYes, the command is wrapped in the outer sandboxTokens and cost summed from assistant message_end eventsEvery non-clean finish is error for nowContract tests in the required ci checkexperimental
Ollama (prompt-only)ollama-httpOllama server running locally, no loginPLAN, CHECK, review, triage; not BUILD (not agentic)No, it makes no file editsNot reportedclassifyFailure on the HTTP status and bodyContract tests in the required ci checkexperimental
Ollama (agentic)ollama-agenticOllama server running locally, no loginBUILD plus the other phases (agentic)NoNot reportedclassifyFailureContract tests in the required ci checkexperimental
Declared custom harnesscommandYour CLI on PATH, declared under harnesses: with an optional probePLAN, CHECK, review, triage; BUILD (build_command) only when declared agentic: trueYes, the command is wrapped in the outer sandboxusage: jsonl or noneDeclared errorPatterns, then classifyFailureContract tests in the required ci checksupported

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: claude

Verify 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 login signs 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-key uses API billing instead, which suits automation and CI.
  • codex login --device-auth signs 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: codex

Verify 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: opencode

Effort

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: pi

Verify 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=1 is deprecated. factory run-issue only 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: false

Version 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: false

Version 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: opencode

Version 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: opencode

Version 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).

  1. Create an OpenRouter API key with zero data retention (ZDR) enforced, by guardrail or account setting.
  2. Export it: export OPENROUTER_API_KEY=..., and set FACTORY_EXPERIMENTAL=1.
  3. Check the key: pi auth check --model openrouter/deepseek/deepseek-v4.1-flash --no-refresh must print ready.
  4. 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
  1. Run factory doctor, then factory 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: codex

Version 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: codex

Version 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-model

Leave 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.