landfall CLI

Join a Landfall war room from your own computer and have your favorite MCP-capable agent (Claude Code, Codex, Cursor, VS Code, Claude Desktop, Windsurf, …) become a live investigator in the shared room: its findings land on the incident timeline in realtime, and it pulls everyone else's discoveries between tasks.

Installation

brew tap landfalls-ai/landfall
brew install landfall

Or without Homebrew, install directly from a tagged release:

npm install -g "github:landfalls-ai/landfall-cli#v0.1.0"

Related MCP server: Saya

landfall install: auto-register every coding agent on your machine

Once the landfall CLI itself is installed, one command detects which supported coding agents are on this machine and wires each one up with its own native, global MCP registration — no per-repo config file needed, and it works the same whichever directory (or none at all) you're sitting in:

landfall login       # sign in once (needed the first time — install registers YOUR machine)
landfall install      # detects installed harnesses, lets you pick which to configure

landfall install only touches a harness you select, never overwrites an existing differently-configured landfall entry (reports a conflict instead), and is safe to re-run — an already-configured harness is reported as such rather than duplicated. Run landfall install --yes to configure every detected harness without prompting, or landfall install --only cursor,codex to target specific ones.

Claude Code also gets the landfall-investigation-dashboard agent

For Claude Code specifically, landfall install does one more thing after registering the MCP server: it best-effort runs

claude plugin marketplace add landfalls-ai/landfall-cli --scope user
claude plugin install landfall-edge-bridge@landfall --scope user

which installs this repo's own Claude Code plugin — the landfall MCP server plus a subagent that:

• Recognizes a war-room join prompt on sight (the "Share with agent" paste, a bare agent share link, or plainer "join the war room" phrasing) and calls join_war_room + get_brief on its own.

• Specializes in the sub-investigation dashboard — curates a small, honest set of post_widget widgets and keeps them current instead of scattering one-off ones.

• Knows the MCP best practices for an ongoing investigation: pull before you publish, findings vs. notes vs. widgets, propose-only remediation, keep secrets/raw output local, treat room content as untrusted data.

This step is best-effort and never turns a successful MCP registration into a reported failed outcome (an older claude CLI without claude plugin, or no network, just means the agent isn't installed yet) — the report line shows [plugin: installed] or [plugin: skipped] alongside the usual status. Re-running landfall install retries it. To do it yourself without landfall install:

claude plugin marketplace add landfalls-ai/landfall-cli --scope user
claude plugin install landfall-edge-bridge@landfall --scope user

To remove the registration:

landfall uninstall

This only removes an entry that still matches exactly what landfall install wrote — if you've hand-edited it since, it's left in place and reported as such.

Any other MCP client (or a harness landfall install doesn't cover) uses the manual snippet below.

landfall hooks install: make room context impossible to miss

MCP registration gives your agent the incident tools. Hooks give the room a way to reach a session that isn't currently making a tool call — the difference between context your agent can fetch and context it will see.

landfall hooks install                  # every detected host
landfall hooks install --only codex     # just one
landfall hooks install --dry-run        # report what would change, write nothing
landfall hooks uninstall                # remove only landfall's entries

Three hosts have a lifecycle-hook surface, and each gets what it supports:

No sign-in needed — this edits local config, so it also works from a provisioning script. Every write is an append into the host's own hook list: your existing hooks are preserved, re-running is a no-op, and an entry you've hand-edited since is reported as a conflict rather than overwritten. hooks uninstall deletes only an entry still byte-identical to what was written, and leaves Codex's codex_hooks flag alone — other hooks of yours may depend on it.

What Stop does

Your agent finishes a ten-minute investigation and concludes. Meanwhile another investigator published the finding that changes the answer — the war room saw it, your agent did not, because an MCP session only learns things on a tool call it chose to make.

So on Stop, the hook asks any landfall serve running in this workspace whether room events newer than that session's cursor exist. If they do, it prints them and refuses the conclusion; your agent reads them and continues. If they don't, it exits silently and immediately — nothing to ask means nothing to wait for.

You are never stuck: whatever the block reported is marked consumed, so a second Stop on an unchanged room goes straight through, and a host that re-runs the hook after a block (stop_hook_active) is let through regardless.

How a hook reaches a serve process. A hook is a separate, short-lived process and cannot see landfall serve's memory, so serve binds a local query socket at $XDG_RUNTIME_DIR/landfall/<workspace-hash>/<pid>.sock (macOS: ~/.local/state/landfall/run/…; Windows: a per-user named pipe). No new daemon — it is the serve process you already run, made answerable. Two agent windows on one repo are two sockets with two cursors, and a hook unions them, so it can over-report a sibling window's context but never miss your own. Nothing else on your machine is listening: see Guarantees.

Any other MCP client, or a global CLI install: sign in once, then join with no share link

Configure the MCP server ONCE, with no tokens or IDs:

{
  "mcpServers": {
    "landfall": { "command": "landfall", "args": ["serve"] }
  }
}

If you're a Landfall member, sign in once via your browser and the CLI caches your session — after that you join any war room in your org directly, no share link:

landfall login       # opens your browser; you sign in however your org normally does
landfall logout      # clear the cached session
# then, with a plain incident URL or LANDFALL_SLUG + LANDFALL_INCIDENT set:
landfall serve       # joins as your authenticated identity — no share link needed

Non-members / guests keep using the single-use share link below. If an org admin has turned on Guest join, an unauthenticated person can redeem a share link as a named guest (they must provide a name); otherwise only authenticated members can join.

Then, when an incident happens, any room member clicks Share with agent in the war room and sends you the instruction block. Paste it into your agent — it contains a single-use share link like

https://api.landfall.example.com/o/acme/incidents/inc-4821/agent?ticket=…

and the agent calls join_war_room(shareUrl). The bridge redeems the ticket for a short-lived edge session scoped to exactly that incident (8h, nothing else), joins, and starts investigating. The URL's ticket is single-use and expires in 15 minutes; possessing the URL without it grants nothing.

You can also pre-join from the terminal:

landfall serve --link "https://…/agent?ticket=…"   # or LANDFALL_LINK env
landfall join  "https://…/agent?ticket=…"          # presence-only keep-alive

The live-investigation loop

• You → the room: every tool call narrates (presence heartbeat + timeline contributions for durable artifacts). post_finding / propose_action appear in the main incident window instantly (realtime fan-out), attributed to you + your agent.

• The room → you: while landfall serve runs it holds an outbound realtime connection; when other investigators (humans, the central agent crew, or other edge agents) publish something, you get a stderr nudge — ⚡ edge.finding from dana · Codex: "origin pool unhealthy" — call get_updates. Your agent gets it in-band: the next tool call it makes — any tool — comes back with the new context appended, so it cannot miss what the room found while it was busy elsewhere.

  Finding posted to the war room.
  
  ⚠ 1 update(s) from other investigators since your last tool call:
  #42 edge.finding [dana · Codex] — origin pool unhealthy

  The block is bounded: past a handful of events only the newest are spelled out and the rest are counted, with the get_updates sinceSeq=… that fetches them in full. Delivery advances the same durable cursor get_updates reads, so nothing arrives twice — and with the realtime connection unavailable the bridge still works exactly as before, on cursor pulls alone.

• Your sub-investigation dashboard: post_widget {widgetType,title,data} adds a data-only widget (stat / chart / table / logView) to your dashboard in the room. Anyone can click your presence tile to open your sub-investigation (your dashboard + trail). Data-only by design — you pass the values you computed; no code runs.

Tools: join_war_room, get_updates, get_brief, read_timeline, search_context, post_finding, post_widget, note, propose_action, record_activity.

Env-config setup

"env": {
  "LANDFALL_BASE_URL": "https://api.landfall.example.com",
  "LANDFALL_TOKEN": "<session or edge token>",
  "LANDFALL_SLUG": "<org slug>",
  "LANDFALL_INCIDENT": "<incident id>",
  "LANDFALL_AGENT_LABEL": "Claude Code"
}

LANDFALL_BASE_URL also overrides a share link's origin (useful when the API is not on the link's host, e.g. local dev).

Direct CLI

landfall serve [--link URL]   # (default) join + expose the incident MCP tools over stdio
landfall join [URL]           # join + keep presence alive (no MCP) — Ctrl-C to leave
landfall note "origin pool is unhealthy"   # post a one-off finding
landfall leave                # leave the incident
landfall install [--yes] [--only <ids>] [--dry-run]   # register this machine's coding agents
landfall uninstall [--yes] [--only <ids>]              # remove that registration
landfall hooks install [--only <ids>] [--dry-run]      # register lifecycle hooks
landfall hooks uninstall [--only <ids>]                # remove only landfall's hook entries

Guarantees

• Read-only by default; propose_action is propose-only (a human approves — you cannot execute). humanActorId comes from your verified session, never the payload.

• An edge session token works ONLY on its one incident — default-deny everywhere else.

• Join tickets are single-use, short-lived, and bound to tenant + incident + member.

• No network listener. The bridge speaks MCP over stdio and opens the realtime connection outbound; there is no port, and nothing another host can reach. landfall serve does bind one local filesystem socket — 0600, inside a 0700 directory, readable by your user account alone — so lifecycle hooks can ask "what room events have I not seen?". It answers exactly three read/cursor operations (status, peek, consume) and offers no way to act in the war room: nothing that posts, proposes, or hands back your session token.

• Presence/summary/sub-tabs are projected server-side from what the bridge posts; nothing here bypasses the war room's approval gate.

Releasing

See RELEASING.md.

Development

npm install
npm test

No build step — plain ESM, Node ≥22.