Stop Juggling SaaS Tools! Markplane Puts Your AI Project Manager Inside Git

Stop Juggling SaaS Tools! Markplane Puts Your AI Project Manager Inside Git

Every developer using AI coding assistants hits the same brutal wall: the AI writes brilliant code, but it's clueless about your project. It doesn't know what you're building. It can't see what's blocked. It has zero memory of yesterday's decisions. Meanwhile, you're copy-pasting context between Jira, Notion, Linear, and your editor like some digital circus performer.

What if your project manager lived inside your repository? What if every task, epic, and plan was a markdown^{↗ Smart Converter} file—version-controlled, grep-able, and automatically compressed into token-efficient summaries your AI could actually read and act on?

Enter Markplane, the open-source project management tool that's making SaaS project management look like a relic from 2019. No database. No subscription. No context-switching. Just pure, git-native productivity that turns your AI assistant into a genuine project collaborator.

What Is Markplane?

Markplane is an AI-native, markdown-first project management system created by zeroWand LLC and open-sourced at github.com/zerowand01/markplane. Its tagline says it all: "Your repo is the project manager."

Unlike every other project management tool that locks your data in someone else's cloud, Markplane stores everything as plain markdown files inside your repository. Tasks, epics, plans, notes—all living alongside your code, breathing the same git history, accessible through any text editor or terminal.

But here's where it gets insane: Markplane isn't just a file-based organizer retrofitted for AI. It was built from the ground up for LLM collaboration. The .context/ directory automatically generates token-optimized summaries of your entire project state. Your AI assistant doesn't need to read 30,000 tokens of unstructured roadmap noise. It loads ~1,000 tokens of compressed, high-signal context and immediately knows what's happening.

This matters because context windows are expensive and finite. Every token your AI wastes parsing bloated project docs is a token not spent writing code. Markplane's context layer is essentially lossless compression for project management—designed by people who understand that AI-native means optimizing for the actual constraints of large language models.

The project is trending hard among developers who've tasted AI-assisted coding but felt the friction of external project tools. It's written in Rust for performance, ships as a single binary, and includes both a sleek web UI and a built-in MCP server for direct AI integration.

Key Features That Change Everything

Markplane isn't a toy. It's a production-grade system with architectural decisions that reveal deep understanding of both software development and AI limitations.

Markdown + YAML Frontmatter — Every item combines structured metadata (status, priority, effort, tags, dependencies) with free-form markdown content. This dual-layer format is perfect for both human readability and machine parsing. Your AI gets typed data it can reason about; you get documents you can read without a UI.

The Context Layer — This is Markplane's secret weapon. The .context/ directory auto-generates summary.md (~1000 tokens), active-work.md (~500 tokens), blocked-items.md (~200-500 tokens), and metrics.md (~500 tokens). Each directory also has an INDEX.md for O(1) item lookup. Compare this to typical ROADMAP.md + BACKLOG.md monstrosities consuming 10,000-30,000 tokens with terrible signal-to-noise ratios.

Built-in MCP Server — The Model Context Protocol server exposes structured tools via JSON-RPC over stdio. Your AI doesn't just read your project; it manages it. Create tasks, update status, query dependencies—all through natural language conversation.

Cross-References & Dependencies — Wiki-style [[TASK-rm6d3]] links between items with markplane check validation. Track blocks / depends_on relationships with bidirectional related links and visual dependency graphs in the web UI.

Real-Time Web UI — Local dashboard at localhost:4200 with kanban board, dependency visualization, markdown rendering, full-text search, and dark/light themes. Changes from CLI, MCP, or direct file edits sync instantly via WebSocket.

Zero Infrastructure — Single binary. markplane init and you're operational. No Docker^{↗ Bright Coding Blog}, no database server, no signup flow, no credit card.

Use Cases Where Markplane Absolutely Dominates

1. AI-Assisted Solo Development

You're building a side project with Claude or Cursor. Every session starts with "what was I doing?" Markplane eliminates this entirely. Your AI reads the context layer, sees your active work, blocked items, and priority queue—then suggests the highest-value next task. The conversation flows: "Let's implement TASK-xyz." → AI reads the plan → builds it → "mark it done." → context updates automatically.

2. Team Development Without SaaS Lock-in

Your startup can't afford Linear's per-seat pricing. Or you work in air-gapped environments. Markplane lives in your repo, so onboarding is git clone. Branch your backlog like you branch your code. git blame shows who changed what status when. No vendor lock-in, no export anxiety, no "what if they change pricing again?"

3. Autonomous Agent Memory

Running autonomous coding agents like OpenClaw? Markplane serves as structured, persistent memory. Instead of degraded daily logs, your agent gets typed tasks, decisions, and project state in a token-efficient format that survives across sessions. The companion package @zerowand/markplane-memory extends this for specific agent frameworks.

4. Research & Decision Tracking

Complex projects generate endless decisions. Markplane's notes/ directory with draft → active → archived workflow captures research, RFCs, and architectural decisions as first-class items. Link them to tasks and epics. Six months later, git log --grep="NOTE-" reveals exactly why you chose that database.

Step-by-Step Installation & Setup Guide

Getting started with Markplane is deliberately minimal. Choose your installation path:

macOS / Linux via Homebrew

# The fastest path for most developers
brew install zerowand01/markplane/markplane

Universal Shell Script

# Downloads latest release, verifies SHA256, installs to ~/.local/bin/
curl -fsSL https://raw.githubusercontent.com/zerowand01/markplane/master/install.sh | sh

# Or specify a custom location
export INSTALL_DIR=/usr/local/bin
curl -fsSL https://raw.githubusercontent.com/zerowand01/markplane/master/install.sh | sh

Pre-Built Binary (All Platforms)

Download from GitHub Releases:

# macOS / Linux extraction
tar xzf markplane-v*.tar.gz
mv markplane ~/.local/bin/

# Fix macOS Gatekeeper quarantine if downloaded via browser
xattr -d com.apple.quarantine ~/.local/bin/markplane

On Windows, extract markplane.exe to %LOCALAPPDATA%\markplane\ and add to your PATH.

Build From Source (Rust 1.93.0+ required)

git clone https://github.com/zerowand01/markplane.git
cd markplane

# CLI only
cargo install --path crates/markplane-cli

# CLI + embedded Web UI (requires Node.js 18+)
cd crates/markplane-web/ui && npm install && npm run build && cd ../../..
cargo install --path crates/markplane-cli --features embed-ui

Initialize Your Project

# Create the .markplane/ directory with starter content
markplane init --name "My Project"

# Or skip examples with --empty
markplane init --name "Production API" --empty

This generates the complete structure:

.markplane/
├── config.yaml           # Project settings, custom workflows
├── INDEX.md              # Root navigation for AI agents
├── roadmap/              # Strategic goals (EPIC-xxxxx)
├── backlog/              # Tasks to execute (TASK-xxxxx)
├── plans/                # Implementation details (PLAN-xxxxx)
├── notes/                # Research, decisions (NOTE-xxxxx)
├── templates/            # Reusable document templates
└── .context/             # AI-optimized summaries

Launch the Web UI

# Opens http://localhost:4200 automatically
markplane serve --open

Connect Your AI via MCP

Per-user setup (Claude Code):

claude mcp add --transport stdio markplane -- markplane mcp

Project-wide setup (create .mcp.json at repo root):

{
  "mcpServers": {
    "markplane": {
      "command": "markplane",
      "args": ["mcp"]
    }
  }
}

REAL Code Examples from the Repository

Let's examine actual usage patterns from Markplane's documentation, with detailed explanations of what each command accomplishes.

Example 1: Creating and Managing Tasks via CLI

# Create a bug task with full metadata
markplane add "Fix login redirect" --type bug --priority critical --tags auth

# List all tasks in the project
markplane ls

# Filter to only high and critical priority items
markplane ls --priority high,critical

# View complete details of a specific task
markplane show TASK-fq2x8

# Progress the task through your workflow
markplane start TASK-fq2x8    # Sets status to in-progress
markplane done TASK-fq2x8     # Sets status to done

What's happening here? The add command creates a new markdown file in .markplane/backlog/ with auto-generated ID TASK-fq2x8, YAML frontmatter capturing type, priority, and tags, plus your description in the body. The ls commands read the INDEX.md for fast filtering without parsing every file. Status transitions validate against your configured workflow in config.yaml—you can't jump from draft to done if your workflow doesn't allow it.

Example 2: MCP Configuration for AI Integration

{
  "mcpServers": {
    "markplane": {
      "command": "markplane",
      "args": ["mcp"]
    }
  }
}

Why this matters: This .mcp.json file lives in your repository root, so every team member automatically gets AI project management. The MCP server speaks JSON-RPC over stdio, which Claude, Cursor, and compatible assistants understand natively. When you say "create a task for the login bug", your AI invokes the add_task tool with parsed parameters. When you ask "what's blocked?", it queries the context layer and summarizes. The integration is bidirectional and stateful—not just reading, but modifying project state.

Example 3: The Context Layer Files

<!-- .context/summary.md — ~1000 tokens of compressed project state -->
# Project Summary: My Project

## Active Epics
- EPIC-a1b2c: Payments integration (60% complete, 3/5 tasks done)
- EPIC-d3e4f: Auth migration (blocked, waiting on OAuth vendor)

## In Progress
- TASK-x7y8z: Implement Stripe webhooks (EPIC-a1b2c)
  - Assigned: @dev1
  - Started: 2026-01-15
  - Blocked: false

## Blocked Items
- TASK-p9q0r: OAuth2 PKCE flow (EPIC-d3e4f)
  - Blocked by: vendor response on scope requirements

## Priority Queue (Next 3)
1. TASK-m1n2o: Payment failure retry logic
2. TASK-s3t4u: Webhook signature verification
3. TASK-v5w6x: Refund endpoint documentation

## Key Metrics
- Total tasks: 47
- Completion rate: 68%
- Critical unstarted: 2

The engineering insight: This isn't hand-maintained. Markplane's sync command regenerates all context files by parsing the actual markdown items, resolving cross-references, and calculating metrics. The AI reads this instead of 47 individual files. The INDEX.md in each directory provides O(1) lookup—an agent scans ~200 tokens of index, then loads only specific items it needs. This is algorithmic efficiency applied to LLM context management.

Example 4: Custom Workflow Configuration

# config.yaml — customize task statuses for your team's process
workflows:
  task:
    draft:
      - backlog
    backlog:
      - planned
    planned:
      - in-progress
    in-progress:
      - in-review      # Custom status!
      - in-qa          # Another custom status!
      - done
    in-review:
      - in-qa
      - in-progress    # Can send back for revisions
    in-qa:
      - done
      - in-progress    # Bugs found, send back
    done: []            # Terminal state
    cancelled: []       # Terminal state

The power here: Status categories (draft, backlog, planned, active, completed, cancelled) control system behavior—kanban columns, progress calculations, archive eligibility. But you can place custom statuses under any category. A team using trunk-based development might add deployed under completed. A research team might add peer-review under active. The workflow engine validates transitions while remaining flexible.

Advanced Usage & Best Practices

Optimize Your Context Budget — The .context/ files regenerate on markplane sync or file changes. For large projects, tune what's included. The active-work.md focuses on current items; archive completed work to keep summaries lean. Your AI's context window is finite—protect it.

Branch Your Backlog — Because everything's git, experiment with git checkout -b feature/new-architecture and modify epics without affecting main. Merge when validated. This is impossible in SaaS tools without complex workspace duplication.

Validate Before Commit — Run markplane check in pre-commit hooks. It validates all [[TASK-xxxxx]] cross-references resolve, detects orphaned items, and ensures workflow state consistency.

Template Your Repetitive Work — The templates/ directory supports custom templates. Create a bug-report.md template with pre-filled sections for reproduction steps, environment, and severity. New bugs become markplane add --template bug-report.

Archive Aggressively — Completed items clutter context. The archive system preserves history while removing noise from active summaries. Your AI thanks you.

Comparison with Alternatives

The verdict: If you want AI collaboration, git-native workflows, and zero vendor lock-in, Markplane has no competition. Traditional tools optimize for PMs creating dashboards. Markplane optimizes for developers shipping code with AI assistance.

FAQ

Is Markplane stable for production use? Markplane is actively developed with a clear architecture documented in the repo. As with any young open-source project, evaluate against your risk tolerance. The file-based format means your data is always accessible even if development stalls.

Can multiple developers edit simultaneously? Since files are git-managed, standard git workflows apply. The web UI uses WebSocket for real-time sync of local changes, but distributed collaboration follows git's merge model. Conflicts are rare since items are individual files.

Does it integrate with GitHub Issues or other tools? Currently Markplane is self-contained. Import/export via standard markdown is possible. The MCP architecture could theoretically bridge to other APIs, but the philosophy is replacing external tools, not augmenting them.

How does AI context work with large projects? The INDEX.md pattern lets AI agents scan ~200 tokens to find relevant items, then load specifics. For very large projects, archive completed epics and use the metrics.md summary for high-level orientation. The context layer design scales sublinearly.

Can I customize the ID format? IDs like TASK-fq2x8 are auto-generated with readable prefixes and random suffixes. The suffix length balances collision resistance with readability. Customization isn't currently exposed but the format is consistent and parseable.

What AI assistants work with Markplane? Any MCP-compatible assistant: Claude (via Claude Code), Cursor, and growing ecosystem. The stdio transport is universal. See the MCP Setup Guide for specific configurations.

Is there a hosted/cloud version? No, and that's intentional. The entire value proposition is local-first, git-native, no infrastructure. A hosted version would contradict the core design.

Conclusion

Markplane represents a fundamental shift in how we think about project management in the AI era. It rejects the assumption that project data belongs in someone else's cloud, accessed through bloated web interfaces, manually kept in sync with actual work.

Instead, it asks: what if your project manager was as close to your code as your linter? What if your AI assistant understood your project state with the same efficiency it understands your functions? What if git log told the complete story of not just what changed, but why and in what priority?

The answer is github.com/zerowand01/markplane—a tool built by developers who felt the friction and chose to eliminate it entirely.

Install it today. Run markplane init. Connect your AI. Say "what should we work on?" and feel the future of development actually arrive.

Star the repo. Open an issue. Join the revolution where your repo is the project manager.