mana

Mana is a local-first coordination system for AI coding agents. It turns work into durable Markdown records with clear scope, dependencies, verification gates, attempts, notes, and facts.

Use it when agent work needs to survive beyond one chat session: planning, delegation, retries, handoffs, audits, and multi-step implementation.

mana init
mana create "Add CSV export" --verify "cargo test csv::export"
mana status

Why mana

Coding agents are effective, but their default working medium is fragile:

• plans live in prompts or ad hoc Markdown files
• “done” is ambiguous
• retries restart without context
• dependencies stay implicit
• useful failures disappear into logs

Mana gives that work a durable shape:

• tasks describe executable work
• epics organize larger efforts
• verify gates define completion
• dependencies encode order
• attempts and notes preserve execution history
• facts capture verified project memory

Everything lives in .mana/ as plain files, so the system is inspectable, git-friendly, local-first, and usable by any agent that can read files and run shell commands.

Installation

cargo install mana-cli

Build from source:

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

Quick start

Initialize mana in a project:

mana init

Create a task with a verify gate:

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

Inspect the queue:

mana status
mana next
mana show 1

Work the task manually or hand it to an agent:

mana claim 1
# make changes
mana verify 1
mana close 1

If you use an agent runtime, configure it once and dispatch through mana:

mana config set-project run "imp run {id}"
mana run 1

[!TIP] Prefer targeted verify commands. cargo test parser::handles_unicode is usually a better task gate than a broad project-wide test suite.

Core concepts

Task

A task is one executable unit of work. It should have a concrete goal, useful context, relevant paths, and a verify command that exits 0 when the task is complete.

mana create "Fix login redirect" \
  --verify "cargo test auth::redirect" \
  --paths "crates/app/src/auth.rs,crates/app/tests/auth.rs"

Epic

An epic is a non-dispatchable parent for larger work. Use epics for features, migrations, audits, and refactors that need decomposition before execution.

mana create "Improve onboarding flow" --epic
mana create "Add empty-state copy" --parent 1 --verify "cargo test onboarding_empty_state"

Fact

A fact is verified project knowledge. Facts are useful for architecture notes, environment requirements, and constraints that agents should not rediscover repeatedly.

mana fact "Tests require Docker" --verify "docker info >/dev/null 2>&1" --ttl 90
mana verify-facts

Verify gate

A verify gate is a shell command attached to a task. mana close <id> runs the command before closing the task. If it fails, the task stays open and the failure is recorded for the next attempt.

How it works

Mana stores records in .mana/:

.mana/
├── config.yaml
├── index.yaml
├── 1-add-csv-export.md
├── 2-improve-errors.md
├── 2.1-add-error-type.md
└── archive/2026/04/

A task is a Markdown file with YAML frontmatter:

---
id: "1"
title: Add CSV export
kind: task
status: open
verify: cargo test csv::export
paths:
  - crates/app/src/export.rs
  - crates/app/tests/export.rs
---

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

Acceptance:
- existing JSON export behavior is unchanged
- CSV output includes headers
- `cargo test csv::export` passes

The normal loop is:

1. define the work as a task
2. claim or dispatch it
3. attempt the implementation
4. run the verify gate
5. close on success, or record failure context and retry

Working with agents

Mana is agent-agnostic. Any runtime can work from mana as long as it can read files and run commands.

Configure command templates with {id} placeholders:

mana config set-project run "imp run {id}"
mana config set-project plan "imp plan {id}"

Useful commands while agents are working:

mana agents      # running and recently completed agents
mana logs 3      # logs for unit 3
mana status      # claimed, ready, blocked, and grouped work
mana context 3   # agent briefing for a unit

mana context <id> is the agent handoff surface. It assembles the unit spec, prior attempts, dependencies, project rules, and relevant files into one briefing.

Planning and decomposition

Use epics and child tasks when work is too broad for one safe attempt:

mana create "Refactor import pipeline" --epic
mana create "Extract parser interface" --parent 1 --verify "cargo test parser_interface" --produces ParserInterface
mana create "Move CSV parser" --parent 1 --requires ParserInterface --verify "cargo test csv_parser"
mana create "Move JSON parser" --parent 1 --requires ParserInterface --verify "cargo test json_parser"

Dependencies can be explicit:

mana dep add 3 2
mana tree 1

Or artifact-based:

mana create "Define schema" --produces Schema --verify "cargo test schema"
mana create "Build query engine" --requires Schema --verify "cargo test query"

Sequential work can be chained:

mana create "Step 1: scaffold" --verify "cargo check"
mana create next "Step 2: implement" --verify "cargo test feature"
mana create next "Step 3: document" --verify "grep -q 'Feature' README.md"

Fail-first checks

By default, mana expects a task’s verify command to fail when the task is created. This prevents creating tasks whose completion check already passes.

Use --pass-ok for refactors, documentation, cleanup, or safety checks where the command may already pass:

mana create "Clean clippy warnings" --verify "cargo clippy --workspace --all-targets -- -D warnings" --pass-ok
mana create "Rewrite README" --verify "grep -q '## Quick start' README.md" --pass-ok

Command overview

# lifecycle
mana create "title" --verify "cmd"
mana create "title" --epic
mana quick "title" --verify "cmd"
mana claim <id>
mana update <id>
mana verify <id>
mana close <id>
mana reopen <id>
mana delete <id>

# graph and queue
mana status
mana next
mana list
mana show <id>
mana tree [id]
mana graph
mana trace <id>

# dependencies and memory
mana dep add <id> <dep-id>
mana dep remove <id> <dep-id>
mana fact "title" --verify "cmd"
mana verify-facts
mana recall "query"

# agents and context
mana context [id]
mana run [id]
mana plan <id>
mana agents
mana logs <id>
mana review <id>
mana diff <id>

# maintenance and integration
mana tidy
mana doctor
mana doctor fix
mana config inspect
mana mcp serve
mana completions <shell>

See command-specific help for options and examples:

mana create --help
mana run --help
mana config --help

Pipe-friendly usage

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

Configuration

Project configuration lives in .mana/config.yaml. Global configuration lives under the user mana config directory.

mana config set-project run "imp run {id}"
mana config set-project plan "imp plan {id}"
mana config set-project max_concurrent 4
mana config set-project batch_verify true
mana config inspect

Common settings:

Key	Description
run	Agent command template for task execution. {id} is replaced with the unit ID.
plan	Agent command template for decomposing larger work.
run_model	Default model for run-compatible agent flows.
plan_model	Default model for planning flows.
review_model	Default model for review flows.
max_concurrent	Maximum parallel agents.
max_loops	Maximum run-loop cycles before stopping.
verify_timeout	Default verify timeout in seconds.
rules_file	Rules file included in mana context.
file_locking	Avoid scheduling concurrent tasks with overlapping paths.
batch_verify	Run shared verify commands once after agents complete.
auto_close_parent	Close parent units when all children are closed.
auto_commit	Commit changes when a unit closes.
on_close / on_fail	Hook templates for close and failure events.

[!WARNING] Do not store secrets in mana config or unit files. Use environment variables or your agent/runtime’s secret mechanism.

MCP integration

Mana includes an MCP server for IDE and agent integrations:

mana mcp serve

The MCP surface exposes project status, unit context, tree views, and common unit operations to compatible clients.

Development

cargo check --workspace --all-targets
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --check

The workspace contains:

• crates/mana-core - durable model, operations, config, index, graph, verification
• crates/mana-cli - CLI commands, output, MCP server, runtime adapters

Documentation

• mana --help - command groups and examples
• mana <command> --help - detailed command help
• CONTRIBUTING.md - contribution workflow
• CHANGELOG.md - release history