{"id":46371485,"url":"https://github.com/agent-field/plandb","last_synced_at":"2026-04-01T20:53:34.671Z","repository":{"id":342042019,"uuid":"1172590199","full_name":"Agent-Field/plandb","owner":"Agent-Field","description":"The task graph primitive for AI agents","archived":false,"fork":false,"pushed_at":"2026-03-07T17:12:19.000Z","size":284,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-09T10:44:20.603Z","etag":null,"topics":["ai-agents","ai-native","cli","jit-planning","llm","mcp","orchestration","rust","sqlite","task-graph","task-management"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Agent-Field.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-04T13:36:26.000Z","updated_at":"2026-03-09T06:51:07.000Z","dependencies_parsed_at":"2026-03-08T07:00:50.569Z","dependency_job_id":null,"html_url":"https://github.com/Agent-Field/plandb","commit_stats":null,"previous_names":["agent-field/planq"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/Agent-Field/plandb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agent-Field%2Fplandb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agent-Field%2Fplandb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agent-Field%2Fplandb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agent-Field%2Fplandb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Agent-Field","download_url":"https://codeload.github.com/Agent-Field/plandb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agent-Field%2Fplandb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30328261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T05:25:20.737Z","status":"ssl_error","status_checked_at":"2026-03-10T05:25:17.430Z","response_time":106,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-native","cli","jit-planning","llm","mcp","orchestration","rust","sqlite","task-graph","task-management"],"created_at":"2026-03-05T04:05:05.005Z","updated_at":"2026-04-01T20:53:34.641Z","avatar_url":"https://github.com/Agent-Field.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/hero.png\" alt=\"PlanDB — The issue tracker for AI agents\" width=\"100%\" /\u003e\n\n# PlanDB\n\n### **The issue tracker your AI agents are missing.**\n\nLinear and Jira were built for humans planning at human speed. Your agents decompose tasks mid-flight, parallelize across branches, and pivot entire subtrees when an approach fails — they need infrastructure that keeps up.\n\nPlanDB is that infrastructure. Local-first, single binary, SQLite-backed. No cloud, no accounts, no setup.\n\n[![Stars](https://img.shields.io/github/stars/Agent-Field/plandb?style=flat\u0026logo=github\u0026logoColor=white\u0026color=7c3aed\u0026labelColor=1e1e2e)](https://github.com/Agent-Field/plandb/stargazers)\n[![License](https://img.shields.io/badge/license-Apache%202.0-7c3aed.svg?style=flat\u0026labelColor=1e1e2e)](LICENSE)\n[![Last Commit](https://img.shields.io/github/last-commit/Agent-Field/plandb?style=flat\u0026logo=git\u0026logoColor=white\u0026color=7c3aed\u0026labelColor=1e1e2e)](https://github.com/Agent-Field/plandb/commits/main)\n\n**[Install](#install)** · **[Demo](#see-it-work)** · **[Architecture](docs/ARCHITECTURE.md)** · **[Examples](examples/)**\n\n\u003c/div\u003e\n\n---\n\nYour agents have no issue tracker. No dependencies. No sprints. No idea what to work on next. They start coding before the schema exists, duplicate each other's work, and forget everything between sessions.\n\nPlanDB gives them one — like giving every agent their own Linear workspace, except it's a single binary that runs anywhere.\n\n## Install\n\nOne command. Your agents start using it immediately — no config, no copy-paste, no prompt engineering.\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Agent-Field/plandb/main/install.sh | bash\n```\n\nThe installer downloads the binary **and** auto-configures your agents with full planning instructions. Supports Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Windsurf, and Aider. Re-run anytime to update — it's idempotent.\n\n\u003cdetails\u003e\u003csummary\u003eMore install options\u003c/summary\u003e\n\n```bash\ncurl -fsSL .../install.sh | bash -s -- --all           # Silent: configure all detected frameworks\ncurl -fsSL .../install.sh | bash -s -- --binary-only   # Just the binary, no framework config\n\n# From source\ncargo install --path .\n\n# Custom prompts for other frameworks\nplandb prompt --for cli    # Shell agents (Codex, Aider)\nplandb prompt --for mcp    # MCP agents (Claude Code, Cursor, Windsurf)\nplandb prompt --for http   # HTTP agents (custom, webhooks)\n```\n\n\u003c/details\u003e\n\n### What Gets Installed\n\n| Framework | What's configured | How it works |\n|---|---|---|\n| **Claude Code** | Rules file (`~/.claude/rules/plandb.md`) + Skill (`~/.claude/skills/plandb/`) | Always-on rules make agents plan automatically. The `/plandb` skill adds a structured 6-phase workflow with command gotchas and anti-patterns. |\n| **Cursor** | Manual (instructions printed) | Paste into Cursor Settings → General → Rules for AI |\n| **Codex** | `~/.codex/AGENTS.override.md` | Appended to agent instructions |\n| **Gemini CLI** | `~/.gemini/GEMINI.md` | Appended to agent instructions |\n| **Others** | Framework-specific config files | Aider, OpenCode, Windsurf — appended to their instruction files |\n\n## Try It Now\n\nAfter installing, open your AI agent and paste one of these prompts:\n\n**Claude Code** (uses the `/plandb` skill for structured planning):\n```\n/plandb Build a CLI todo app in Python with add, list, complete, and delete commands.\nStore todos in a local JSON file. Include tests.\n```\n\n**Any agent** (Codex, Gemini CLI, Cursor, etc.):\n```\nUse plandb to plan and build a CLI todo app in Python with add, list, complete,\nand delete commands. Store todos in a local JSON file. Include tests.\n```\n\nWatch the terminal — the agent will decompose the task into a dependency graph, parallelize independent work, and track progress with `plandb go` / `plandb done --next` automatically.\n\n## Why PlanDB\n\n- **Compound graph, not a flat task list.** Most tools give you a list or a tree. PlanDB is a compound graph — tasks contain subtasks to any depth (like folders), and dependencies connect tasks *across* those boundaries (like symlinks). Your \"Build API\" subtask inside Backend can directly depend on \"Define Schema\" inside Database. One `split` turns a stuck task into three parallel subtasks. One `--dep` wires them into the right execution order. That's why agents using PlanDB naturally parallelize — the graph tells them exactly what's independent.\n\n- **Plans that adapt mid-flight.** Agents don't know the full plan upfront. PlanDB expects that. `split` a task when it turns out harder than expected. `insert` a step you missed between two existing tasks — dependencies rewire automatically. `pivot` an entire subtree when an approach fails. The plan is a living hypothesis, not a static spec.\n\n- **Knowledge that finds you.** Record discoveries, blockers, and decisions with `plandb context` as you work. When an agent claims a related task days later, that context surfaces automatically via BM25 — no one searched for it, no one remembered to pass it along. Knowledge compounds across agents and sessions.\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003eEverything else\u003c/strong\u003e\u003c/summary\u003e\n\n- **Atomic multi-agent claiming.** `plandb go` uses atomic operations — two agents cannot claim the same task. No locks, no races, no duplicate work.\n- **Critical path analysis.** `plandb critical-path` shows the longest dependency chain. `plandb bottlenecks` shows what blocks the most downstream work. Focus where it matters.\n- **Pre/post conditions.** `--pre \"schema must exist\"` and `--post \"all tests pass\"` attach conditions agents see when claiming and completing tasks.\n- **BM25 search across everything.** Tasks, descriptions, context entries, notes — all searchable with `plandb search`.\n- **Zero infrastructure.** Single binary. SQLite. No Docker, no cloud, no config files. Works offline.\n- **Three interfaces.** CLI for shell agents. MCP server for Claude Code / Cursor / Windsurf. HTTP API for custom agents and dashboards.\n- **Export/import patterns.** Save a decomposition as YAML, reuse it across projects. `plandb export` / `plandb import`.\n- **Live terminal dashboard.** `plandb watch` for a real-time view that refreshes as tasks complete.\n\n\u003c/details\u003e\n\n## See It Work\n\n```bash\nplandb init \"auth-system\"\nplandb add \"Design schema\" --as schema --kind research \\\n  --description \"Define user/session tables, auth flows, token format\"\nplandb add \"Build API\" --as api --kind code --dep t-schema \\\n  --description \"Implement endpoints: register, login, refresh, logout\"\nplandb add \"Write tests\" --as tests --kind test --dep t-schema \\\n  --description \"Integration tests for all auth endpoints\"\nplandb add \"Deploy\" --as deploy --kind shell --dep t-api --dep t-tests \\\n  --description \"Docker build, push, deploy to staging\"\n\nplandb go            # claims \"Design schema\" (only task with no blockers)\nplandb done --next   # completes it → \"Build API\" and \"Write tests\" both become ready\n```\n\nTwo tasks ready = two agents work in parallel. Atomic claiming prevents conflicts.\n\n## In the Wild: 6 Tasks Became 20\n\nWe gave one Claude Code instance one sentence: *\"Build a GPT from scratch in Rust, then train it to do tool calling.\"*\n\nNo human intervention. PlanDB planned the entire thing. The agent built a **3,769-line transformer** in pure Rust (zero ML frameworks), then ran **7 RL experiments**. The plan evolved from 6 to 20 tasks — splitting when work proved complex, parallelizing independent experiments, pivoting when REINFORCE collapsed:\n\n```mermaid\ngraph LR\n  design --\u003e sft\n  sft --\u003e reinforce \u0026 dpo \u0026 custom \u0026 sft-v2 \u0026 sft-v3 \u0026 reject\n  reinforce \u0026 dpo \u0026 custom \u0026 sft-v2 \u0026 sft-v3 \u0026 reject --\u003e compare\n  compare --\u003e final\n```\n\n| Method | Format Acc | Tool Acc | Composite |\n|--------|-----------|----------|-----------|\n| **Rejection Sampling** | **71.3%** | **70.0%** | **0.601** |\n| SFT Baseline | 66.3% | 63.8% | 0.577 |\n| DPO | 65.0% | 62.5% | 0.570 |\n| REINFORCE | 0.0% | 0.0% | 0.090 |\n\nPre-trained weights included: `cd experiments/mini-gpt-rust \u0026\u0026 cargo run --release -- --demo`\n\n\u003e More in [`experiments/`](experiments/) — docs sites built autonomously by Codex, Claude Code, and Gemini CLI.\n\n## Under the Hood\n\nPlanDB uses a **compound graph** — two orthogonal structures composed:\n\n- **Containment** (hierarchy): tasks contain subtasks, recursively, to any depth\n- **Dependencies** (flow): edges between tasks at ANY level, crossing containment boundaries\n\n```mermaid\ngraph LR\n  subgraph Backend\n    DB --\u003e API\n  end\n  subgraph Frontend\n    UI\n  end\n  API --\u003e UI\n  DB -.-\u003e UI\n```\n\nA backend subtask can depend on a frontend task directly. Composites auto-complete when children finish. `plandb use t-backend` zooms into a subtree for scoped work.\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003eWhat your agents get vs what you use\u003c/strong\u003e\u003c/summary\u003e\n\n| You use | Your agents get | Why it matters |\n|---|---|---|\n| **Issues** | `plandb add --description \"...\"` | Work items with full specs, not just prompts |\n| **Dependencies** | `--dep t-schema` | Right execution order, automatically |\n| **Sprint board** | `plandb status --detail` | See what's blocked, ready, running, done |\n| **Assignment** | `plandb go` | Atomic claiming — no two agents grab the same work |\n| **Sub-issues** | `plandb split --into \"A, B, C\"` | Recursive decomposition to any depth |\n| **Comments** | `plandb context --kind discovery` | Knowledge persists across sessions and agents |\n| **Triage** | `plandb critical-path` | Prioritize the bottleneck, not just the next task |\n| **Search** | `plandb search \"query\"` | BM25 across everything the project has learned |\n| **Pre/post conditions** | `--pre \"...\" --post \"...\"` | Conditions agents see on claim and completion |\n| **Retrospective** | Context auto-surfaces via `plandb go` | Agent B gets what Agent A discovered — automatically |\n\n\u003c/details\u003e\n\n## Interfaces\n\n| | Command | For |\n|---|---|---|\n| **CLI** | `plandb \u003ccommand\u003e` | Claude Code, Codex, Gemini, any shell agent |\n| **MCP** | `plandb mcp` | Claude Code, Cursor, Windsurf |\n| **HTTP** | `plandb serve --port 8484` | Custom agents, webhooks, dashboards |\n\n## Part of AgentField\n\nPlanDB is the task planning layer for [**AgentField**](https://github.com/Agent-Field/agentfield) — the open-source AI backend for building and running AI agents. [**SWE-AF**](https://github.com/Agent-Field/SWE-AF) uses PlanDB internally to coordinate parallel agent workstreams.\n\n**[Architecture Docs](docs/ARCHITECTURE.md)** · **[Examples](examples/)** · **[CLI Reference: `plandb --help`](#)**\n\n## License\n\nApache License 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagent-field%2Fplandb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagent-field%2Fplandb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagent-field%2Fplandb/lists"}