PlanDB: A Local-First Issue Tracker Built for AI Agents, Not Humans

The Problem: Agents Work Without a Plan

The core mechanism is a compound graph, not a flat list. Tasks can contain subtasks to any depth, like folders. Dependencies connect tasks across those boundaries, like symlinks. For example, a 'Build API' subtask inside a Backend group can directly depend on a 'Define Schema' task inside a Database group. The graph tells agents exactly what is independent, which naturally leads to parallelization. The README shows a single `split` command turning a stuck task into three parallel subtasks. A `--dep` flag wires them into the correct execution order. This is a deliberate departure from the tree-only models that most task tools use.

Installation and Agent Auto-Configuration

The auto-configuration is a key differentiator. It means agents start using PlanDB without human intervention. The Claude Code skill adds a structured 6-phase workflow with command gotchas and anti-patterns. That is a real integration point, not just a command-line tool.

Working with the Graph: Commands and Data Flow

The README includes a demonstration where one Claude Code instance was given a single sentence: 'Build a GPT from scratch in Rust, then train it to do tool calling.' PlanDB planned the entire thing. The agent built a 3,769-line transformer in pure Rust and ran 7 RL experiments. The plan evolved from 6 to 20 tasks, splitting when work proved complex and pivoting when REINFORCE collapsed. That example is anecdotal, but it shows the intended use case. The graph structure is what enables this evolution.

Context Search and Knowledge Persistence

PlanDB includes a BM25 search across tasks, descriptions, context entries, and notes. The `plandb context` command records discoveries, blockers, and decisions. When an agent claims a related task days later, that context surfaces automatically via BM25. No one has to search for it or remember to pass it along. This is a knowledge layer that compounds across agents and sessions. The README claims this is what makes knowledge find you, not the other way around. It is a specific mechanism: BM25 is a well-known ranking function, so the search behavior is predictable. The `plandb search` command gives access to it from the CLI. This is a genuine feature for multi-agent setups where context is often lost between sessions.

Three Interfaces: CLI, MCP, and HTTP

PlanDB offers three interfaces. The CLI is for shell agents like Codex and Aider. The MCP server is for Claude Code, Cursor, and Windsurf. The HTTP API is for custom agents and dashboards. The README shows how to generate prompts for each with `plandb prompt --for`. This means you are not locked into one agent framework. The MCP integration is the most detailed, with a skill and rules file for Claude Code. The CLI is the most complete for manual use. This three-interface approach is a trade-off: it adds surface area, but it also means the tool can fit into different agent ecosystems without rewriting.

Operational Features: Critical Path and Live Dashboard

PlanDB includes `plandb critical-path` to show the longest dependency chain and `plandb bottlenecks` to show what blocks the most downstream work. These are useful for focusing agent effort. The `plandb watch` command provides a live terminal dashboard that refreshes as tasks complete. This is a real-time view, which is helpful when multiple agents are working in parallel. The README also mentions pre/post conditions. You can attach `--pre "schema must exist"` and `--post "all tests pass"` to tasks. Agents see these conditions when claiming and completing tasks. This adds a guardrail against premature completion. These features are not unique to PlanDB, but they are integrated into the graph model, which makes them more actionable.

Limitations and Alternatives

PlanDB is not for human-centric project management. It has no sprints, no human-facing UI beyond the terminal dashboard, and no collaboration features like comments or assignments for people. The README explicitly says it is for agents, not for humans planning at human speed. If your team needs to track work in a shared web interface, PlanDB is the wrong tool. The project is also early-stage, with the latest release at v0.2.1. The README does not document failure modes for the graph operations, such as what happens when a `pivot` conflicts with external dependencies. The BM25 search is local and does not scale to massive corpora. A real alternative is Linear or Jira, but those are cloud-based and built for human workflows. A more comparable alternative is a local task manager like Taskwarrior, which also uses a CLI and SQLite, but it does not have a compound graph or agent-specific integration. Taskwarrior's approach is flat tasks with tags and dependencies, not nested subtasks with cross-boundary links. That makes PlanDB more suited to agent-driven decomposition.

Maintenance, Licensing, and Upgrade Path

PlanDB is licensed under Apache-2.0, which permits commercial use and modification. The project is a single binary with SQLite storage, so there is no server to maintain. The installer is idempotent, and re-running it updates the binary and agent configurations. The release history shows a steady cadence, with v0.2.1 released on 2026-05-05. The repository is not archived, and the default branch is main. The documentation is sparse beyond the README, with an ARCHITECTURE.md and examples directory mentioned. Before adopting, you should verify that the installer works with your specific agent version, as the auto-configuration targets specific files like `~/.claude/rules/plandb.md`. The upgrade path is simple: re-run the install command. There is no migration process documented for the SQLite database across versions, so you should back up the database file before upgrading.

Editorial conclusion

Adopt PlanDB if your AI agents frequently decompose tasks, parallelize across branches, and need a persistent plan across sessions. Skip it if you need a human-facing tracker with rich UI, or if your agents already have a reliable planning mechanism. Before adopting, verify that the installer's auto-configuration matches your agent framework version, and test the atomic claiming behavior with a small pilot. The project is Apache-2.0, single-binary, and SQLite-backed, so the maintenance cost is low, but you must confirm the graph operations and search meet your scale.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes