FlightPlan is a team intent registry that lets coding agents declare work, detect collisions with other agents' in-flight or recently-completed work, and leave behind outcomes as searchable memory.
Declare work (post_intent) — register a task with summary, kind (build/explore/spike/decision), branch, and touches globs; get back an intent id plus overlapping intents and relevant past context.
Record decisions (post_intent with kind: "decision") — log a resolved decision with what was chosen, rejected, and why; stored complete, never collides, doubles as correction for wrong past outcomes.
Query the registry (list_intents) — semantic pre-planning collision check (summary), fast glob collision check (overlaps), or context/history search (q, since, author, branch, status, session), with alert levels warn/nudge/fyi.
Read full records (get_intent) — fetch whole summary/outcome by id or 8-char prefix when excerpts aren't enough.
Revise and heartbeat (update_intent) — change summary/globs as scope shifts, renew TTL on long work, and get fresh overlaps as a cheap mid-session re-check.
Close out work (complete_intent) — record outcome paragraph plus git facts (files, commits, uncommitted flag); the flag escalates collision warnings for others.
Report landings (mark_intent_landed) — tell the registry that declared-uncommitted work is now in git so warnings stop; idempotent and never rewrites the record.
Uses GitHub for account sign-in and repository access/registration, helping identify the current checkout via its origin remote and commit IDs so agents coordinate under the correct repository.
Your agents collide. File a FlightPlan.
Before work begins, each of your agents declares where it's headed and sees what's already in flight. They coordinate around conflicts, then leave behind what changed and why.
Advisory, never locking.
A byproduct of agent work, not another process to maintain.
FlightPlan coordinates coding agents before their work collides. This repo contains the CLI, MCP server, and installer for the hosted service at getflightplan.com.
From your repo's root:
uvx getflightplan installThat installs FlightPlan for Claude Code. For Codex or Cursor, append
--agent codex or --agent cursor. --agent also takes a comma list
(--agent claude,cursor) and all, which means every agent this version
knows. The command is safe to re-run.
The first time on a machine, run uvx getflightplan login next — it
connects your account and finishes the MCP setup.
The hosted service is in beta; sign in with your GitHub account at
getflightplan.com. The package is on PyPI, so the
command above is all you need. To pin a branch or commit instead, install from
the source:
uvx --from git+https://github.com/sledmonkey/getflightplan getflightplan install.
Version and compatibility policy: docs/versioning.md.
Related MCP server: agenthelm
File the work. Before editing, an agent declares its task and the files it expects to touch.
See what's in flight. FlightPlan returns overlapping active work, including uncommitted changes Git cannot see, decisions made during coding, plus relevant recent outcomes.
Coordinate. Overlaps are advisory: narrow the work, sequence it, or proceed with context.
Debrief. The agent records what changed, what surprised it, and what it tried so the next session does not start cold.
.flightplan.toml — pins the repo name every agent posts under, plus the
registry URL. Committed on purpose; no secrets.
A managed agent snippet in CLAUDE.md and/or AGENTS.md.
/registry-digest — an on-demand "what happened lately" command.
A session-end stop hook (.claude/hooks/flightplan_stop_hook.py plus its
settings wiring) that reminds the agent to close out open intents.
It also checks MCP registration and service reachability, and repairs the registration when the machine has a credential — no prompts. Verification is advisory and never fails the run.
To remove everything the installer wrote, run getflightplan uninstall from
the repo root (--dry-run to preview, --purge-key to also delete the saved
API key).
getflightplan login gets a credential without a copied API key. It opens
your browser, you approve there, and the credential goes to
~/.config/flightplan/env with mode 600. The credential is never printed.
After the credential is stored, login also registers the MCP server for
the agent binaries on your machine — the step install has to skip while
the machine has no credential.
On a machine with no browser, run getflightplan login --headless. The
command shows a short code and an address. Open that address on another
device and enter the code.
getflightplan logout removes the stored credential from this machine. To
revoke it on the service, use the /devices page.
After a login, the client asks the registry which repository this checkout is.
It sends the address of your origin remote and up to 1000 commit ids, which
prove that you have a clone. If your account has access, the id and the name
go into .flightplan.toml. If the registry does not know the repository, the
client offers to register it in your browser. If your account has no access,
the client offers to request it.
getflightplan login --no-register skips the check. getflightplan register
runs it on its own, later. A failed check never fails a login.
An intent completed with uncommitted: true says the work is in someone's
working tree and nowhere else. The registry cannot see your tree, so it keeps
warning everyone who touches those paths until it is told the work landed.
Agents do this with the mark_intent_landed tool. You can do it by hand:
getflightplan landed <intent-id> --commit <sha> --commit <sha>The commits are optional; the timestamp is the correction. Pass the SHAs only if you know them — the client never guesses which commits belong to an intent. Landing can be repeated safely and never rewrites the completed record.
The MCP server command is uvx getflightplan mcp — the mcp subcommand is
required. A bare getflightplan prints help and exits, so a registration or
directory build spec without mcp fails before the first MCP message.
FLIGHTPLAN_URL — optional; defaults to https://api.getflightplan.com
FLIGHTPLAN_API_KEY — your key (the MCP server's env; the stop hook also
reads ~/.config/flightplan/env).
.flightplan.toml — the per-repo pin: a repo name and url, or a
target_id with a readable name once the repo has an id pinned.
The installer adds the following managed contract with your repo name pinned. In a folder with no git, it writes a folder version instead. That version asks agents to post before work that others may use or edit, and to skip commit facts.
This repo participates in the team intent registry (MCP server: flightplan).
Before starting non-trivial work, call post_intent. The test: will the
work change behavior, defaults, or contracts another agent would encounter —
or, for pure investigation, would the findings save the next agent an hour?
Yes to either → post; Q&A and typo-level fixes, no. Send
a one-paragraph summary (what + why), kind (build, or
explore/spike for throwaway investigation), and touches globs for the
areas you expect to change. Keep the returned id for later. For repo,
use the basename of the git origin remote (or the repo root directory name if there is no remote) — every agent on this repo must use the same name or
collision checks silently miss each other. The response may include
context: recent completed work relevant to your task — read those outcomes
before starting; the surprises and dead ends in them are load-bearing.
If the response includes overlaps at level warn, check what the overlap is
before pausing. Two cases need no confirmation — mention the overlap and keep
going: the overlapping intent is the very work you were asked to act on
(reviewing it, verifying it, following up on it), or your task is read-only.
Otherwise, tell your user who is doing what and which globs collide, and ask
how to proceed before continuing. fyi/nudge levels: mention briefly and
keep going.
If the work changes shape or runs long, call update_intent: revise the
summary/touches when scope grows (collision checks run against them — stale
globs miss real collisions), or call with just the id to renew the TTL on
work spanning more than a day. The response includes fresh overlaps — the
same collision check as posting, glob-based — and a warn there gets the
same treatment as a warn at post time.
When the work finishes or is abandoned — including when the session is
wrapping up — call complete_intent with a one-paragraph outcome: what
actually changed, anything surprising, approaches tried and rejected, anything
deliberately left in place. If a warn overlap changed how the work went
(coordinated, narrowed scope, proceeded anyway), say which. Attach the git
facts you have: files changed (git diff --name-only), commits created,
and uncommitted — true if any work is not committed, false if all is.
Outside git, omit uncommitted and commits (no commit to wait for); still
send files. Send files: [] only when this work changed no files,
committed or not; omit files when you do not know. Completing an intent
ends the slice, not the session: follow-up work after a complete that
changes behavior, defaults, or contracts gets a fresh post — "same session"
doesn't exempt it.
When you learn declared-uncommitted work has landed, call
mark_intent_landed with that intent's id (and the commit SHAs if you know
them): until someone says so, the registry keeps warning everyone who touches
those paths.
Re-check for collisions whenever your picture of in-flight work may be
stale — posting checks once, and it goes stale over a long session.
Re-check moments: a file changed between your read and your edit, or an Edit
fails on text you just read — someone's work landed under you; before editing
a shared doc or artifact you didn't create this session; when resuming after
a handoff from another agent; and before touching files named in an earlier
warn. The cheapest re-check is
update_intent with just your intent id (renews the TTL, returns fresh
overlaps); use list_intents (pass overlaps globs, plus summary for a
semantic check, or q/since for history) when you have no open intent or
are scoping new work.
When a decision gets resolved in conversation (an approach chosen, an
alternative rejected, a direction set), record it the moment it settles:
post_intent with kind: "decision", the question as the summary, and the
resolution in outcome — what was decided, what was rejected, and why. One
call; no touches, no completion later. Decisions never collide and become
searchable team memory. Decisions are also the correction mechanism:
completed outcomes are immutable, so if one later proves wrong, post a
decision citing what actually held.
The registry is advisory and must never block work: if its tools are missing
or error, proceed with the work, and tell your user once that they can run
uvx getflightplan install (see getflightplan.com) to join this repo's
registry.
What leaves your machine is the coordination record: intent summaries and outcome paragraphs, glob patterns, changed-file paths, branch names, and commit ids — sent only to the FlightPlan service. Source code contents are never uploaded. Everything the registry knows, it learns as a byproduct of your agents' work.
The details — what never leaves, and what is stored where — are in docs/data-flow.md. Vulnerability reporting: SECURITY.md.
Apache-2.0
Close out an intent when work finishes or is abandoned. The outcome summary is required for done and is the most valuable artifact this system produces: write one paragraph covering what actually changed, anything surprising, approaches tried and rejected, and anything deliberately left in place. Gather git facts you already have at completion time: files = repo-relative paths actually changed (git diff --name-only over the work, committed or not); commits = SHAs created for this work; uncommitted = true if ANY of the work is not yet committed (untracked/unstaged/staged-only), false if all of it is. True makes other agents' collision checks warn loudly. Outside git, omit uncommitted and commits (there is no commit to wait for), but still send files. Send files: [] only when this work changed no files, committed or not; omit files when you do not know. Omit anything unknown. Any overlaps that come back carry excerpts, and overlaps_omitted counts the ones the server cut per level — use get_intent(id) for a full record.
Inputs: id (required), status (required), outcome (required), files, +2 more.
Fetch one intent's full record — the whole summary and outcome — by id or by a unique 8-char prefix. Overlap, context and list entries carry excerpts only, so call this when the excerpt is not enough: an overlap you have to describe to your user, or a context outcome you want to read in full before starting. Read-only; it records nothing.
Inputs: id (required).
Query in-flight and recent work across the team. Three distinct uses — pick exactly one: (1) pre-planning semantic check — pass summary (and optionally overlaps globs) to get an advisory semantic overlap before you post_intent; this is the strong collision check; (2) fast glob collision check — pass overlaps alone (no summary, no q) for deterministic prefix matching; (3) context search — pass q and since (add match=any for recall if a precise query returns nothing) to search summaries and outcomes including completed work. q and overlaps are AND-combined: a descriptive q alongside overlaps filters out overlapping intents whose summaries don't contain your words — for a collision check, omit q. q matches per-word (all words must appear, any order). Each returned intent carries an alert_level when overlaps is given: warn = surface loudly to your user; fyi = quiet mention; nudge = possible duplicate spike, suggest comparing notes. Rows carry outcome_excerpt by default; pass detail="full" for whole outcomes.
Inputs: q, kind, repo, limit, +10 more.
Record that work an already-COMPLETED intent declared uncommitted is now in git. Call this the moment you learn it: you committed and pushed that work yourself, or you can see in the tree that the work another session left uncommitted has since landed. Until someone says so, the registry keeps warning every agent who touches those paths and keeps re-telling the same story about work that is no longer at risk — a tree it cannot see is the one thing it cannot check for itself. Pass the commit SHAs if you know them; landing without them is fine and complete, the timestamp is the correction. Idempotent, and it never rewrites the completion record — the outcome, the reported files and the original uncommitted declaration all stand.
Inputs: id (required), commits.
Register what you are about to work on so other developers' agents can avoid collisions. Call this before starting any non-trivial task (anything touching more than a trivial fix). Infer kind: build for work meant to land, explore/spike for throwaway investigation, decision for a resolved decision worth recording (post it the moment a debate settles: pass the resolution in outcome — what was decided, what was rejected, and why; no touches needed; it is stored complete, never collides, and needs no complete_intent). Infer touches from your plan as repo-relative glob patterns. Returns the intent id — keep it to post the outcome later. Also returns any overlapping in-flight intents — active work (alert warn/nudge/fyi) and recently-completed work that may not have landed in git yet (always fyi): overlaps are the COLLISION signal — if overlap level is warn, tell your user before proceeding; for fyi, check whether that work is already in your tree before redoing it. The response also includes context — recently-completed work relevant to THIS task: read those outcomes before you start, the surprises and dead ends in them are load-bearing (a rejected approach you might retry, a gotcha you will hit). Overlap entries carry summary_excerpt; context entries carry summary_excerpt and outcome_excerpt. overlaps_omitted counts what the server cut per alert level — a non-zero warn there means more warnings exist than are shown. Call get_intent(id) for any full record.
Inputs: repo (required), summary (required), touches (required), kind, +3 more.
Update an in-progress intent. Call when the work changes shape (revise summary or touches — collision checks run against these fields, so stale globs silently miss real collisions) or when work runs long (a call with just the id renews the TTL heartbeat; active intents expire after ~48h without one). Calling with just the id ALSO returns fresh overlaps — the cheap mid-session collision re-check, since a post-time check goes stale over a long session. Treat a warn here exactly like a warn at post time: tell your user before proceeding. Overlaps carry excerpts, and overlaps_omitted counts any the server cut per level — use get_intent(id) for a full record. Never use this to finish work — call complete_intent for that.
Inputs: id (required), title, branch, summary, +1 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 6 tools
The six tools have mostly clear lifecycle boundaries: post, update, complete, get, list, and mark landed. However, list_intents is overloaded with three distinct modes (pre-planning semantic check, glob collision check, context search), and collision/overlap results also surface from post_intent and update_intent, which could make tool selection less immediate despite detailed guidance.
All tool names use snake_case and a predictable verb_object pattern: list_intents, post_intent, complete_intent, get_intent, mark_intent_landed, update_intent. The lone four-word name, mark_intent_landed, is still consistent and readable.
Six tools are well-scoped for an intent registry: create, list/query, fetch, update, complete, and mark landed. Each tool earns its place without obvious redundancy or missing lifecycle operations.
The surface covers the full lifecycle for work intents: registration, search/listing, detail retrieval, mid-flight updates and TTL renewal, completion with outcome, and post-completion landing correction. No obvious CRUD or workflow gap remains for the stated domain.
Coding agents from Claude Code, Cursor and Codex claim jobs and lock files on one shared board.
Coordination for AI coding agents: declare plans, catch design conflicts early, share team memory.
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.
Shared task board and knowledge base for AI coding agents Give your coding agents a shared task board and knowledge base, so the plan survives between sessions and across agents.
