Skip to content
Back to search

markplane

AI-native, markdown-first project management. Your repo is the project manager.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/zerowand01/markplane with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/zerowand01/markplane'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zerowand01--markplane/badge.svg)](/listings/zerowand01--markplane)

HTML

<a href="/listings/zerowand01--markplane"><img src="/api/listings/zerowand01--markplane/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install `markplane` ([see below](#installation)) 2. Initialize in your project: `markplane init --name "My Project"` ([details](#initialization)) 3. Open the web UI: `markplane serve --open` 4. Connect your AI via MCP ([setup guide](docs/mcp-setup.md)) 5. 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."*

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 269 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.png">
  4. <source media="(prefers-color-scheme: light)" srcset="assets/logo-light.png">
  5. <img src="assets/logo-light.png" width="280" alt="Markplane">
  6. </picture>
  7. </p>
  8. <p align="center">
  9. Project management in your repo, built for AI collaboration.
  10. </p>
  11. ---
  12. <a href="https://github.com/user-attachments/assets/9d303e13-d14a-458f-bb58-20cd069082bc">
  13. <video src="https://github.com/user-attachments/assets/9d303e13-d14a-458f-bb58-20cd069082bc" autoplay loop muted playsinline></video>
  14. </a>
  15. Every 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.
  16. Markplane 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.
  17. ## Quickstart
  18. 1. Install `markplane` ([see below](#installation))
  19. 2. Initialize in your project: `markplane init --name "My Project"` ([details](#initialization))
  20. 3. Open the web UI: `markplane serve --open`
  21. 4. Connect your AI via MCP ([setup guide](docs/mcp-setup.md))
  22. 5. 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."*
  23. ## A day with Markplane
  24. **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.
  25. **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.
  26. **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.
  27. **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.
  28. ## Why Markplane
  29. - **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.
  30. - **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.
  31. - **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.
  32. - **Zero infrastructure** — `markplane init` and you're done. No signup, no server, no Docker container. It's a single binary.
  33. ## Agent Memory
  34. Markplane 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.
  35. For OpenClaw, see [`@zerowand/markplane-memory`](https://github.com/zerowand01/markplane-memory).
  36. ## The Context Layer
  37. Markplane 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.
  38. | File | What it contains | Size |
  39. |------|-----------------|------|
  40. | `summary.md` | Active epics, in-progress work, blocked items, priority queue, key metrics | ~1000 tokens |
  41. | `active-work.md` | Detailed view of current work with dependencies and assignees | ~500 tokens |
  42. | `blocked-items.md` | Items waiting on unresolved dependencies | ~200-500 tokens |
  43. | `metrics.md` | Status distribution, priority breakdown, epic progress | ~500 tokens |
  44. Each 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.
  45. A 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.
  46. See the [AI Integration Guide](docs/ai-integration.md) for the full context layer design, token budgets, and recommended AI reading patterns.
  47. ## Installation
  48. ### Homebrew (macOS and Linux)
  49. ```bash
  50. brew trust zerowand01/markplane
  51. brew install zerowand01/markplane/markplane
  52. ```
  53. Homebrew 6.0+ requires third-party taps to be trusted before their formulae
  54. will load. Formulae are executable Ruby, and only official taps are
  55. pre-reviewed, so Homebrew asks you to opt in explicitly. Without the first
  56. command you'll see `Error: Refusing to load formula ... from untrusted tap`.
  57. Trust is recorded in `~/.homebrew/trust.json` and is set once per machine.
  58. To upgrade later:
  59. ```bash
  60. brew update && brew upgrade markplane
  61. ```
  62. `brew update` refreshes the tap's metadata — without it Homebrew still
  63. believes your installed version is current and reports nothing to upgrade.
  64. ### Shell script (macOS and Linux)
  65. ```bash
  66. curl -fsSL https://raw.githubusercontent.com/zerowand01/markplane/master/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 98 on GitHub
  67. ```
  68. Downloads the latest release, verifies the SHA256 checksum, and installs to `~/.local/bin/`. Customize with environment variables:
  69. ```bash
  70. curl -fsSL https://raw.githubusercontent.com/zerowand01/markplane/master/install.sh | INSTALL_DIR=/usr/local/bin sh
  71. ```
  72. ### Pre-built binary
  73. Download 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.
  74. | Platform | Archive |
  75. |----------|---------|
  76. | macOS (Apple Silicon) | `markplane-v*-aarch64-apple-darwin.tar.gz` |
  77. | macOS (Intel) | `markplane-v*-x86_64-apple-darwin.tar.gz` |
  78. | Linux (x86_64) | `markplane-v*-x86_64-unknown-linux-musl.tar.gz` |
  79. | Windows (x86_64) | `markplane-v*-x86_64-pc-windows-msvc.zip` |
  80. **macOS / Linux:**
  81. ```bash
  82. tar xzf markplane-v*.tar.gz # extract the binary from the archive
  83. mv markplane ~/.local/bin/ # or /usr/local/bin/ with sudo
  84. ```
  85. > **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.
  86. **Windows:** Extract `markplane.exe` from the `.zip` to a location on your `PATH` (e.g., `%LOCALAPPDATA%\markplane\`).
  87. ### Build from source
  88. Requires Rust 1.93.0+. To include the web UI, also requires Node.js 18+.
  89. ```bash
  90. git clone https://github.com/zerowand01/markplane.git
  91. cd markplane
  92. # CLI only
  93. cargo install --path crates/markplane-cli
  94. # CLI + Web UI (single binary)
  95. cd crates/markplane-web/ui && npm install && npm run build && cd ../../..
  96. cargo install --path crates/markplane-cli --features embed-ui
  97. ```
  98. ## Initialization
  99. Initialize Markplane in your project:
  100. ```bash
  101. markplane init --name "My Project"
  102. ```
  103. This creates the `.markplane/` directory with config, templates, and starter content to explore. Use `markplane init --empty` to skip starter content.
  104. ```
  105. .markplane/
  106. ├── config.yaml # Project settings
  107. ├── INDEX.md # Root navigation
  108. ├── roadmap/ # Epics — strategic goals and phases (EPIC-xxxxx)
  109. ├── backlog/ # Tasks — the "what" to do (TASK-xxxxx)
  110. ├── plans/ # Plans — the "how" to do it (PLAN-xxxxx)
  111. ├── notes/ # Notes — research, ideas, decisions (NOTE-xxxxx)
  112. ├── templates/ # Document templates
  113. └── .context/ # Token-optimized summaries for AI
  114. ```
  115. ## Web UI
  116. Launch the local web dashboard to see your project:
  117. ```bash
  118. markplane serve --open
  119. ```
  120. This opens `http://localhost:4200` in your browser with a dashboard, kanban board, dependency graph, and more.
  121. See the [Web UI Guide](docs/web-ui-guide.md) for keyboard shortcuts, views, and details.
  122. ## AI Integration
  123. Markplane 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".
  124. Example with Claude Code:
  125. **Per-user** — adds Markplane to your local editor configuration:
  126. ```bash
  127. claude mcp add --transport stdio markplane -- markplane mcp
  128. ```
  129. **Project-wide** — add a `.mcp.json` file at the repo root so every team member gets the integration automatically:
  130. ```json
  131. {
  132. "mcpServers": {
  133. "markplane": {
  134. "command": "markplane",
  135. "args": ["mcp"]
  136. }
  137. }
  138. }
  139. ```
  140. See the [MCP Setup Guide](docs/mcp-setup.md) for other editors, configuration options, and the full tool and resource catalog.
  141. ## CLI
  142. The CLI is a power-user interface for everything Markplane can do:
  143. ```bash
  144. markplane add "Fix login redirect" --type bug --priority critical --tags auth
  145. markplane ls # List tasks
  146. markplane ls --priority high,critical # Filter by priority
  147. markplane show TASK-fq2x8 # View item details
  148. markplane start TASK-fq2x8 # Set to in-progress
  149. markplane done TASK-fq2x8 # Mark as done
  150. markplane dashboard # Project overview
  151. markplane sync # Regenerate INDEX.md + .context/
  152. markplane check # Validate cross-references
  153. ```
  154. See the [CLI Reference](docs/cli-reference.md) for complete command documentation.
  155. ## Status Workflows
  156. | Type | Statuses | Configurable? |
  157. |------|----------|---------------|
  158. | Task | `draft` → `backlog` → `planned` → `in-progress` → `done` (also `cancelled`) | Yes — via `config.yaml` `workflows.task` |
  159. | Epic | `later` → `next` → `now` → `done` | No |
  160. | Plan | `draft` → `approved` → `in-progress` → `done` | No |
  161. | Note | `draft` → `active` → `archived` | No |
  162. Task 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`.
  163. ## Features
  164. - **Markdown + YAML frontmatter** — Structured metadata (status, priority, effort, tags) in YAML; free-form details in markdown.
  165. - **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.
  166. - **Web UI** — Local dashboard with kanban board, dependency graph, markdown rendering, search, and dark/light themes.
  167. - **MCP server** — Structured tool access for AI coding assistants (Claude, Cursor, etc.) via JSON-RPC over stdio.
  168. - **Cross-references** — `[[TASK-rm6d3]]` wiki-style links between items, with validation via `markplane check`.
  169. - **Dependency tracking** — `blocks` / `depends_on` relationships and bidirectional `related` links with visual dependency graphs.
  170. - **Real-time sync** — Changes from CLI, MCP, or file edits appear instantly in the web UI via WebSocket.
  171. - **Archive management** — Archive completed items across all entity types with easy restore.
  172. - **Built-in workflows** — Configurable status progressions for tasks, epics, plans, and notes.
  173. ## Documentation
  174. - [Getting Started Guide](docs/getting-started.md) — Step-by-step tutorial
  175. - [CLI Reference](docs/cli-reference.md) — Complete command documentation
  176. - [Web UI Guide](docs/web-ui-guide.md) — Web dashboard usage and development
  177. - [AI Integration Guide](docs/ai-integration.md) — Context layer, INDEX.md pattern, AI workflows
  178. - [MCP Setup Guide](docs/mcp-setup.md) — AI tool integration
  179. - [Item Reference](docs/file-format.md) — Directory structure, YAML schema, ID system, cross-references
  180. ## Development
  181. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution guidelines.
  182. - [Architecture](docs/architecture.md) — System design, data model, crate responsibilities
  183. - [Releasing](docs/releasing.md) — Release process and versioning
  184. ## License
  185. Apache-2.0. See [LICENSE](LICENSE) for details.
  186. ---
  187. <sub>© 2026 zeroWand LLC</sub>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.