Docs / Getting started

Getting started

Install Flanner and set it up in a repository.

Installation

Prerequisites

Python 3.10 or higher
Git installed and initialized in your project
Claude Code or Codex installed (optional, for the agent integration)

Install from PyPI

Flanner is on PyPI. This gives it an environment of its own and puts the flanner and flanner-mcp commands on your PATH:

uv tool install flanner

Both commands matter. Your agent spawns flanner-mcp by name, so it has to be findable from outside any project environment. uv installs in one line if you do not have it.

Or download the app

The desktop app is the same flanner with nothing else to install: no Python, no pip. It puts flanner and flanner-mcp on your PATH, shows the web UI in a window, and updates itself. Windows, macOS and Linux, from the download page.

Other ways to install

pipx

The same idea as uv, and already on many machines. Isolated environment, commands on your PATH.

pipx install flanner

pip

Works, with one caveat: it installs into whichever Python is active. Inside a project virtualenv, an agent started outside that environment will not find flanner-mcp.

pip install flanner

Run it once without installing

For a look around before committing to anything.

uvx flanner --help

There is no curl | sh installer, and that is deliberate. Flanner is a Python package rather than a single binary, so an installer would have to bring a Python with it — and the guard hook runs on every file your agent writes, where a self-extracting bundle would add hundreds of milliseconds to each call. The desktop app is the exception: it brings its own Python, installed once as an ordinary app rather than unpacked on every call.

Install from source (optional)

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

git clone https://github.com/elandlabs/flanner.git
cd flanner
uv tool install --editable .

Quick start

Step 01

Navigate to your project

Make sure you're in a git repository:

cd your-project
git init

Step 02

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
Register the MCP server with Claude Desktop, Claude Code and Codex. For Codex it adds its entry to ~/.codex/config.toml, or prints the two lines when it cannot do that safely
Write a managed block into CLAUDE.md and AGENTS.md, a .mcp.json entry and a guard hook, and install the flanner-plan, flanner-memory and agent-blast-radius skills for both agents
On a team with messages on, add a messages hook and a note on the message tools to the agents it sets up, and ask once whether to start receiving messages when you log in

To register only one agent, use --setup codex (or claude-code, claude-desktop). To skip agent registration, use --skip-claude. To repair it later, run flanner setup.

If the repository already has plan files, run flanner init --sync to import them.

Step 03

Verify installation

Check that everything is working:

flanner status

Step 04

Start using it with your agent

Restart Claude Code or Codex so it reloads the config, then ask it to manage your plan files:

"Create a new architecture plan for our project"

"Show me the history of the architecture plan"

"Remember that we chose Postgres because we need concurrent writers"