mana

Mana is the medium for coding agent work: it gives that work structure, verification, dependencies, and memory.

It turns work that would normally disappear into prompts and scrollback into durable units that can be verified, retried, decomposed, and built on over time.

Plain Markdown files in .mana/. Any agent that can read files and run shell commands is fluent in mana.

mana init --agent claude
mana create "Add CSV export" --verify "cargo test csv::export"
mana run

Contents

• Why mana exists
• The core model
• Install
• Quick start
• How mana works
• Working with agents
• Fail-first development
• Decomposition and dependencies
• Facts and memory
• Command reference
• Configuration
• Documentation

Why mana exists

Coding agents are powerful, but their work is usually ephemeral.

• The plan lives in a prompt
• "Done" is often vague
• Retries start cold
• Dependencies stay implicit
• Useful lessons vanish into logs

Mana gives that work a durable shape.

A unit says what to do. A verify gate says how to know it's done. Dependencies say what it relies on. Attempts, notes, and facts record what was learned.

Agents come and go. Mana keeps the work legible.

The core model

Mana is built from a few simple ideas:

Unit

A unit is one bounded piece of work.

It has:

• an ID
• a title
• a status
• a verify command
• optional description, acceptance criteria, paths, labels, and notes

Verify gate

Every unit has a verify gate: a shell command that must exit 0 before the unit can close.

This makes "done" machine-checkable.

Graph

Units form a graph through:

• parent / child relationships for decomposition
• dependencies for ordering
• produces / requires for artifact-based coordination

Memory

Mana keeps context with the work itself:

• failed attempts
• notes
• verified facts
• related files
• dependency context

Medium

Everything lives in .mana/ as plain files.

That means the system is:

• local-first
• git-friendly
• inspectable
• agent-agnostic
• resilient when any one tool or process dies

Install

cargo install mana-cli

git clone https://github.com/kfcafe/mana
cd mana
cargo build --release
cp target/release/mana ~/.local/bin/

Quick start

Initialize a project:

mana init --agent claude

Create a unit:

mana create "Fix CSV export" --verify "cargo test csv"

Create another:

mana create "Add pagination" --verify "cargo test page"

Dispatch ready work to your agent:

mana run

Watch what happens:

mana agents
mana logs 3
mana status

Manual workflow:

mana quick "Fix CSV export" --verify "cargo test csv"
mana verify 1
mana close 1

How mana works

Work lives in Markdown units inside .mana/:

.mana/
├── 1-add-csv-export.md
├── 2-add-tests.md
├── 2.1-unit-tests.md
└── archive/2026/01/

A unit looks like this:

---
id: "1"
title: Add CSV export
status: in_progress
verify: cargo test csv::export
attempts: 0
---

Add a `--format csv` flag to the export command.

**Files:** src/export.rs, tests/export_test.rs

When you run mana close 1:

1. Mana runs the verify command
2. Exit 0 → the unit closes and archives
3. Non-zero exit → the unit stays open and the failure is recorded for the next attempt

That simple loop is the foundation:

define → attempt → verify → learn → retry or close

Working with agents

Configure an agent once, then dispatch units to it:

mana init --agent claude

Or set the run template directly:

mana config set run "claude -p 'read unit {id}, implement it, then run mana close {id}'"

{id} is replaced with the unit ID.

Dispatching

mana run                    # Dispatch all ready units
mana run 3                  # Dispatch a specific unit
mana run -j 8               # Up to 8 parallel agents
mana run --loop-mode        # Keep dispatching until work is done
mana run --auto-plan        # Auto-split large units before dispatch
mana run --review           # Adversarial review after each close
mana run --dry-run          # Preview dispatch plan

Batch verify

When parallel agents share the same verify command (e.g. cargo build), each agent running it independently causes lock contention and redundant work. Enable batch verify to run each unique command once:

mana config set batch_verify true

With batch verify enabled:

1. Agents skip verify and exit after calling mana close
2. The runner collects all completed units
3. Groups them by verify command and runs each command once
4. Passing units close normally; failing units reopen for retry

Monitoring

mana agents                 # Show running/completed agents
mana logs 3                 # View agent output for unit 3
mana status                 # See what's ready, blocked, or in flight

Agent context

mana context <id> produces a complete briefing for an agent:

1. unit spec
2. previous attempts
3. project rules
4. dependency context
5. file structure
6. relevant file contents

mana context 5
mana context 5 --structure-only
mana context 5 --json
mana context                 # No ID: project-wide memory context

This is how agents stay grounded in the work instead of re-deriving context from scratch.

Fail-first development

Mana defaults to fail-first.

Before a unit is created, the verify command runs and must fail.

• If it already passes, the unit is rejected
• If it fails, the unit is accepted
• Later, mana close runs the same verify command and it must pass

# Rejected: verify already passes
mana quick "..." --verify "python -c 'assert True'"

# Accepted: real failing check
mana quick "..." --verify "pytest test_unicode.py"

Use --pass-ok (-p) when fail-first is not appropriate, like refactors or safety checks:

mana quick "extract helper" --verify "cargo test" -p
mana quick "remove secrets" --verify "! grep 'api_key' src/" -p

Decomposition and dependencies

Parent / child units

Break large work into smaller units:

mana create "Search feature" --verify "make test-search"
mana create "Index builder" --parent 1 --verify "cargo test index::build"
mana create "Query parser" --parent 1 --verify "cargo test query::parse"

mana tree 1

Parents can auto-close when all children close.

Dependencies

Coordinate units explicitly:

mana create "Define schema types" --parent 1 \
  --produces "Schema,FieldType" \
  --verify "cargo test schema::types"

mana create "Build query engine" --parent 1 \
  --requires "Schema" \
  --verify "cargo test query::engine"

Mana blocks work until its dependencies are satisfied.

Sequential chaining

mana create "Step 1: scaffold" --verify "cargo build"
mana create next "Step 2: implement" --verify "cargo test"
mana create next "Step 3: docs" --verify "grep -q 'API' README.md"

Each next unit automatically depends on the previous one.

Planning

mana plan 3
mana plan --auto
mana plan --dry-run

Use planning when a unit is too large or underspecified for a single attempt.

Facts and memory

Mana can also store verified project facts.

mana fact "DB is PostgreSQL" --verify "grep -q 'postgres' docker-compose.yml" -p
mana fact "Tests require Docker" --verify "docker info >/dev/null 2>&1" --ttl 90
mana verify-facts
mana recall "database"

Facts appear in context and can go stale if their verification expires or fails.

This gives agents a durable memory that lives outside chat history.

Command reference

Unit lifecycle

mana create "title" --verify "cmd"      # Create a unit
mana create "title" -p                  # Skip fail-first
mana create next "title" --verify "cmd"
mana quick "title" --verify "cmd"       # Create + claim
mana claim <id>
mana verify <id>
mana close <id>
mana close --defer-verify <id>
mana close --failed <id>
mana update <id>
mana edit <id>
mana delete <id>
mana reopen <id>
mana unarchive <id>

Orchestration

mana run [id] [-j N]
mana run --loop-mode
mana run --auto-plan
mana run --review
mana plan <id>
mana review <id>
mana agents
mana logs <id>

Inspecting the graph

mana status
mana show <id>
mana list
mana tree [id]
mana graph
mana trace <id>
mana context [id]
mana recall "query"

Dependencies and memory

mana dep add <id> <dep-id>
mana dep remove <id> <dep-id>
mana fact "title" --verify "cmd"
mana verify-facts

Maintenance and integration

mana tidy
mana doctor [--fix]
mana sync
mana locks [--clear]
mana config get/set <key> [value]
mana mcp serve
mana completions <shell>

Pipe-friendly usage

mana create "fix parser" --verify "cargo test" -p --json | jq -r '.id'
mana list --json | jq '.[] | select(.priority == 0)'
mana list --ids | mana close --stdin --force
cat spec.md | mana create "task" --description - --verify "cmd"
mana list --format '{id}\t{status}\t{title}'

Configuration

Project configuration lives in .mana/config.yaml.

mana config set run "claude -p 'read unit {id}, implement it, then run mana close {id}'"
mana config set plan "claude -p 'read unit {id} and split it into subtasks'"
mana config set max_concurrent 4

Key	Default	Description
run	—	Command template for agent dispatch. {id} = unit ID.
plan	—	Command template to split large units.
max_concurrent	4	Max parallel agents.
max_loops	10	Max agent loops before stopping (0 = unlimited).
poll_interval	30	Seconds between loop mode cycles.
auto_close_parent	true	Close parent when all children close.
verify_timeout	—	Default verify timeout in seconds.
rules_file	—	Path to rules file injected into mana context.
file_locking	false	Lock unit paths files during concurrent work.
extends	[]	Parent config files to inherit from.
batch_verify	false	Batch shared verify commands: run each once after agents complete.
auto_commit	false	Commit all changes on close. Skipped in worktree mode.
commit_template	feat(bean-{id}): {title}	Template for auto-commit messages. Vars: {id}, {title}, {parent_id}, {labels}.
on_close	—	Hook after close. Vars: {id}, {title}, {status}, {branch}.
on_fail	—	Hook after verify failure. Vars: {id}, {title}, {attempt}, {output}, {branch}.
post_plan	—	Hook after mana plan creates children.
review.run	—	Review agent command. Falls back to run.
review.max_reopens	2	Max review reopen cycles.

Config inheritance

# .mana/config.yaml
extends:
  - ~/.mana/global-config.yaml
project: my-app
run: "claude -p 'read unit {id}, implement it, then run mana close {id}'"

Child values override parent. Multiple parents are applied in order; later values win.

Use extends for shared non-secret defaults such as agent command templates or concurrency settings. Do not use it as a secret-distribution mechanism.

Documentation

• Agent Skill — Quick reference for AI agents
• Best Practices — Writing effective units for agents
• mana --help — Full command reference

Contributing

Contributions welcome. Fork the repo, create a branch, and open a pull request.

License

Apache 2.0