{"id":47588429,"url":"https://github.com/zerowand01/markplane","last_synced_at":"2026-04-01T16:56:01.046Z","repository":{"id":344678669,"uuid":"1172010174","full_name":"zerowand01/markplane","owner":"zerowand01","description":"AI-native, markdown-first project management. Your repo is the project manager.","archived":false,"fork":false,"pushed_at":"2026-03-30T00:10:31.000Z","size":1476,"stargazers_count":61,"open_issues_count":5,"forks_count":9,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-03-30T03:50:18.984Z","etag":null,"topics":["ai","ai-native","claude-code","cli","cursor","developer-tools","git","markdown","mcp","mcp-server","open-source","project-management","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/zerowand01.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-03T21:13:47.000Z","updated_at":"2026-03-30T03:31:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zerowand01/markplane","commit_stats":null,"previous_names":["zerowand01/markplane"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/zerowand01/markplane","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerowand01%2Fmarkplane","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerowand01%2Fmarkplane/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerowand01%2Fmarkplane/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerowand01%2Fmarkplane/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zerowand01","download_url":"https://codeload.github.com/zerowand01/markplane/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerowand01%2Fmarkplane/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"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","ai-native","claude-code","cli","cursor","developer-tools","git","markdown","mcp","mcp-server","open-source","project-management","task-management"],"created_at":"2026-04-01T16:56:00.107Z","updated_at":"2026-04-01T16:56:01.039Z","avatar_url":"https://github.com/zerowand01.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logo-dark.png\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"assets/logo-light.png\"\u003e\n    \u003cimg src=\"assets/logo-light.png\" width=\"280\" alt=\"Markplane\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Project management in your repo, built for AI collaboration.\n\u003c/p\u003e\n\n---\n\n\u003ca href=\"https://github.com/user-attachments/assets/9d303e13-d14a-458f-bb58-20cd069082bc\"\u003e\n  \u003cvideo src=\"https://github.com/user-attachments/assets/9d303e13-d14a-458f-bb58-20cd069082bc\" autoplay loop muted playsinline\u003e\u003c/video\u003e\n\u003c/a\u003e\n\nEvery developer using AI coding assistants hits the same wall: the AI is great at code, but clueless about the project. It doesn't know what you're building, what's blocked, or what's next. Meanwhile, your project data is locked in a SaaS tool that lives outside your codebase, outside your editor, outside your flow.\n\nMarkplane stores every task, epic, and plan as a markdown file inside your repo — version-controlled with git, browsable with any editor, and automatically compressed into token-efficient summaries your AI assistant can read and act on. No database, no SaaS, no context-switching.\n\n## Quickstart\n\n1. Install `markplane` ([see below](#installation))\n2. Initialize in your project: `markplane init --name \"My Project\"` ([details](#initialization))\n3. Open the web UI: `markplane serve --open`\n4. Connect your AI via MCP ([setup guide](docs/mcp-setup.md))\n5. Just tell your AI what to do in plain English: *\"Create a task for the login bug, mark it critical, and link it to the auth epic.\"*\n\n## A day with Markplane\n\n**Morning** — You open your AI assistant and ask \"what should we work on?\" It pulls the project summary via MCP — 2 tasks in progress, 1 blocked on the auth migration, the payments epic is 60% done — and suggests the highest-priority planned task.\n\n**Mid-day** — You hit a design question. You talk it through with your AI, arrive at an approach, and say \"create a task for this, and then let's work on an implementation plan.\" Markdown files appear in your repo, linked and ready.\n\n**Afternoon** — \"Let's implement TASK-xyz.\" Your AI reads the plan, understands the dependencies and project context, and builds it. When you're happy with the result: \"mark it done.\" The context layer updates.\n\n**End of day** — You commit. Your project state is versioned alongside your code. Tomorrow's session picks up where today left off — no re-explaining.\n\n## Why Markplane\n\n- **AI-native, not AI-retrofitted** — `.context/` summaries compress full project state into ~1000 tokens. Your AI loads only what it needs. Every design decision optimizes for LLM context windows.\n- **Files are the database** — No vendor, no subscription, no migration. `grep` your tasks. `git blame` your status changes. Branch your backlog like you branch your code.\n- **MCP server built in** — AI assistants don't just read your project — they manage it. Query tasks, update status, create plans, and track dependencies without leaving your conversation.\n- **Zero infrastructure** — `markplane init` and you're done. No signup, no server, no Docker container. It's a single binary.\n\n## Agent Memory\n\nMarkplane also works as structured memory for autonomous AI agents. Instead of unstructured daily logs that degrade over time, your agent gets typed tasks, decisions, and project state — compressed into a token-efficient summary that persists across sessions.\n\nFor OpenClaw, see [`@zerowand/markplane-memory`](https://github.com/zerowand01/markplane-memory).\n\n## The Context Layer\n\nMarkplane automatically generates a `.context/` directory with compressed, token-efficient summaries of your entire project state. This is what makes AI collaboration work — your assistant doesn't need to read every file to understand the project.\n\n| File | What it contains | Size |\n|------|-----------------|------|\n| `summary.md` | Active epics, in-progress work, blocked items, priority queue, key metrics | ~1000 tokens |\n| `active-work.md` | Detailed view of current work with dependencies and assignees | ~500 tokens |\n| `blocked-items.md` | Items waiting on unresolved dependencies | ~200-500 tokens |\n| `metrics.md` | Status distribution, priority breakdown, epic progress | ~500 tokens |\n\nEach directory also has an `INDEX.md` that lists all items with IDs and status — so an AI agent can scan the index (~200 tokens) and load only the specific items it needs, instead of reading everything.\n\nA typical monolithic `ROADMAP.md` + `BACKLOG.md` consumes 10,000-30,000 tokens with low signal-to-noise. Markplane's equivalent project state fits in ~1000 tokens.\n\nSee the [AI Integration Guide](docs/ai-integration.md) for the full context layer design, token budgets, and recommended AI reading patterns.\n\n## Installation\n\n### Homebrew (macOS and Linux)\n\n```bash\nbrew install zerowand01/markplane/markplane\n```\n\n### Shell script (macOS and Linux)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/zerowand01/markplane/master/install.sh | sh\n```\n\nDownloads the latest release, verifies the SHA256 checksum, and installs to `~/.local/bin/`. Customize with environment variables:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/zerowand01/markplane/master/install.sh | INSTALL_DIR=/usr/local/bin sh\n```\n\n### Pre-built binary\n\nDownload the latest release for your platform from [GitHub Releases](https://github.com/zerowand01/markplane/releases). Pre-built binaries include the web UI and require no additional dependencies.\n\n| Platform | Archive |\n|----------|---------|\n| macOS (Apple Silicon) | `markplane-v*-aarch64-apple-darwin.tar.gz` |\n| macOS (Intel) | `markplane-v*-x86_64-apple-darwin.tar.gz` |\n| Linux (x86_64) | `markplane-v*-x86_64-unknown-linux-musl.tar.gz` |\n| Windows (x86_64) | `markplane-v*-x86_64-pc-windows-msvc.zip` |\n\n**macOS / Linux:**\n\n```bash\ntar xzf markplane-v*.tar.gz       # extract the binary from the archive\nmv markplane ~/.local/bin/        # or /usr/local/bin/ with sudo\n```\n\n\u003e **Note:** On macOS, binaries downloaded via a browser may be blocked by Gatekeeper. Remove the quarantine attribute with `xattr -d com.apple.quarantine ~/.local/bin/markplane`, or use the shell script install which avoids this entirely.\n\n**Windows:** Extract `markplane.exe` from the `.zip` to a location on your `PATH` (e.g., `%LOCALAPPDATA%\\markplane\\`).\n\n### Build from source\n\nRequires Rust 1.93.0+. To include the web UI, also requires Node.js 18+.\n\n```bash\ngit clone https://github.com/zerowand01/markplane.git\ncd markplane\n\n# CLI only\ncargo install --path crates/markplane-cli\n\n# CLI + Web UI (single binary)\ncd crates/markplane-web/ui \u0026\u0026 npm install \u0026\u0026 npm run build \u0026\u0026 cd ../../..\ncargo install --path crates/markplane-cli --features embed-ui\n```\n\n## Initialization\n\nInitialize Markplane in your project:\n\n```bash\nmarkplane init --name \"My Project\"\n```\n\nThis creates the `.markplane/` directory with config, templates, and starter content to explore. Use `markplane init --empty` to skip starter content.\n\n```\n.markplane/\n├── config.yaml           # Project settings\n├── INDEX.md              # Root navigation\n├── roadmap/              # Epics — strategic goals and phases (EPIC-xxxxx)\n├── backlog/              # Tasks — the \"what\" to do (TASK-xxxxx)\n├── plans/                # Plans — the \"how\" to do it (PLAN-xxxxx)\n├── notes/                # Notes — research, ideas, decisions (NOTE-xxxxx)\n├── templates/            # Document templates\n└── .context/             # Token-optimized summaries for AI\n```\n\n## Web UI\n\nLaunch the local web dashboard to see your project:\n\n```bash\nmarkplane serve --open\n```\n\nThis opens `http://localhost:4200` in your browser with a dashboard, kanban board, dependency graph, and more.\n\nSee the [Web UI Guide](docs/web-ui-guide.md) for keyboard shortcuts, views, and details.\n\n## AI Integration\n\nMarkplane includes a built-in [MCP](https://modelcontextprotocol.io) server that lets AI coding assistants manage your project directly. Connect your assistant, then just tell it what to do in natural language — \"create a task for the login bug\", \"show me what's blocked\", \"mark TASK-fq2x8 as done\".\n\nExample with Claude Code:\n\n**Per-user** — adds Markplane to your local editor configuration:\n\n```bash\nclaude mcp add --transport stdio markplane -- markplane mcp\n```\n\n**Project-wide** — add a `.mcp.json` file at the repo root so every team member gets the integration automatically:\n\n```json\n{\n  \"mcpServers\": {\n    \"markplane\": {\n      \"command\": \"markplane\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nSee the [MCP Setup Guide](docs/mcp-setup.md) for other editors, configuration options, and the full tool and resource catalog.\n\n## CLI\n\nThe CLI is a power-user interface for everything Markplane can do:\n\n```bash\nmarkplane add \"Fix login redirect\" --type bug --priority critical --tags auth\nmarkplane ls                          # List tasks\nmarkplane ls --priority high,critical # Filter by priority\nmarkplane show TASK-fq2x8            # View item details\nmarkplane start TASK-fq2x8           # Set to in-progress\nmarkplane done TASK-fq2x8            # Mark as done\nmarkplane dashboard                   # Project overview\nmarkplane sync                        # Regenerate INDEX.md + .context/\nmarkplane check                       # Validate cross-references\n```\n\nSee the [CLI Reference](docs/cli-reference.md) for complete command documentation.\n\n## Status Workflows\n\n| Type | Statuses | Configurable? |\n|------|----------|---------------|\n| Task | `draft` → `backlog` → `planned` → `in-progress` → `done` (also `cancelled`) | Yes — via `config.yaml` `workflows.task` |\n| Epic | `later` → `next` → `now` → `done` | No |\n| Plan | `draft` → `approved` → `in-progress` → `done` | No |\n| Note | `draft` → `active` → `archived` | No |\n\nTask statuses are fully configurable. Each status maps to one of six **status categories** (`draft`, `backlog`, `planned`, `active`, `completed`, `cancelled`) that control system behavior (kanban columns, progress tracking, archive eligibility). Add custom statuses like `in-review`, `in-qa`, or `deployed` by placing them under the appropriate category in `config.yaml`.\n\n## Features\n\n- **Markdown + YAML frontmatter** — Structured metadata (status, priority, effort, tags) in YAML; free-form details in markdown.\n- **AI-optimized context layer** — Generated `.context/` summaries compress full project state into ~1000 tokens for AI consumption. INDEX.md routing lets AI agents load only what they need.\n- **Web UI** — Local dashboard with kanban board, dependency graph, markdown rendering, search, and dark/light themes.\n- **MCP server** — Structured tool access for AI coding assistants (Claude, Cursor, etc.) via JSON-RPC over stdio.\n- **Cross-references** — `[[TASK-rm6d3]]` wiki-style links between items, with validation via `markplane check`.\n- **Dependency tracking** — `blocks` / `depends_on` relationships and bidirectional `related` links with visual dependency graphs.\n- **Real-time sync** — Changes from CLI, MCP, or file edits appear instantly in the web UI via WebSocket.\n- **Archive management** — Archive completed items across all entity types with easy restore.\n- **Built-in workflows** — Configurable status progressions for tasks, epics, plans, and notes.\n\n## Documentation\n\n- [Getting Started Guide](docs/getting-started.md) — Step-by-step tutorial\n- [CLI Reference](docs/cli-reference.md) — Complete command documentation\n- [Web UI Guide](docs/web-ui-guide.md) — Web dashboard usage and development\n- [AI Integration Guide](docs/ai-integration.md) — Context layer, INDEX.md pattern, AI workflows\n- [MCP Setup Guide](docs/mcp-setup.md) — AI tool integration\n- [Item Reference](docs/file-format.md) — Directory structure, YAML schema, ID system, cross-references\n\n## Development\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution guidelines.\n\n- [Architecture](docs/architecture.md) — System design, data model, crate responsibilities\n- [Releasing](docs/releasing.md) — Release process and versioning\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE) for details.\n\n---\n\n\u003csub\u003e© 2026 zeroWand LLC\u003c/sub\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerowand01%2Fmarkplane","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzerowand01%2Fmarkplane","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerowand01%2Fmarkplane/lists"}