Flanner

Flanner

A plan-file manager for AI coding agents, wired into Claude Code and other assistants over MCP (Model Context Protocol).

Why

AI agents write markdown constantly: design docs, migration plans, architecture notes. It piles up fast, scattered across your repo, quietly going stale, and easy to commit by accident. Flanner gives those files one home, versions them automatically as the agent revises, and keeps them out of git until you decide otherwise, with a browsable reading view and an audit trail on top.

No, I'm not convinced. But why?

Those plan files pile up in two directions at once: scattered across your projects locally, and scattered across open issues in your project-management tool. Flanner is the choke point for both, keeping you organized on disk and linked to the issue each plan belongs to.

Flanner is local-first, and stays that way when a team uses it. Plans sync directly between your machines over an encrypted connection — there is no server holding them, and no upload step. The hosted side (Flanner Mesh) issues identities and decides who may read what; it never sees plan contents and could not read them if it wanted to. Next after that: clean links out to the tools teams already work in, from product trackers and chat to second brains like Notion.

Features

• MCP integration: exposes plan-file tools to Claude Code and Codex.
• Automatic headers and versioning: every plan gets YAML frontmatter, and each revision is a new version with a full history.
• Git protection: plans live in .plans/ and are kept out of commits automatically.
• Agent integration: flanner init wires CLAUDE.md, AGENTS.md, and a guard hook so agents save plans through flanner instead of scattering raw markdown.
• Memory: the durable context around a plan — a constraint, a rejected library, a fact about the environment — kept as Markdown files a later session can search. By default an agent proposes and you approve; it refuses anything that looks like a credential, and shares with a teammate only when somebody asks for it.
• Skills: what your agents actually load. Skill packages arrive from a project, your home directory and every installed plugin at once, and when two share a name one wins silently. flanner skills scan reads them all and flanner skills doctor says which copy is in effect and what is wrong with the rest. A read: nothing in a package is executed.
• Curb: what each agent can reach. flanner curb map checks every Claude Code and Codex launch for readable credentials and for the channels that could carry them away, and rates it High, Medium or Low with the rule behind it. Its output never names a credential or a location, whoever runs it; flanner curb show puts those in a window on your screen. flanner curb sweep finds secrets agents left behind in transcripts, sessions, instruction files, skills, MCP configs, shell history and .env files, and says which were sent to a model provider. A read: nothing is changed, and nothing leaves the machine unless you ask a secret's own issuer to check it. With Flanner Mesh, flanner curb policy takes one agent policy your organization signs, applies the changes that only tighten once you enrol, and holds anything else for your approval; flanner curb fleet shows admins each device's policy state and counts, from minimised reports each device signs. flanner curb ci, also a GitHub Action at actions/curb-ci, judges agent steps in CI workflows the same way and writes SARIF; flanner curb app finds an application's own LLM calls; and the agent-blast-radius skill lets an agent run the redacted commands itself. flanner curb attribution gives each agent a signing key of its own, kept in your OS credential store, so its commits are labelled; flanner curb verify says which agent key signed each commit, checked against your organization's signed key registry. A signature shows which key signed, not who wrote the code.
• Messages (Team Mesh): teammates can message each other inside their agents, device to device. flanner messages send previews before it sends, and flanner tells an agent to show a teammate's message and never act on it.
• Issue tracker links (off in this build): tie a plan to its Linear (or JIRA) issue; with a LINEAR_API_KEY, flanner verifies the issue and shows its live state, in the CLI and the dashboard. Built but not supported yet: set FLANNER_INTEGRATIONS=1 to turn them on.
• Reading view: a browser dashboard to read, edit, and walk the history of plans (light and dark, fully offline).
• Per-project config: customize the plan directory per repository.

Quick start

uv tool install flanner   # or: pipx install flanner, or: pip install flanner

cd your-project # a git repo where plans should live flanner init # sets up the database, MCP registration, and a project

Rather not install Python? The desktop app for Windows, macOS and Linux is the same flanner with nothing to install first: the web UI in a window, the command line, and the MCP server Claude and Codex use, with background sync and updates. Download it from flanner.io/download; desktop/README.md covers building and releasing it.

uv tool install gives flanner an environment of its own and puts both flanner and flanner-mcp on your PATH. Both matter: your agent spawns flanner-mcp by name, so a project virtualenv can hide it from an agent started outside that environment. pip install flanner works, with that caveat.

Then ask your agent to work with plans:

"Create an architecture plan for the auth service"

"Show me the history of the architecture plan"

And open the dashboard to browse them:

flanner web --open-browser     # http://localhost:8080

flanner init is safe to re-run. It detects your git root, creates .plans/, updates .gitignore, and installs the agent integration.

Three agents, three different files, and init handles all of it — there is no second command to remember. It writes a project-scoped .mcp.json that Claude Code reads, registers the server at user scope and in Claude Desktop's config, and adds managed blocks to CLAUDE.md and AGENTS.md. Codex reads AGENTS.md and registers MCP servers in ~/.codex/config.toml; when Codex is installed, init adds flanner's entry there, and prints the two lines to paste only when it cannot edit the file safely. flanner status shows a row per agent, each checked where that agent actually looks, and flanner setup re-runs the registration on its own if one of them needs repairing later.

--setup picks which of them you want, and repeats: flanner init --setup codex registers Codex and nothing else. --skip-claude registers with no agent, though the repository's own files are still written.

Adopting a repository somebody else set up? flanner init --sync also imports the plan files already committed in it, so flanner list shows them straight away.

CLI commands

flanner init [--project-root PATH] [--plan-dir DIR]     # set up a project

flanner status # projects, plan files, db path flanner list [--project NAME] [--output json] # list projects or a project's plans flanner sync [--project NAME] [--dry-run] # import existing .plans/ files flanner config NAME [--plan-dir DIR] [...] # change project settings flanner web [--port 8080] [--host 127.0.0.1] [--open-browser] flanner start [--port 8765] / flanner stop # MCP server in the background, over http flanner peer start / flanner peer stop # serve plans to teammates in the background flanner mem remember "..." --category fact # durable context for later sessions flanner mem recall "..." # search what earlier sessions knew flanner mem list / show ID / supersede ID --with "..." # browse, read, and correct flanner mem mode [off|explicit|suggest|auto_safe] # how much this project captures flanner mem share ID / flanner mem withdraw ID # give one to the team, or ask them to stop flanner skills scan / flanner skills doctor # what your agents load, and what is wrong flanner skills list [--all] / inspect NAME # browse them, or read every copy of one flanner skills observe enable / flanner skills report # record which get used; init asks flanner skills adopt NAME / install HASH / rollback ID # keep a copy, install it, put it back flanner skills share HASH / transfers / import ID # send one to the team; receiving is not installing flanner curb map [--agent A] [-- LAUNCH ...] # what each agent launch can reach flanner curb show # names and locations, in a window flanner curb inventory # agents, MCP servers, hooks, jobs flanner curb sweep [--validate] # secrets agents left behind (needs flanner[sweep]) flanner curb forget # delete Curb's reports and digest key flanner curb fix [--dry-run|--undo] # close what agents reach, after your OS says yes flanner curb test # prove each block with decoys (costs tokens) flanner curb decoys [--renew|--remove] # the decoys the tester planted flanner curb scrub FILE [--dry-run] # replace rotated secrets in a file (no undo) flanner curb log [--enable|--disable|--verify] # each tool call's metadata, hash-chained and signed flanner curb observed # what each agent has been seen using flanner curb policy [--check-in|--enrol|--approve] # your organization's signed agent policy flanner curb fleet # every device, checked by its own signature (admins) flanner curb ci [PATH] [--sarif F] [--fail-on L] # agent steps in CI workflows, as SARIF flanner curb app [PATH] [--sarif F] # LLM calls in an app's Python code flanner curb attribution [--setup|--rotate] # sign each agent's commits with its own key flanner curb verify [REV|RANGE] # which agent key signed each commit flanner register [--force] / flanner unregister # MCP registration with Claude Desktop flanner claude-info # integration status

Most MCP clients spawn their own copy of the server over stdio and need neither start nor stop. They are for a client that only speaks http, two editors sharing one server, or working with flanner on its own. The server binds 127.0.0.1 and no option widens that: every tool acts with the full authority of whoever started it, and nothing authenticates a caller.

Plan file format

Every managed plan carries YAML frontmatter, generated by the tools and never hand-written:

---

mcp_plan_file: true project_id: 3d816ecd-489a-4fa0-abe2-15ec93f60d5a plan_file_id: 59c34f9c-8471-47fc-97f2-8dcfefa15434 plan_name: architecture version: 2 created_by: claude

---

Architecture Plan

Your plan content here...

</d