A file-based task tracker for developers and AI agents.
Heavily inspired by Steve Yegge's Beads that didn't really fit my workflow.
Tasks live as Markdown files with YAML frontmatter in a .bears/ directory — plain text, git-friendly, no database. Run bea from the terminal or expose the same functionality as an MCP server for AI coding agents.
cargo install bea-rsDownload the latest release for your platform:
curl -fsSL https://raw.githubusercontent.com/LHelge/bea-rs/main/install.sh | shThis detects your OS and architecture, downloads the right binary from GitHub Releases, and installs it to /usr/local/bin. Set BEA_INSTALL_DIR to change the install location. Falls back to cargo install if no pre-built binary is available.
git clone https://github.com/LHelge/bea-rs.git
cd bea-rs
cargo install --path .The binary is named bea.
bea init
bea create "Design the API" --priority P1 --tag backend
bea create "Implement endpoints" --priority P1 --tag backend --depends-on <id>
bea list
bea ready # what can I work on right now?
bea start <id>
bea done <id>Each task is stored as .bears/{id}-{slug}.md:
---
id: a1b2
title: Implement OAuth flow
status: open
priority: P1
type: task
created: 2026-03-15T10:30:00Z
updated: 2026-03-15T10:30:00Z
tags: [backend, auth]
depends_on: [f4c9]
parent: x9k2
---
Any Markdown body goes here.Statuses: open · in_progress · done · blocked · cancelled
Types: task (default) · epic (high-level objective grouping child tasks)
Priorities: P0 (critical) · P1 · P2 · P3 (low) — sorted P0 first everywhere. A task inherits the highest priority of any task that depends on it, so a P3 task blocking a P0 task is effectively treated as P0.
Create the .bears/ directory and .bears.yml config in the current directory.
bea initbea create "Title" [--priority P0-P3] [--tag tag1,tag2] [--depends-on id1,id2] [--body "..."] [--epic]Use --epic to create an epic instead of a regular task. Epics are high-level objectives that group child tasks via the --parent flag.
Hides done and cancelled tasks by default. Use --all / -a to show everything.
bea list
bea list --status open
bea list --priority P0
bea list --tag backend
bea list --epic <epic-id>
bea list --allShow tasks that are open and have all dependencies completed. Epics are excluded — only actionable tasks appear. This is the key command for agent workflows — always start here.
bea ready
bea ready --tag backend --limit 5
bea ready --epic <epic-id>bea show <id>bea update <id> --status blocked
bea update <id> --priority P0 --tag urgent,backend
bea update <id> --title "New title" --body "Updated description"List all epics with progress (done/total children).
bea epicsShortcuts for the most common status transitions:
bea start <id> # → in_progress
bea done <id> # → done
bea cancel <id> # → cancelledWhen all children of an epic are completed, the epic is automatically marked as done.
bea dep add <id> <depends-on-id> # add dependency (cycle-safe)
bea dep remove <id> <depends-on-id>
bea dep tree <id> # show dependency treeAdding a dependency that would create a cycle is rejected with an error.
Permanently delete a task file.
bea delete <id>Delete cancelled tasks. Use --done to also delete completed tasks.
bea prune
bea prune --doneShow the dependency graph as a tree. Hides done and cancelled tasks by default; use --all / -a to include them.
bea graph
bea graph --allMatches against title, body, tags, and ID. Hides done and cancelled tasks by default.
bea search "oauth"
bea search "oauth" --allOpen a task's .md file in your $EDITOR for direct editing. Falls back to $VISUAL, then vi. After the editor exits, the file is re-parsed and validated.
bea edit <id>Generate shell completions for bash, zsh, or fish.
bea completions bash
bea completions zsh
bea completions fishAdd to your shell config to enable completions:
# zsh — add to .zshrc
eval "$(bea completions zsh)"
# bash — add to .bashrc
eval "$(bea completions bash)"
# fish — add to ~/.config/fish/config.fish
bea completions fish | sourceEvery command accepts --json for machine-readable output:
bea --json list
bea --json ready --limit 3
bea --json create "New task" --priority P1bears can run as an MCP server, exposing all task operations as tools for AI coding agents.
bea mcp # starts MCP server over stdio| Tool | Description |
|---|---|
list_ready |
Tasks ready to work on (limit?, tag?, epic?) |
list_all_tasks |
All tasks with optional filters (status?, priority?, tag?, epic?) |
list_epics |
List all epics with progress |
get_task |
Full task details (id) |
create_task |
Create a task or epic (title, priority?, tags?, depends_on?, body?, type?) |
update_task |
Update fields (id, status?, priority?, tags?, assignee?, body?) |
start_task |
Set status to in_progress (id) |
complete_task |
Set status to done (id) |
cancel_task |
Set status to cancelled (id) |
prune_tasks |
Delete cancelled tasks (include_done?) |
add_dependency |
Add a dependency, cycle-safe (id, depends_on) |
remove_dependency |
Remove a dependency (id, depends_on) |
delete_task |
Permanently delete a task (id) |
search_tasks |
Full-text search (query) |
get_graph |
Adjacency list of all dependencies |
Add to your Claude Code MCP config (claude mcp add):
{
"mcpServers": {
"bears": {
"command": "bea",
"args": ["mcp"]
}
}
}cargo build
cargo test
cargo clippy
cargo fmtAll three of fmt, clippy, and test must pass cleanly before committing.
src/
main.rs Entry point — dispatch to CLI or MCP server
cli/
mod.rs CLI module root and dispatch
args.rs clap command and argument definitions
cmd.rs Command handlers (list, show, create, etc.)
mcp/
mod.rs MCP module root and server setup
params.rs Tool parameter structs (serde + JSON Schema)
tools.rs MCP tool implementations and tests
service.rs Business logic (create, update, epic progress, etc.)
store.rs Read/write .bears/ directory
task.rs Task struct, frontmatter parse/render, ID & slug
graph.rs Dependency graph, ready computation, cycle detection
config.rs .bears.yml configuration
error.rs Error types
.bears/ Task files (created by `bea init`)