Documentation

Everything you need to get started with Flanner - the AI-powered plan file management system

Installation

Prerequisites

Python 3.8 or higher
Git installed and initialized in your project
Claude Code installed (optional, for MCP integration)

Install from PyPI

Flanner is on PyPI. Install it to use the flanner command from anywhere:

pip install flanner

Install from source (optional)

Prefer to run the latest from GitHub, or hack on it yourself:

git clone https://github.com/jaysonmulwa/flanner.git
cd flanner
pip install -e .

Quick Start

Navigate to Your Project

Make sure you're in a git repository:

cd your-project
git init  # if not already initialized

Initialize Flanner

Run the init command to set up everything:

flanner init

This command will:

Create the database at ~/.flanner/data.db
Detect your git repository root
Create .plans/ directory for plan files
Update .gitignore to exclude plan files
Automatically register with Claude Code

Verify Installation

Check that everything is working:

flanner status

Start Using with Claude

Restart Claude Code and ask Claude to manage your plan files:

"Claude, create a new architecture plan for our project"

"Claude, show me the history of the architecture plan"

"Claude, list all plan files"

CLI Commands

Core Commands

flanner init

Initialize Flanner in your project

flanner status

Check server status and project information

flanner list

List all projects

flanner list --project PROJECT_NAME

List plan files for a specific project

Plan File Management

flanner sync

Sync existing plan files into database

flanner sync --dry-run

Preview sync without making changes

flanner sync --project PROJECT_NAME

Sync specific project only

Web Interface

flanner web

Launch web UI on default port (8080)

flanner web --open-browser

Launch and auto-open browser

flanner web --port 3000

Launch on custom port

MCP Server

flanner start

Start the MCP server (prints connection instructions)

flanner stop

Stop the MCP server

Claude Code Integration

flanner claude-info

Show integration status

flanner register

flanner register --force

Force update configuration

flanner unregister

Unregister from Claude Code

Project Configuration

flanner config PROJECT_NAME --plan-dir DIR

Configure project settings

flanner setup-gitignore PROJECT_NAME

Update .gitignore manually

Plan File Format

All plan files managed by Flanner include YAML frontmatter with metadata:

---
mcp_plan_file: true
plan_manager_version: '1.0'
project_id: 3d816ecd-489a-4fa0-abe2-15ec93f60d5a
project_name: my-app
plan_file_id: 59c34f9c-8471-47fc-97f2-8dcfefa15434
plan_name: architecture
version: 2
created_at: 2025-01-15T10:30:00Z
created_by: claude
---

# Architecture Plan

Your plan content here...

Versioning

Versions are tracked by the version number in the frontmatter, not by filename. One file holds the whole history; the database keeps every version. To record a new version, edit the file, bump the number, and sync.

# 1. Edit .plans/architecture.md, then bump the frontmatter:
#    version: 2, and update created_at

flanner sync --dry-run   # preview
flanner sync             # OK UPDATED architecture.md (architecture, v1 -> v2)

Change per version

Increment version by 1
Update created_at
Change the content

Keep the same

plan_file_id — links all versions
project_id and plan_name
mcp_plan_file: true

Working through an agent, you never touch the frontmatter yourself — the MCP tools version the file for you. Ask Claude to “show the version history for the architecture plan” to browse it.

Web Interface

Launch the Web UI

flanner web --open-browser

Access at: http://localhost:8080

Features

Dashboard

Overview of all projects with statistics

Project Management

Create and manage projects

Markdown Preview

Beautiful rendering with syntax highlighting

Version History

Timeline view of all changes

Plan Editor

Edit plans with live preview

Responsive Design

Works on all devices

Claude Code Integration

Automatic Registration

Flanner automatically registers with Claude Code during initialization. No manual configuration needed!

flanner claude-info # Check integration status

Manual Registration

If needed, you can manually register or update:

flanner register

flanner register --force # Force update

flanner unregister # Unregister

Agent Integration

flanner init installs two layers so your agent routes plans through flanner instead of scattering raw markdown, with no reminding on your part. Works with both Claude Code and Codex.

Guidance the agent reads

A managed block is written into CLAUDE.md and AGENTS.md (read every session by Claude Code and Codex), plus a flanner-plan skill, telling the agent to save plans through the MCP tools.

A guard hook as backstop

A guard-write PreToolUse hook denies any raw write into the plan directory and points the agent back to create_plan_file_tool. It fails open and never blocks writes elsewhere.

MCP tools the agent calls

create_plan_file_toolCreate a plan file (adds the YAML header, records v1)

update_plan_file_toolRevise a plan and record a new version

get_plan_file_toolRead a plan file

list_plan_files_toolList plan files in a project

get_plan_history_toolGet the full version history of a plan

link_plan_to_linear_toolLink a plan to a Linear issue

link_plan_to_jira_toolLink a plan to a Jira issue

get_plan_configConfirm the plan directory and header format

Issue Tracker Integrations

Linear

live status sync

Link-only by default (no credentials). Set LINEAR_API_KEY to opt into live sync: verify issues, cache title and state, and refresh status. The key is read from the environment only, never stored or logged.

flanner linear config PROJECT --workspace acme
flanner linear link my-plan --issue ENG-123
flanner linear links                     # list all links
flanner linear refresh my-plan           # re-pull title + state (with API key)

export LINEAR_API_KEY=lin_api_xxxx        # opt into live sync
flanner linear auth                       # verify key, print MCP config block

Jira

supported · links

Link-only: store an issue key against a plan and build the issue URL. No API calls to Jira are made. One plan can link to multiple issues.

flanner jira config PROJECT --url https://you.atlassian.net --project-key PROJ
flanner jira link my-plan --issue PROJ-123 --type Epic
flanner jira show my-plan                 # links for one plan
flanner jira links                        # all links
flanner jira unlink my-plan --issue PROJ-123

Troubleshooting

Claude Code doesn't see the MCP server

flanner register

command not found: flanner

Reinstall, or run it as a Python module.

python -m flanner.cli --help

Database not initialized

Run init from inside your project. The database lives at ~/.flanner/data.db.

flanner init

Plan files aren't showing up

Sync the .plans/ directory into the database.

flanner sync

Ready to get started?

Install Flanner and start managing your plan files with AI assistance