Agent Flow

Leave your coding agent alone with your repo. Come back to a reviewed pull request, not a mess.

One agent builds. A second reviews. A third tests. A guard keeps all three out of what they must never touch.

Install · What you come back to · How it works · Harnesses · FAQ

Install

npx @drix10/agent-flow install --harness claude

Then tell your agent "use the agent-flow-bootstrap skill": it reads the repo and asks what must never be touched. After that, hand it a task:

npx @drix10/agent-flow run "Add a --json flag so CI can parse the output"

That's all of it. It runs in its own git worktree and stops with checked work and a draft pull request waiting for you. Works with Claude Code, Codex, Gemini CLI, Cursor, Copilot, Windsurf, Pi and anything that reads AGENTS.md: swap claude for codex, gemini, cursor, copilot, windsurf or agents. Node.js 20+, no runtime dependencies, no package.json needed in your repo.

The guard blocks tool calls directly on Claude Code and Pi. On the other hosts the skills guide the agent and a pre-commit hook and CI catch the slips: what each host enforces.

What you come back to

Real output from a run on a real repository (trimmed):

$ agent-flow status

Protection
  ✓ Claude Code guard hook is active
  ✓ 11 protected paths, 7 critical areas
  ✓ 1 review-only path: agents may add lines (a new CI test), a person reviews the pull request

Work
  · #100000 is ready: reviewed, checked, not pushed
      → agent-flow run 100000 --pr  to open the pull request

Without it, and with it

From one real repo

Agent Flow ran for five days on a real C++ and Python research repository (294 role runs, about $83). The audit log recorded:

• 150 tool calls blocked, among them 20 reads of secret files, 2 pushes to main and 1 --no-verify. Not every block was right: 16 were false alarms from a Windows path bug, fixed in 1.2.6.
• 15 lines added to the CI workflow, none changed or deleted.
• A median finished issue cost $0.90 and took 17 minutes, over 63 issues.

One repository, one maintainer: an example, not a benchmark.

npx @drix10/agent-flow scan

npx skills add Drix10/agent-flow

npx @drix10/agent-flow install --harness claude     # nothing to install first

npm install --global @drix10/agent-flow             # the agent-flow command everywhere
agent-flow install --harness claude

npm install --save-dev @drix10/agent-flow           # or pin it in a Node project's package.json
npx agent-flow install --harness claude

npx @drix10/agent-flow run "Add a --json flag so CI can parse the output"

npx @drix10/agent-flow@latest update --yes
npx @drix10/agent-flow doctor
npx @drix10/agent-flow audit-risk --fail-on-new

name: agent-context
on: [push, pull_request]
jobs:
  context:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npx @drix10/agent-flow doctor
      # Create and review .risk-baseline.json before enabling this gate.
      - run: npx @drix10/agent-flow audit-risk --fail-on-new

- uses: actions/checkout@v4
  with: { fetch-depth: 0 }
- uses: Drix10/[email protected]

npx @drix10/agent-flow status       # protection, checks, context and pending work
npx @drix10/agent-flow doctor       # read-only context report
npx @drix10/agent-flow scan         # read-only repository reconnaissance
npx @drix10/agent-flow hook install # install the pre-commit gate
npx @drix10/agent-flow debt         # the shortcuts agents left, and which have no trigger to revisit them
npx @drix10/agent-flow clean        # preview removing merged agent/issue-N branches and worktrees (--yes to do it)
npx @drix10/agent-flow uninstall    # preview taking back out what install wrote (--yes to do it)
npx @drix10/agent-flow state dismiss --issue 100000 --reason "did it by hand"   # drop an issue from the list
npx @drix10/agent-flow state dismiss --merged                                   # drop every finished issue already merged into the default branch

How it works

task -> worktree -> implement -> classify -> review -> gates -> QA -> optional PR
                         ^                         |
                         +--- bounded fix rounds --+

Each role is a separate process and receives files from .agent-flow/artifacts/issue-N/, not another role's reasoning. Issue text is escaped and treated as untrusted input. The state machine enforces transitions and the review-round cap. Repeated failures stop for a human. When you request a PR, critical changes create a draft and wait for human review. Local is the default; publishing needs --pr.

pipeline.lean asks the Implementer and Reviewer for the smallest correct change and marks the shortcuts it takes (Lean).

Protected paths stop a run; review-only paths (review_paths, usually .github/workflows/) don't. An agent may add a line there, such as a new test in the CI list, and the pull request waits as a draft for you. See Adoption.

The loop is not equally enforced on every harness. The guard blocks tool calls directly on Claude Code and Pi. Other harnesses rely on their available sandbox and the pre-commit hook, which runs at commit time and can be bypassed by a human. Reviewer write restrictions vary by harness. See the harness matrix before choosing a role setup.

Repository context

Agent Flow uses AGENTS.md for shared agent instructions. Claude Code can load it through CLAUDE.md containing @AGENTS.md. Module-level AGENTS.md files add rules for that part of the repository. CONTEXT_MANIFEST.json records referenced paths, protected paths, risk boundaries and pipeline settings. The agent-flow-gardener skill checks and repairs this context; it re-reads the code before refreshing timestamps.

When an agent repeats a mistake, prefer a mechanical fix: an invariant in code, a test, a guard rule or a protected path. Prompts and prose are the least reliable enforcement.

What leaves your machine

Agent Flow runs no service and has no telemetry, account or API key. It sends nothing to its author. The only traffic is what you start yourself, to services you already use:

The guard, the pre-commit hook, classify, audit-risk and gates never touch the network. What Agent Flow writes stays in your repository: the audit log and artifacts under .agent-flow/ (kept out of git through .git/info/exclude). It reads files in your checkout and commit hashes and subjects; it does not collect personal data, and it refuses to read .env files and deny_read paths. Details: Security.

Limits and security

• Risk classification and secret detection are heuristic; review their findings.
• Shell-write analysis is best-effort. Use a sandbox or remove shell access from read-only roles when a hard boundary is required.
• Per-tool enforcement is available on Claude Code and Pi. Other harnesses have different enforcement limits.
• Hooks do not access the network. doctor may make optional, cached read-only lookups for package updates and GitHub Code Owner settings; CI and offline modes skip them.
• Each issue gets its own git worktree. Measured on Windows with a synthetic 60,000-file repository: creating it took 16 seconds (git's checkout), Agent Flow's own commands each finished in about half a second or less, and the before-and-after check around QA added about 3 seconds in total. Very large monorepos should use git sparse-checkout or a partial clone; Agent Flow does not automate that.
• Critical changes are reviewed by a stronger model only if you set pipeline.models.high_reasoning (and pipeline.models.fast for the rest). Unset, every role uses the default model, and status and run say so.
• Audit logs are tamper-evident, not tamper-proof. Keep an audit hash outside the repository if you need an external trust anchor.

See Security and known failure modes for details. Agent Flow works one repository at a time and does not provide model-provider failover.

FAQ

Will agents get stuck waiting for me? Only on protected paths and critical changes. Everything else, including CI list additions, carries on and reaches you as a draft.

What if my harness has no hooks? The skills and the pre-commit gate still apply; the guard's per-call blocking does not. The harness matrix says which is which.

My run stopped after 30 minutes. That is the background limit of the tool that launched it (Claude Code's default), not Agent Flow's: a pipeline takes one to two hours. Launch it with the tool's longest limit, and agent-flow run <issue> resumes a stopped one. --timeout <seconds> sets how long each role may run (default 3600).

Branches and worktrees pile up. Every run --pr pushes agent/issue-N, and nothing removes it after the merge: one user had 169 on the remote. agent-flow clean previews and agent-flow clean --yes removes the ones whose work is already in the default branch, local and on origin, with their worktrees. It never touches uncommitted work, an issue with a run or decision still open, or a branch that isn't named agent/issue-N; a squash merge is recognised through gh. To stop the remote ones piling up at the source, turn on "Automatically delete head branches" in the repository's GitHub settings.

GitHub blocked my push over a secret in a test. Its push protection scans every commit and doesn't know a fixture from a leak. Build the fake value at run time (split or join the string) so nothing secret-shaped is committed. The run says which file it found and where a person can allow it.

How do I remove it? agent-flow uninstall previews, --yes applies. Files you edited are kept.

Development

npm install
npm test

The test suite exercises real temporary Git repositories and supported installation targets. See Contributing.

License

MIT