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

Freshness

flanner freshness

Freshness status for every plan, with the evidence behind it

flanner freshness PLAN_NAME

Status and evidence for one plan

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.

Freshness

Freshness tells you whether a plan still matches the code, with the evidence behind the verdict. It is computed on demand from the plan text plus git: nothing is stored, git access is read-only, and every status can show its reasons. It extracts the paths and symbols a plan cites, checks they still exist, anchors the plan version to the commit history, and counts how many commits touched the cited files since.

$ flanner freshness payment-webhooks

payment-webhooks v2: suspect
  - 24 commits touched cited files since anchor 4c19aef
  anchored_at_commit: 4c19aef8b21d
  referenced_paths: ['src/webhooks.py']
  referenced_symbols: ['verify_signature']
  commits_since_anchor: 24
  churn_scope: paths
  age_days: 12

The four statuses

fresh

Everything the plan cites still exists, and little has changed since it was written.

aging

Some movement: 5 or more commits touched the cited files, or the plan is over 45 days old.

suspect

Heavy churn: 20 or more commits touched the cited files since the plan was written (60 for the whole repo when the plan cites no files).

stale

The plan cites at least one path or symbol that no longer exists in the repo. The evidence names each one.

Agents can check this over MCP with get_plan_freshness_tool before trusting a plan.

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

get_plan_freshness_toolCheck a plan's freshness status and evidence before trusting it

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

Working with a team

Everything above works with no account and no network. This is the part that needs one, and it is four commands split across two scopes — three run once per machine, one runs once per repository, and mixing those up is the usual way it goes wrong.

Your invitation email carries the same steps, so you do not have to keep a page open while you follow them.

Access and binding are different

The distinction that catches people. Access is per person: an admin grants you a role in a workspace, and it reaches every machine you have enrolled when your entitlement next renews — up to a day later, or now if you run flanner whoami --refresh.

Binding is per repository: flanner join is what makes review in that repository count for the team. Being granted a workspace binds nothing on its own.

A workspace is not a repository — it is the boundary deciding who sees what, and everything inside one syncs as a single set.

The four commands, in order What Mesh is, and what it costs

Syncing between your devices

Devices find each other by public key, not by address. There is no VPN to install, no port to open, and no administrator rights needed. A machine dials out and answers on that connection.

flanner peer serve

Answer authorised peers. Opens no listening port; this machine dials out.

flanner peer pull <device-id>

Bring across what a teammate holds for this project's workspace.

flanner peer status

How this device is reached, and whether a peer connection is direct or relayed.

What syncing does not do

Plans move between your own machines. They are never uploaded to us, and a subscription manages accounts and access rather than storage.

Being reachable grants nothing on its own. A caller needs a signed request and an entitlement naming both its device and the workspace, and every version received is checked against its author's key rather than the peer that handed it over.

Ready to get started?

Install Flanner and start managing your plan files with AI assistance

Install Flanner GitHub Repository