brainfile

$ npx brainfile init
$ npx brainfile list

Every command works through npx. The MCP configuration above uses it so the server tracks whatever version npm resolves, and nothing has to be on the PATH.

$ brainfile migrate
$ brainfile migrate --logs-to-ledger   # also backfill logs/*.md into ledger.jsonl

Older boards kept every task inside one brainfile.md. migrate splits that into .brainfile/brainfile.md plus one file per task, keeps backups, and refuses to overwrite its own outputs unless you pass --force.

brainfile is one of the chain.sh tools. One command installs the set:

$ curl -fsSL https://chain.sh/bootstrap.sh | sh

A decision belongs to a claim family through its dotted claimKey (dependency.http-client). A family has one current decision: decide records a new one and supersedes the old, which gets status: superseded and supersededBy, moves to logs/, and is pointed at by the new one's supersedes. A current decision lives in board/; a superseded, rejected or stale one in logs/. The body is the decision and why.

---
id: decision-3
title: Use undici for HTTP, never axios
type: decision
status: current
claimKey: dependency.http-client
kind: constraint
stance: forbids
subject: axios
holdsWhile: we target Node 20 and later
recheck: when fetch gains retries
validUntil: 2027-06-30
packageVersion: undici>=6
supersedes: decision-1
---

Name your own under types: in the config, or with brainfile types add. A type can take a built-in's place with like:: it gets that type's parents, children, completion rule and glyph. One with no like behaves as a task.

types:
  bug: { like: task }
  rfc: { like: spec, idPrefix: rfc }

An entry under a built-in's own name overrides it (plan: { completable: false } stops a plan completing when it reaches a completion column). With strict: true, a document's type must be built in or listed. brainfile types prints every type with its place in the graph.

$ brainfile init
$ brainfile init --force    # overwrite an existing config
$ brainfile init --plain    # a plain directory, even inside a git repository
$ brainfile init --here     # inside a repository: this directory, not its root
$ brainfile init -g         # the home board at ~/.brainfile

Writes a short brainfile.md with two columns and the default agent instructions (no types:: the five built-in types need none), creates board/ and logs/, and adds a .gitignore that excludes state/, this machine's own bookkeeping (see state/).

Inside a git repository the board is created at the repository root as a worktree on its own brainfile branch, hidden from the code branch through .git/info/exclude; outside one, --tracked makes it its own repository. Either way every change becomes a commit. --plain opts out. See Sharing a board.

$ brainfile list
$ brainfile list -c todo
$ brainfile list -t urgent             # by tag
$ brainfile list --parent epic-1
$ brainfile list --type spec           # aliases work: issue is task, adr is decision
$ brainfile list --tree                # the outline: epics, specs, plans, tasks
$ brainfile list --tree --parent epic-1
$ brainfile list --type decision       # decisions, current first
$ brainfile list --contract ready      # ready | in_progress | delivered | done | failed
$ brainfile list --related             # open tasks on related boards this board waits on
$ brainfile list --related all         # every open task on every related board

Prints every column with its tasks, priorities and tags. A task waiting on a related board says so on a Blocked by: line, and one resting on a superseded decision says that too. Decisions have no column, so list leaves them out and says how many; --type decision lists them with where each stands.

--tree prints open work as an outline, nested by parentId in column order:

$ brainfile list --tree

My Project — outline

▸ epic-1  Memory and the graph  · In Progress
  ◆ spec-1  Default types  · To Do
    ⎘ plan-1  Build order  · To Do
      · task-1  Registry  · To Do
  · task-3  Index work  · To Do  ⚠ rests on superseded decision-2

With a filter it shows the matches and keeps their ancestors, dimmed, for context; --parent shows one document and everything under it.

$ brainfile show -t task-2
$ brainfile show -t task-2 --json
$ brainfile show -t mobile:task-12     # a task on a related board

--json prints the document's frontmatter as one object, timestamps included. show names the document's type, its parent, its children (open or done), each dependency and whether it is done, and the decisions it rests on with where each stands; if one is superseded it says "Rests on a superseded decision". A decision shows its status and the work resting on it. --json adds the same as graph.

A hand-off's whereabouts are on the same page. A task that lands somewhere other than the trunk says where and why (Lands on: release/0.38.0 · from epic-3, or · epic-3's own branch); an epic with a branch of its own says so (Epic branch: yes, epic-3's children land on dispatch/epic-3); a task made from an issue shows its Source:; one opened as a pull request shows it (Pull request: #12 open, dispatch/task-12 into main, with the URL). --json carries the target as target.

$ brainfile add -t "Fix login bug" -p high --tags bug,auth --files src/auth.ts
$ brainfile add -t "Auth epic" --type epic --child "OAuth flow" --child "Session hardening"
$ brainfile add -t "Token refresh" --type spec --parent epic-1
$ brainfile add -t "Use SQLite for the index" --type decision
$ brainfile add -t "Build the index" --parent spec-1 --decisions decision-1
$ brainfile add -t "Crash on empty board" --source https://github.com/o/r/issues/12

$ brainfile issues                        # open issues; those on the board show their task
$ brainfile issues --import 12 15         # make a task from each
$ brainfile issues --import 12 -c todo
$ brainfile issues --json

Lists the open issues of the GitHub repository the project's origin points at, pull requests left out, most recently updated first, and marks each one a task on the board (open or completed) already carries as source:. --import makes a task from each number: the issue's title, its body as the description, its labels as tags (good first issue becomes good-first-issue), and its page as source:, in -c, --column or else the first column that is not done. An issue already on the board is found, not made again. GitHub is asked with the gh CLI's login (gh auth token), then GH_TOKEN or GITHUB_TOKEN, then the token brainfile auth github saved; with none, public repositories still answer, on GitHub's smaller rate limit. The desktop app looks in the same order.

$ brainfile pr task-12             # push dispatch/task-12, open a pull request into where it lands
$ brainfile pr task-12 --status    # where it stands; merged completes the task
$ brainfile pr task-12 --json

Landing by pull request instead of a merge (decision-16). The task's hand-off branch, dispatch/<task>, is pushed to origin, and only that branch: the trunk is never pushed. A pull request is opened from it into the branch the task lands on (its landsOn, inherited, else the trunk), titled with the task's title, its body the task's ID, the first lines of its description and the last of its log, and the task records it as pullRequest:. It is refused, as a merge is, while the worktree has uncommitted work, the branch has nothing to land, a runner holds the task, or one is open already; checks are the forge's. While it is open the hand-off is not ready to merge.

--status asks GitHub where it stands. Merged, origin's copy of the target is fetched, the worktree and the local branch go (a squash or rebase merge counts when the branch is what the pull request carried; work committed after it was pushed keeps the worktree, and says so), and the task completes, unless subtasks are left. Closed without merging, pullRequest: says closed, and the hand-off can be merged, or opened again. Credentials as issues; opening one needs them.

$ brainfile move -t task-1 -c in-progress

Column names and ids both work.

$ brainfile patch -t task-1 -p critical --assignee codex
$ brainfile patch -t task-1 --tags perf,cache        # replaces the tag list
$ brainfile patch -t task-1 --clear-due-date
$ brainfile patch -t spec-3 --parent epic-2
$ brainfile patch -t task-7 --depends-on task-5,task-6 --decisions decision-2
$ brainfile patch -t epic-3 --lands-on release/0.38.0 --epic-branch

Takes --title, -d, -p, --tags, --assignee, --due-date, --parent, --depends-on, --decisions, --lands-on and --epic-branch, plus --clear-tags, --clear-assignee, --clear-due-date, --clear-priority, --clear-parent, --clear-depends-on, --clear-decisions, --clear-lands-on and --clear-epic-branch. -p none also removes the priority. A new parent must fit the type, as for add, and neither link may loop. --lands-on must be a name git takes for a branch; cleared, the task inherits its parent's target again.

$ brainfile complete -t task-1
$ brainfile complete -t epic-1 --force   # even if children are still active

Appends to logs/ledger.jsonl, moves the file to logs/, and records cycle time from createdAt. A parent with open children refuses, whatever its type, until they are done or you pass --force; a decision is never completed.

$ brainfile delete -t task-3 --force

--force is required; there is no prompt and no undo. Prefer complete.

$ brainfile subtask -t task-1 --add "Write tests"
$ brainfile subtask -t task-1 --toggle sub-1
$ brainfile subtask -t task-1 --update sub-1 --title "Write unit tests"
$ brainfile subtask -t task-1 --delete sub-1

$ brainfile search parser
$ brainfile search parser -c in-progress
$ brainfile search cache --type adr      # decisions, under either name
$ brainfile search "p:high #auth token"  # filter tokens: p: #tag @user type: due: contract:
$ brainfile search parser --no-history --json

Current results come first: open work, current decisions, plans/ and the project's own Markdown (README, AGENTS.md, docs/…). History comes after, in its own lane: completed work, the ledger, and decisions that were superseded, rejected or let go stale. Every hit has its path and line range; a board document also has its ID, a file hit's ID is path:start-end.

On Node 22.13 and later the local index answers (.brainfile/state/index.db, brought up to date before every search): words are matched all together first and any of them second, ranked with titles over bodies. On older Node, or with BRAINFILE_INDEX=off, the scan over board/ and logs/ answers in the same shape; nothing else changes. A query that is only filter tokens (p:high) always scans. --limit caps each lane (default 20), --json prints { mode, query, results, count } with each hit's lane, source, path, startLine and endLine.

$ brainfile note -t task-1 "Bounded by bytes, not entries"
$ brainfile note -t task-1 --agent codex "Tests pass on the new cache"

Each note is tagged with who wrote it: --agent when given, otherwise the agent running the command if brainfile can tell (see Who did what), otherwise your git user.name. Notes stay with the task and become the ledger summary when it completes.

$ brainfile log --recent
$ brainfile log -t task-1
$ brainfile log -s "cache"

$ brainfile tui

Columns, decisions, detail view, filters and every write operation from the keyboard. See The TUI.

$ brainfile brief --agent claude
$ brainfile brief --agent claude --max-chars 0  # no budget
$ brainfile brief --agent claude --peek         # read without marking seen
$ brainfile brief --agent claude --json
$ brainfile brief --agent claude --offline      # skip the sync a shared board does first

One block, about 1,600 characters (--max-chars), in lanes:

Brainfile brief for claude · My Project (since 3h ago)
! task-12 Build the index: rests on superseded decision-1 (now decision-3)
## Current decisions
- decision-3 dependency.http-client: Use undici for HTTP, never axios (constraint · forbids axios)
## Your tasks
- task-12 Build the index · In Progress · high
## Since your last brief
- task-12 note: [codex] wired the FTS table (2h ago)
- decision-3 decided: Use undici for HTTP, never axios (supersedes decision-1) (3h ago)
## Docs that bear on them
- docs/index.md:12-40 Search index › Design

Lines starting with ! come first: open work resting on a superseded decision, and current decisions whose validUntil, source file or package version no longer holds. Then the current decisions; the agent's tasks (or, when nothing is assigned to it, the work in flight); what changed since its last brief (notes, task changes, completions, decisions made or retired, config), or on a first brief the latest notes and completions; and, from the local index, the docs that share the tasks' most distinctive words. When the budget is tight every lane still gets its first line, shortened if need be, before any lane gets a second, and a last line says how many more there are.

The checkpoint is per agent, kept in .brainfile/state/ and ignored by git; --peek reads without moving it. --json carries the block as text, its lanes as sections, and the checkpoint's own lanes as before. A shared board syncs before the brief so it reflects other machines; a sync failure is one warning line, never an error. The SessionStart hook prints this block.

$ brainfile contract pickup -t task-2
$ brainfile contract deliver -t task-2
$ brainfile contract validate -t task-2
$ brainfile contract attach -t task-5 --ready --deliverable "file:src/x.ts" --validation "npm test"
$ brainfile contract activate --parent epic-1     # every draft under the epic → ready
$ brainfile contract graph --show

The whole lifecycle is in Contracts.

$ brainfile mcp

Speaks MCP over stdio; your agent launches it, you never run it by hand. It tells the agent to use its tools for every board change and never to edit .brainfile/ by hand. Tools and setup are in For agents.

$ brainfile hooks install claude-code
$ brainfile hooks install cursor --scope project
$ brainfile hooks list
$ brainfile hooks uninstall cline --scope all

Supports claude-code, cursor and cline, at user (default) or project scope. The hooks nudge the agent to update the board after it edits files, and when a session starts they hand it its brief: for Claude Code as hookSpecificOutput.additionalContext, for Cline as text. The session-start hook runs from a lean entry that loads the brief and nothing else, about 150ms warm; it names the agent from BRAINFILE_AGENT, else the tool (claude, cline), and moves that agent's brief checkpoint. BRAINFILE_BRIEF_MAX_CHARS changes its budget.

$ brainfile dispatch task-12 --agent codex
$ brainfile dispatch task-12 task-13 --agent claude --model opus --effort high
$ brainfile dispatch --column todo --agent claude      # every open task in To Do
$ brainfile dispatch --parent epic-3 --agent codex     # the epic's open children
$ brainfile dispatch task-12 --agent codex --until done
$ brainfile dispatch task-12 --agent codex --now       # and run it here until it ends
$ brainfile dispatch epic-3 --agent claude             # a lead for the epic

Writes dispatch: on each task (the agent, model, effort, until, who asked and when) and makes the agent its assignee; one commit on a tracked board. With no --agent, a task goes to the agent it was last handed to, else its assignee when that is an agent. --until review (the default) stops the work in Review for you; --until done lands it on its own where the repository's permission policy is bypass (dispatch policy, below). A task an agent is still at, or a runner holds, is skipped and said so; so are decisions. A task already queued with the same request is said so, and nothing is written again. A task named that has open children (an epic) gets a lead instead: see Leads. A task whose dependsOn are open, or complete with their branch not landed, is queued and waits until they have landed. At most dispatch.maxRunning in the board's config (else the repository's setting in the app, else 3) run at once on a repository.

When no runner is up on this machine it says so: Run brainfile run or open Brainfile to start it. --now runs the tasks here in the foreground instead, through brainfile run's loop given only these tasks, until each has ended (and, with --until done, landed or been sent back); the agent's questions come to this terminal, and Ctrl-C lets go of them as run does. A task that waits on its dependencies is said so once (task-2 waits on task-1: it runs here once that has landed) and starts here once they have landed, while anything of this run is still going: dispatch task-1 task-2 --now --until done lands task-1, then runs task-2 from the result. One still waiting when nothing more is going stays queued for a runner, and is said so; when nothing asked for could run here at all, the command exits with status 1. --json prints what was queued and skipped.

$ brainfile dispatch policy                 # what it is now, and where it is kept
$ brainfile dispatch policy bypass          # this repository: --until done lands on its own
$ brainfile dispatch policy ask             # this repository: everything stops in Review
$ brainfile dispatch policy clear           # take the repository's own off; the app-wide setting decides
$ brainfile dispatch policy bypass --all    # the app-wide setting, for repositories without one of their own

How asks are answered on a repository, and so how far a hand-off goes on its own: in a bypass repository a hand-off asked for --until done is checked and landed by its runner when its agent finishes, and an epic's lead lands each child; with ask (the default) every hand-off stops in Review for you, and an agent that asks before it acts is answered by whoever runs it (the window's band, the terminal's prompt). The setting lives in dispatch.json in the data folder, shared with the Brainfile window, whose Settings write the same file: ~/Library/Application Support/Brainfile on a Mac, %APPDATA%\Brainfile on Windows, $XDG_DATA_HOME/brainfile (~/.local/share/brainfile) elsewhere, or BRAINFILE_DATA_DIR when set. With no argument it prints the policy in force, where it comes from (the repository's own setting, the app-wide one, or the default) and the file. It is yours: an agent's role, whatever it is, is refused, even to read it, and there is no MCP tool for it.

$ brainfile run                 # until Ctrl-C
$ brainfile run --once          # until nothing more can start
$ brainfile run --max 1         # one hand-off at a time from here
$ brainfile run --until done    # a request that names nothing lands on its own

A runner in the foreground, to leave open in a terminal split; not a daemon. While it is up its file in .brainfile/state/runners/ says so (so dispatch stops saying no runner is up), and it looks at the queue every second: it claims each queued task, oldest request first, starts its agent in its worktree, and takes up an epic's lead the same way, then starts the children the lead hands off inside the lead's rules. At most dispatch.maxRunning run at once on the repository, whichever runner runs them; --max N keeps this one to N of them. The Brainfile window and another brainfile run work the same queue: each task is claimed by one runner, by compare-and-swap on its file, so two never start one task.

It prints one plain line per change:

task-74 · codex · editing
task-74 · codex · running
task-74 in Review
epic-6 · lead · claude · leading
task-75 · codex · done, landing it
task-75 landed

When an agent asks before it acts, the question comes to this prompt, one at a time, naming the run (task-74 · codex asks: Run npm test), with the agent's own choices by number (Allow once, Always, Deny). An ask whose run stops is taken down. With no terminal to answer in, it is refused.

Ctrl-C lets go: the agents stop and their run files end, each task it held goes back to the queue on the board (its request stays, its claim is cleared) for the next runner, and a lead it ran waits for a runner to take it up from its notes. Worktrees stay as they are. What it wrote on the board is committed before it exits. A second Ctrl-C leaves at once; its claims are then taken again once its process is gone.

--once returns when nothing it started is still going and nothing queued can start, and says what is still queued and what each waits on. A lead it ran that waits on you (children in Review, or waiting to be handed off) is let go as on Ctrl-C. --until review|done is how far a hand-off goes when its request names neither.

$ brainfile discuss task-12
$ brainfile discuss task-12 --agent claude --model opus --effort high

Opens a session with an agent about one task, at any stage of its life, under the same rules as the desktop's Discuss (decision-19). The agent first gets what the board says about the task (its stage, description, subtasks, contract, the decisions it rests on, its latest notes, the board's other decisions, and its branch, worktree and the agent on it now, if it was handed off), the rules, and says where the task stands. Then each line you type is sent to it and its reply is printed.

The session is core's, opened through a runner as run opens its agents; its brainfile mcp runs in role discuss. It never runs in bypass, and runs in the agent's read-only mode when it has one. The agent may read the code and the board, run git that only reads, and with your yes change the task's description, subtasks and contract, record decisions and note what was agreed. An edit, any other command, a change of mode, or a board tool beyond those is refused before you are asked. Anything else it asks before it acts (reading a file, say) comes to this prompt as in run: Allow once, Always, Deny.

With no --agent it is the agent the task was last handed to, else its assignee when that is an agent, else the first installed here.

Ctrl-C, or the end of input, ends it: once you have said something, the agent is told you are done, and notes what was agreed on the task if it has not yet. A second Ctrl-C leaves at once. Then the session is let go and what was written on the board is committed.

$ brainfile dispatch status
$ brainfile dispatch status --json
$ brainfile dispatch stop task-12           # or its run id, run-…

status is the runners up on this machine, every live hand-off (its task, agent, model, what it is doing or asking, and which runner has it), the queue in order with what each task waits on, and the tasks a runner holds, marked lost when its runner has gone so another may take it. It reads the board and every runner's run files, whichever process started them.

stop stops a run by its id or its task's: it leaves .brainfile/state/runs/<run-id>.stop.json beside the run's file, and the run's own runner stops it within a second; no process is ever signalled from another. The command waits up to 15 seconds to say it has stopped. The worktree and branch stay for review, and the claim is given back as stopped. Handed off again, a task that was stopped carries on the same try.

$ brainfile dispatch epic-3 --agent claude --model opus
$ brainfile dispatch epic-3 --agent claude --now   # lead it here until it ends
$ brainfile dispatch pause epic-3
$ brainfile dispatch resume epic-3
$ brainfile dispatch stop epic-3

An epic, or any task with open children, is run by a lead (decision-15): an agent that writes no code. It checks the plan first (which children touch the same code, whether the dependencies are right, whether one child wires the parts together), writes the plan as a note on the epic, then hands the children off in order, and is woken with a new turn when one ends, lands or is sent back. Its brainfile mcp is started as the lead of that epic, so its dispatch, dispatch_status and dispatch_stop reach only the tasks under it; it may read the code and run git commands that only read.

dispatch <epic> writes the lead's request on the epic: dispatch: with role: lead. A runner that takes up leads (brainfile run, the Brainfile window when you press Resume, or --now here) claims it, as it claims a task, so one lead runs a tree, whichever process or machine; a tree that already has one, above or under the epic, is refused. The runner holds the rules the lead cannot bend, and checks them again before it starts what the lead asks for:

• a child goes only once its dependsOn are done and their branches landed;
• at most dispatch.maxRunning hand-offs at once on the repository;
• a child is tried at most its contract's maxRetries again (once by default), counted in tries on its record (a start after a stop, or after its runner went away, carries on the same try); then it waits in Review for you, with a note saying so;
• only children under the epic with none of their own;
• in its tree only the lead and you hand off: the board's chat is refused;
• children it adds after it started, and children whose contract is still a draft, wait for you to hand them off, unless the repository's permission policy is bypass, where the lead also lands each child that ends in Review.

When the last child is done the epic is completed, or, with a branch of its own (epicBranch: true), waits in Ready to merge. The lead's record comes off and the lead ends. A lead taken up when every child is complete but some have not landed finishes the epic: in a bypass repository it lands them first; otherwise it waits for you to merge them. An epic with a branch of its own whose last child lands with no lead (land, Merge) waits in Ready to merge the same way.

pause marks the record paused: the lead hands off nothing and what happens waits for its next turn; what is running goes on. resume takes that off and the lead carries on; a lead no runner holds (its runner went away) waits for one, and takes up from its notes on the epic. stop takes the record off: the lead ends, and what it handed off goes on and is yours. Each works whichever runner leads it, which follows the epic's record. dispatch status lists the leads: waiting for a runner, leading or paused, and where. A lead the Brainfile window ran before leads moved to core (lead: on the epic) is not taken up on its own: it is listed paused, and resume (or the window's Resume) carries it on from its notes.

$ brainfile review task-12          # branch, commits, files, conflicts; can it land?
$ brainfile review --ready          # every hand-off that can land now
$ brainfile land task-12            # check, then land on its target
$ brainfile land task-12 --into release/2.0
$ brainfile discard task-12         # throw the worktree and branch away

review shows the task's branch and where it lands, its commits and the files they change, files not yet committed in the worktree, and the files that would conflict with its target now (git's merge-tree, nothing written). --ready lists the hand-offs that can land: commits not yet in their target, nothing uncommitted, no pull request open, and no agent at them.

land lands it as the window's Merge does (decision-12): its contract's validation runs in its worktree with the target brought in, then it merges, serially, and the task completes unless subtasks are left. A conflict or a failed check goes back to the agent that did the work, with a note on the task saying what collided and how to settle it, queued for a runner, up to the contract's maxRetries; past that the task waits in Review for you, and land exits non-zero. discard removes the worktree, uncommitted work and all, and the branch. Both are refused while an agent is at the task.

$ brainfile agents
$ brainfile agents --json

Every agent Brainfile knows and every one of your own (kept in dispatch.json in the app's data folder, shared with the desktop), whether it is installed on this machine, and the models each offered when it last started.

$ brainfile plan add -t "Thin-frontend refactor" --status draft
$ brainfile plan list --status active
$ brainfile plan show plan-1 --json
$ brainfile plan link plan-1 -t task-42

add takes -c, --description, --tags, --parent (an epic or a spec) and a free-form --status. link sets the task's parentId to the plan, so list --parent plan-1 finds a plan's tasks. plan is a built-in type, so a strict board needs no types: entry for it.

$ brainfile decide -k dependency.http-client "Use undici for HTTP. It ships with Node."
$ brainfile decide -k dependency.http-client --kind constraint \
    --stance forbids --subject axios "Never axios: one HTTP client"
$ brainfile decide -k release.window --valid-until 2026-12-31 \
    --recheck "Ask the release manager" "Release on Tuesdays"
$ brainfile decide -k storage.index --source docs/index.md "Index with SQLite FTS5"
$ brainfile decide -k runtime.node --package "engines.node>=20" --for task-12 "Support Node 20+"
$ brainfile supersede decision-3 "Use fetch: it retries now"
$ brainfile retire decision-4 --as rejected --note "Too costly to run"

decide needs -k/--claim-key and the text (- reads stdin; the first line is the title unless --title). When the family already has a current decision, that one is superseded and moved to logs/; when the family was empty, it lists related families (the same parent key, or the same words) in case the call already exists under another key. Saying again exactly what the family's current decision says changes nothing. --no-supersede leaves both current, and check will say review. --source records the file's sha256 relative to the project root; --package a version predicate; --for adds the decision to the listed work's decisions:.

supersede <id> replaces one decision by hand, keeping its claim key and kind unless you give others. retire <id> --as rejected|stale moves a decision to logs/ with that status and an optional --note. Each command is one board commit on a tracked board. list --type decision lists them all, current first; show prints one with its chain.

$ brainfile add -t "Use SQLite for the index" --type decision
$ brainfile adr promote -t adr-1

ADRs are decisions: --type adr writes a decision, and an existing type: adr file reads as one and keeps its ID. promote marks a legacy ADR accepted and moves it to logs/. Current decisions and accepted ADRs appear in every brief.

$ brainfile check "use axios for the retry client"
$ brainfile check decision-3
$ brainfile check --claim-key dependency.http-client
$ brainfile check --claim-key-prefix dependency "add axios"
$ brainfile check "add axios" --json

check finds the claim family an action touches (a decision ID, a claim key, or its words: the local index when there is one, a scan of the decisions when there is not) and answers in this order:

--claim-key-prefix checks every family under a prefix and gives the worst verdict. Errors (no board, bad arguments) exit 1. --json prints the verdict, recommendation, reason, the predicates as evaluated and the family.

$ brainfile columns                                   # list, with task counts
$ brainfile columns add "In Review" --after in-progress
$ brainfile columns add Shipped --completion
$ brainfile columns rename in-review Review
$ brainfile columns reorder backlog todo in-progress
$ brainfile columns remove review --move-to in-progress

Columns are named by ID or title. add makes the ID from the title (In Review is in-review) unless --id gives one, and puts the column last unless --after or --before says where; --completion marks a column whose tasks count as done. rename changes the title only: the ID stays, so the tasks in it stay. reorder puts the columns you name first, in that order, and the rest after them. remove refuses a column that still holds tasks unless --move-to names where they go; they move there first, without being completed. The last column is never removed. Every command takes --json, and each change is one board commit on a tracked board.

$ brainfile types
$ brainfile types list --json
$ brainfile types add bug --like task
$ brainfile types add rfc --like spec --id-prefix rfc --schema ./rfc.json

$ brainfile types
Strict mode: off

  TYPE      ID          GOES UNDER                 HOLDS
▸ epic      epic-N      top level                  spec · plan · task
◆ spec      spec-N      epic                       plan · task
⎘ plan      plan-N      epic · spec                task
  task      task-N      epic · spec · plan · task  task                alias issue
● decision  decision-N  never in the tree          —                   alias adr · no column, never completed

  bug       bug-N       epic · spec · plan · task  task                like task

--like takes a built-in's place; without it a type behaves as a task. An alias name (adr, issue) cannot be added as a type of its own.

$ brainfile template --list
$ brainfile template --use bug-report --title "Login times out" -c todo

Three templates ship: bug-report, feature-request and refactor, each with a default priority, tags and a subtask checklist.

$ brainfile lint
$ brainfile lint --fix
$ brainfile lint --check   # non-zero exit for CI

--fix also folds a legacy rules: block into agent.instructions. lint also checks the graph: a parent that is missing, loops or does not fit the type, decisions: that name nothing or something other than a decision, and a like: that names no type, and a dispatch: record a runner cannot read. Off-pattern links are warnings, and errors on a strict board. It also checks where the board lives: two boards that disagree are an error; the board branch checked out away from .brainfile/, a checkout whose folder is gone (--fix forgets it), and a code branch still tracking an old copy are warnings. So is a landsOn that names a branch the repository has neither locally nor on origin.

$ brainfile index            # bring it up to date and say what changed
$ brainfile index --rebuild  # drop it and index from scratch
$ brainfile index --status   # what is in it

Never required: every search, brief and check brings the index up to date first. Unchanged files (same size and modification time) are not read; a changed file replaces its chunks; a deleted one drops out. Inside git the project's files come from git ls-files, so .gitignore is honoured; root AGENTS.md and CLAUDE.md are read even when ignored. Markdown and text only, 256 KiB a file at most, never node_modules, dist and the like, never .brainfile/ (the board is indexed on its own terms), never your home folder. Where Node has no node:sqlite (below 22.13) it says so; search, brief and check scan instead.

$ brainfile schema               # list
$ brainfile schema board --json
$ brainfile schema update        # check brainfile.md for a newer version

Bundled with the CLI, so validation works offline. Update checks run at most once a day and never block.

$ brainfile migrate --dir ./old-project
$ brainfile migrate --to-branch            # move the board onto its own branch
$ brainfile migrate --to-plain             # back to a plain directory

Flags: --dir, --force, --logs-to-ledger, --to-branch, --to-plain. --to-branch keeps the board's history when it was committed on the code branch (git subtree split), imports a gitignored one as a fresh branch, and folds a standalone board repository into the surrounding repository. Board changes not yet committed come along as one more commit on the branch. If any step fails, the migration undoes itself and the repository is left as it was. When the code branch tracked the board, one commit on it drops .brainfile/ and adds it to .gitignore (anything else you had staged stays staged); push it like any commit. Run on a board already on its branch, it makes that commit if the code branch still tracks an old copy. If a board already lives on the brainfile branch, this folder and it are two boards, and --to-branch says so and points to merge-boards. --to-plain leaves the branch intact.

$ brainfile where
$ brainfile where --fetch          # ask the remote for its copy first
$ brainfile where --json

Prints the board's location, how it is stored (plain files, a branch of this repository, or its own repository), the remote it is shared through, when it last synced, how many changes are waiting to be sent and how many on the remote are not here yet. It also looks for every other copy of the board in the repository (see One board per repository) and says when one disagrees with this one. It touches the network only with --fetch, so it is always safe to run.

$ brainfile adopt refs/brainfile/remotes/origin/board   # take that board as it is
$ brainfile adopt .brainfile                            # keep this folder
$ brainfile merge-boards refs/heads/brainfile           # combine them by document ID
$ brainfile backups                                     # what was saved
$ brainfile backups restore 20261012T205217Z-folder     # put one back

When a repository has two boards (see One board per repository), these make it one. adopt <ref|path> takes the named board as it is. merge-boards <ref|path> combines this board with the named one by document ID, with the same rules sync uses: frontmatter fields by updatedAt, logs unioned in time order, completion over an edit. One ID on two different documents (created apart, with unrelated titles) keeps the older; the newer gets the next free ID, a log line saying so, and every reference to it on its board rewritten. When one board already has everything the other has, merge-boards says so and adopts it without asking.

Both end the same way: the board on the brainfile branch, checked out at .brainfile/, descending from what the branch and the remote's copy had (so the next sync is a plain push), with any other checkout of the branch removed once its changes are committed. If the code branch still tracked .brainfile/, one commit on it stops tracking the folder and adds it to .gitignore; push that like any commit. Every board that is replaced is saved first as refs/brainfile/backups/<UTC time>-folder or -branch; backups lists them and backups restore <name> puts one back, backing up what it replaces. Backups stay on this machine unless you push one by name.

$ brainfile fix --dry-run                 # what is wrong, and what fix would do
$ brainfile fix                           # do it
$ brainfile fix --expected "Back up both, then untrack main's copy"
$ brainfile fix --undo                    # put it back, within 20 seconds

The desktop app's Fix, from the command line. It says what is wrong with where the board lives, in the words the desktop's health list uses, and what fix would do, then does it, as long as that is still the plan it printed (--expected names the plan as --dry-run said it, for a script or an agent). It only offers a fix that loses nothing: the copy it keeps already has every document every other copy has, each the same or newer. It backs up every copy first, as adopt does, and changes nothing if a backup fails. Then it does one of three things: stops the code branch tracking an old copy of .brainfile/ (one commit, as migrate --to-branch makes), adopts the copy that has everything (two copies, a checkout outside .brainfile/, or the board branch checked out twice), or forgets a checkout whose folder is gone.

An unfinished merge, two copies that each have changes, a board that is its own repository and a checkout with uncommitted work are never fixed: fix says so, and adopt or merge-boards is your call. For 20 seconds after a fix, --undo puts back what it changed, whether the CLI, an agent or the desktop ran it (the fix is kept in .brainfile/state/last-fix.json). It backs up the board it replaces first, and refuses if the board or the code branch has moved on since; after that, backups has every copy.

$ brainfile sync                                  # fetch, merge, push
$ brainfile sync --pull                           # one direction
$ brainfile sync --set-remote origin              # the code remote
$ brainfile sync --set-remote git@host:me/boards.git --board-name myproject
$ brainfile sync --autosync full                  # off | push | full

Fetches the board, fast-forwards or merges with the board-aware merge driver, and pushes it to refs/brainfile/<name> on the remote. Runs entirely inside the board directory; the code tree is never touched. --set-remote in a repository that has no board yet checks the board out from that remote. Details in Sharing a board.

$ brainfile archive -t task-1                    # same as complete
$ brainfile archive -t task-1 --to github
$ brainfile archive --all --to linear --dry-run
$ brainfile restore -t task-1 -c in-progress -r "phase C is left"

restore reopens work completed too soon: the task comes back from logs/ to the column you name, its ledger record goes (completing it again writes a new one), and its log says it was reopened, with --reason if you gave one. A decision is not reopened: supersede it, or decide again. On a v1 board it brings a task back from brainfile-archive.md.

Exports create an issue in the configured GitHub repo or Linear team; set the destination with config set archive.github.owner, archive.github.repo or archive.linear.teamId, and archive.default for the default target.

$ brainfile auth github            # OAuth device flow
$ brainfile auth github --token ghp_…
$ brainfile auth linear --token lin_api_…
$ brainfile auth status
$ brainfile auth logout --all

$ brainfile config path            # ~/.config/brainfile/config.json
$ brainfile config list
$ brainfile config set archive.default github

Holds archive destinations, auth and the schema update timestamp. Nothing about a specific board lives here.

When an agent makes the change, the commit message ends with its name in brackets, and notes carry the same name. brainfile works out the agent in this order:

• --agent <name> or BRAINFILE_AGENT, when the agent says who it is.
• The nearest agent CLI above the command: claude, codex, cursor-agent, gemini, opencode, goose, droid, crush, aider, cline, amp, qwen or copilot.
• Variables agents set for the commands they run, for sandboxes that hide the process tree (Codex's CODEX_THREAD_ID, Claude Code's CLAUDECODE).

Commands you type yourself get no tag, and your notes carry your git user.name. Desktop apps and editors don't count as agents, because their built-in terminals are yours. BRAINFILE_DETECT_AGENT=off keeps only names given explicitly.

The branch is hidden, not secret. A plain git push sends only your code branch, but git push --all, --mirror and mirroring tools push every local branch, the board included. Once the board is on a remote, anyone who can read that remote can read it. The point is a clean main, not privacy; for private notes next to public code use a separate remote (below).

Two worktrees of the repository share the board directly. A clone gets it the first time you run brainfile there: brainfile asks the remote once for a shared board, checks it out into .brainfile/, says so (Checked out the shared board from origin into .brainfile/), and sends changes back to the remote it came from. If the remote has no board, brainfile does not ask again for ten minutes; sync --set-remote always asks. Someone who never runs brainfile never sees the folder.

Outside a repository, init --tracked makes the board its own small repository; the home board brainfile init -g is always one. Both take the same sync commands.

Any MCP client can talk a task over with you. The server's discuss prompt takes taskId and gives the agent what the board says about the task: its stage, description, subtasks, contract, the decisions it rests on, its latest notes, the board's other decisions, and its branch, worktree and the agent on it now, if it was handed off. Then the rules a discussion keeps, the same as in the desktop's chat (decision-19):

• It changes only this task's description, subtasks and contract, and only after you say yes.
• It runs check before recording a decision, and records one only after you agree to it.
• It adds a note saying what was agreed.
• It writes no code and hands nothing off.

The discuss tool returns the same text, for clients that do not support prompts. The client keeps to the rules itself: a server cannot refuse its own client's edits. brainfile discuss (see Hand-offs) opens the session itself and holds the rules for it.

Whoever starts brainfile mcp for an agent says what the agent is to the board in BRAINFILE_AGENT_ROLE: chat, lead, worker or discuss. The runner does so for every agent it starts, the desktop for its chat, leads and discussions, and brainfile discuss for its session.

The agent's own environment carries the role too, so the command line in its shell keeps to it: as a worker, brainfile dispatch, land, discard and pr (without --status) are refused, and a lead's reach only its tree. No agent runs brainfile run, dispatch --now or discuss, which would start agents inside its own turn; the runner that started it works the queue.

What agents may do on their own in a repository is yours alone: the permission policy (ask, or bypass, where a hand-off asked for until done lands on its own and a lead lands each child) is read and written by brainfile dispatch policy and the window's Settings, and lives in dispatch.json in the data folder: ~/Library/Application Support/Brainfile on a Mac, %APPDATA%\Brainfile on Windows, $XDG_DATA_HOME/brainfile elsewhere, or BRAINFILE_DATA_DIR when set. Any agent's role is refused it, even to read.

{
  "mcpServers": {
    "brainfile": {
      "command": "npx",
      "args": ["brainfile", "mcp"],
      "env": { "BRAINFILE_AGENT_ROLE": "lead", "BRAINFILE_LEAD_SCOPE": "epic-3" }
    }
  }
}

This is a rule for agents, not a security boundary: anyone on the machine can run the CLI.

Some commands have no tool, on purpose: tui, run and mcp (they are the interfaces; run works what the dispatch tools queue), merge-driver (git runs it), hooks (events the agent host fires, and your agent's settings), auth and config (your credentials and user config), init and migrate (one-off, and your call), adopt, merge-boards and backups (which of two boards is the board is your call: until it is made, every write refuses and names them), dispatch policy (what agents may do on their own is never theirs to change) and index (a cache that search, brief and check refresh). Choosing the remote a board is shared through, and its autosync mode, also stays with you (brainfile sync --set-remote, --autosync). A test holds the CLI and the server to this: a new command fails it until it has a tool or a reason here.