beflow

An AI-agent orchestration CLI for governed autonomy — drives your backlog to shipped PRs, with a policy gate on every change.

beflow turns work items on a project board (Plane or Linear) into agent-driven pull requests. You stay the captain — decide, review, merge; beflow runs the crew — investigate, spec, build, open PRs — and keeps the board in sync.

beflow owns the PR: every agent-built change runs a policy gate (AGENTOWNERS-style, most-restrictive-wins) before it's ever review-ready — block, require_approval, or allow — so you can run agents autonomously on real repos without handing them unsupervised write access to main.

⭐ If beflow is useful to you, please star the repo — it helps others find it.

The agent is tracker-blind. All tracker I/O happens at the boundaries of a run: beflow resolves a task + a repo + a contract, hands them to a coding-agent CLI, and writes the structured result back to the board. The agent never knows which tracker it's serving, so the same agent works across Plane and Linear.

Why tracker-blind matters: the agent never couples to a specific board. Swap Plane for Linear, run several trackers at once, or restructure your boards — your agents, prompts, and contracts don't change. The tracker is an adapter, not a dependency. Governance lives at that same boundary: the policy gate sees the diff and the decision, never the tracker.

flowchart LR
  T["Tracker adapter<br/>Plane | Linear"]
  subgraph C["beflow core"]
    R["resolve repo + agent<br/>+ job kind + run mode"]
    G["gates + policy"]
    P["open / ready / block PR"]
  end
  A["Agent adapter<br/>claude | acpx | omp"]
  T -- fetch issue --> R
  R --> G --> P
  P -- run in worktree --> A
  A -- report --> G
  C -- write back report --> T

Loading

---

Requirements

• Bun ≥ 1.0 — beflow runs on the Bun runtime.
• A coding-agent CLI that speaks ACP (e.g. claude) plus acpx (fetched automatically via bunx).
• git and the gh CLI (for the PR step).
• A Plane or Linear workspace and a personal API token.

Install

bun add -g beflow      # or: npm i -g beflow

beflow is invoked with the Bun runtime, so Bun must be on your PATH. To run from source instead:

git clone https://github.com/corrm/beflow.git
cd beflow
bun install
bun run build          # optional: compile a standalone ./dist/beflow binary

Quickstart

# 1. Set your tracker API token in your shell profile:
#    zsh:   echo 'export PLANE_API_KEY=...' >> ~/.zshrc  && source ~/.zshrc
#    bash:  echo 'export PLANE_API_KEY=...' >> ~/.bashrc && source ~/.bashrc
#    PowerShell (Windows):
#           [System.Environment]::SetEnvironmentVariable("PLANE_API_KEY","your_token","User")
# Use LINEAR_API_KEY instead if you are on Linear.

# 2. Check your setup — creates ~/beflow/config.json on first run
beflow doctor
# Open ~/beflow/config.json, fill in your workspace slug, project IDs, and repo paths, then re-run.

# 3. Provision the board (creates the tracker project if it doesn't exist)
beflow setup <KEY>     # <KEY> is the project key in your config (e.g. APP, BE, WEB)

# 4. Run a work item, or start the watch daemon
beflow run <KEY>-42 --auto
beflow watch <KEY>

See the config reference for every setting and config.example.json for a complete starting point.

Run modes

Mode	Flag	What it is
Autonomous	beflow run <KEY>-42 --auto	Headless. Isolated git worktree; for an implement job, opens a PR and moves the item to In Review.
Supervised	beflow run <KEY>-42 --attend	Interactive via acpx — you approve actions as they happen.
Open	beflow run <KEY>-42 --open	Runs in the agent's own native TUI; you're present for a multi-turn session.

Runs are resumable: each persists a run record and keeps its worktree until the item is Done, so an interrupted run picks up where it left off.

In --auto mode with pr.owner: "beflow" (the beflow-owned pipeline), beflow gates the issue before running the agent, then owns the full PR lifecycle — opening a draft, running the quality gate, evaluating post-run policy, and writing back to the board — without any gh call from the agent itself. The post-run policy gate supports globs, agentowners, command, and off evaluators — see PR ownership and policy.

flowchart TD
  picks["pick up issue"] --> dgate{"decision gate<br/>(needs-decision?)"}
  dgate -- held --> ni1["→ Needs Input"]
  dgate -- ok --> iq{"input-quality<br/>(too thin?)"}
  iq -- thin --> ni2["→ Needs Input"]
  iq -- ok --> wt["create worktree beflow/&lt;key&gt;"]
  wt --> ag["agent: commit + push (no gh)"]
  ag --> noop{"any commits?"}
  noop -- no --> failkeep["failed (keep worktree)"]
  noop -- yes --> draft["beflow opens DRAFT PR"]
  draft --> qg{"quality gate"}
  qg -- RED after rework --> failkeep2["failed (keep draft PR)"]
  qg -- green --> pol{"post-run policy"}
  pol -- block --> blk["close PR, keep branch<br/>→ Needs Input"]
  pol -- require_approval --> appr["enrich body, leave DRAFT<br/>→ In Review + awaits-approval note"]
  pol -- allow --> al["enrich body + mark ready<br/>→ In Review"]

Loading

See PR ownership and policy for the full configuration reference and policy examples.

The board is the control center

beflow drives a simple board and you steer from it:

Backlog → Todo → In Progress → In Review → Done   (+ Needs Input, Cancelled)

beflow watch polls the queue and dispatches Todo items up to your WIP limit (limits.inProgress / limits.inReview), advances merged PRs to Done, reworks items you label changes-requested, and answers items in Needs Input when you reply. See the lifecycle and operating model.

Commands

Command	What it does
run <key>	Run a work item through an agent
watch <project>	Continuously poll a project's queue and dispatch work
setup / update <project>	Provision/reconcile a project's board to the template
new <project> [template]	Author a new work item from a template
accept <project> <intake>	Accept an intake item into the backlog
review <key>	Run an agent-driven review over a work item's open PR
queue	Print the work queue across projects
runs [key]	Inspect persisted run records (read-only)
doctor	Diagnose the local beflow environment
gc	Find and prune orphaned git worktrees

Full details — flags, examples, behavior — in the command reference. Every command also supports --help.

Configuration

beflow reads its configuration from ~/beflow/config.json — the tracker connection, your workspace + project registry, agent definitions, and global defaults. Running beflow doctor creates the file automatically on first run — open it, fill in your workspace details, and re-run. See config.example.json for a complete reference.

A project maps a key to a tracker project and the local repos its work lands in:

"projects": {
  "APP": {
    "name": "My App",
    "plane_project_id": "…",
    "root": "/path/to/your/project",
    "default_repo": "main_repo",
    "repos": { "main_repo": "…", "website": "…" },
    "module_repo_map": { "Backend": "main_repo", "Frontend": "website" }
  }
}

Every key — per-project overrides, agent definitions, and the opt-in gates (dead-letter, quality gate, SLA, CI rework, review) — is documented in the config reference. API keys are set in your shell profile, never in ~/beflow/config.json.

Documentation

• Command reference — every command and flag
• Config reference — every config.json setting
• PR ownership and policy — beflow-owned PR creation, post-run policy gating
• Design — architecture and the run pipeline
• Lifecycle — the board as the control center
• Operating model — the queue-based workflow
• Resolution — how agent / mode / repo / job kind are chosen
• Prompts — prompt templates and overrides
• Issue templates — authoring work items with beflow new
• Adapters — writing a tracker adapter
• MCP — per-run MCP servers
• ACP events — the agent event stream beflow consumes

Star the repo

⭐ If beflow helps you ship, please star it on GitHub — it's the easiest way to support the project and help others discover it.

License

MIT