Your terminal and the CLI

Landfall's promise to an investigator is that you keep using your favorite harness (the coding agent you already use), in your own terminal, on your own work, and still stay current on the incident without being interrupted. This page explains the pieces that run on your machine to make that true: the landfall CLI, how a war room's context reaches your agent and you, the lifecycle hooks, the status line, and the room daemon that keeps them all telling the same story.

How it works

• landfall serve is the MCP server your agent starts. It gives the agent the room tools (join, brief, updates, timeline, search, share, propose, artifacts, signal queries). It is a thin front end: it answers reads itself but leaves owning the room to the daemon.
• landfall daemon is one process per machine that owns every room you have joined: one join and one presence identity per room, one live connection to Landfall, and a separate reading position for every reader. It starts by itself the first time an agent joins and exits by itself a minute after the last one leaves. You never run it.
• Hooks are tiny landfall hooks … commands your agent host runs at fixed moments. They speak to the model only when you are owed something.
• The status line (landfall status) is the passive channel: it changes while you are heads-down and costs nothing to ignore.

When context reaches the model

Nothing can push into an agent turn that is not running. So there are exactly three moments, and the design uses all three:

1. On a tool result. After any Landfall tool call, the agent is handed what changed since its own reading position: items addressed to it in full, other substantive findings, and a count of routine activity.
2. At the start of your next prompt. The prompt hook adds what you have not been told, messages addressed to a person first. Then it marks you told.
3. When the model tries to conclude. The Stop hook refuses once if substantive room events arrived that the model has not read, and spells them out. It never refuses over the room's own machinery.

Two rules make this quiet. First, machinery is never news: Beacon's telemetry queries, widget build stages and read receipts do not count for anyone. Second, every reader has its own cursor: your agent's reads move its cursor, a hook delivering to you moves yours, and nothing moves another reader's. A helper your agent spawns can read the whole room without your status count dropping to zero.

The four hooks

landfall hooks install registers them in your host's own configuration (for Claude Code, ~/.claude/settings.json). Each one exits cleanly if it cannot reach the room; a hook must never turn into an error in your prompt.

• Prompt submit delivers the untold digest before the model reads your message.
• Stop refuses a stale conclusion once, then lets the model through.
• File changed watches a doorbell the daemon rings when a quiet room gets news, so a session that was idle picks it up on your next prompt.
• Pre tool use applies your local production allow-list to shell commands during an active incident.

The status line is installed alongside them, with a five-second refresh. Without it, the line is painted once and never again while you are idle, which is exactly when you need it.

The Claude Code mod

A hook runs only when its host fires an event, so with hooks alone an idle session sees a count on the status line at best. On Claude Code 2.1.287 and later, landfall hooks install also installs the Landfall mod, code that runs inside Claude Code and can draw while you are not typing.

• The stream. The mod starts landfall watch once per session. It follows the room daemon's own push and prints a line whenever what you would see changes. It never marks anything as read.
• The screen. A band above the prompt with the room, the count, the newest item in words and three keys (catch up, open the console, later); a toast when a message names someone; the status line under the prompt; and the /landfall console.
• The room at a glance. The status line carries the incident's status and severity, how many people are here and whether Beacon is investigating; the line under the prompt names who else is here and where; /landfall opens on Home, with the status, your vote and everyone in the room with their agents. All of it comes from the context frame the room daemon already caches, refreshed in the background when the status or the people change, so drawing it never waits on the network.
• Charts. When your agent reads a metric, key 4 puts that read on your dashboard in the room as a chart. The CLI rebuilds the chart from the same read, so no data point is copied by hand, and the key press is the only approval it needs.
• The model. Unchanged. On your next message the mod runs the same prompt-submit hook and hands its digest to the model, so every rule above still holds. Catch up only drafts a prompt; the mod never sends one and never answers a tool call.
• One voice. The mod tells Landfall's own hooks and status line to stand down in its session, so nothing arrives twice. Codex, Cursor, older Claude Code and organizations that only allow managed mods keep the hooks.

The console is the same code on every Claude Code surface. In a terminal it draws as text, and in the Code tab of the Claude desktop app it draws as native cards and buttons. Every read behind it is a landfall command that prints one JSON line (see the CLI reference), so the mod holds no credentials of its own. The tabs are described on Using Claude Code, and the desktop app, including the connector's cards in Chat, on Using the Claude desktop app.

What happens when you paste a link

A bare share link is the whole ask. Your agent joins in the session you are already in, reads the brief, and goes back to your work. It does not hand the room to a background helper on its own: a helper shares the session's connection, so the CLI cannot tell its reads from the main session's, and its lifetime would be nobody's decision. It uses room tools only and does not read or share your working directory for the room unless you say so. When it shares, it can say what kind of thing it is sharing; a reply addressed to a teammate is always a note, so an answer is never held behind the admission gate away from the person who asked.

The room daemon

• One room per machine. A second agent joining the same incident attaches to the room that is already open. Presence shows one entry for you, not one per window.
• Readers by name. Your agent (claude-code:…), your terminal (terminal:…), a helper, the Edge panel. landfall rooms lists them with their cursors.
• Restarts are safe. Rooms, readers and cursors are written to a private file so a restarted daemon rejoins and nothing is delivered twice. An idle exit forgets the rooms nobody was reading.
• Hooks read the daemon directly. Since v0.8.7 a hook or the status line asks the daemon once, as your terminal reader, instead of asking every agent process in the checkout; a process running without the daemon is still found.
• Older tools keep working. A front end still binds the per-process socket earlier hooks and status lines look for, and answers it from the daemon.
• The Edge desktop panel shows the same rooms. Its status bar carries a "Terminal" pill with your own unread count, the number your status line prints, and a popover listing every reader of every room with what it has not seen.
• Fallback. If the daemon cannot run, landfall serve says so in one line and behaves as it always did: one process, one cursor. LANDFALL_DAEMON=0 forces that.

Where you see it

• In your prompt: the digest the prompt hook adds before the model reads your message.
• At the end of a turn: the Stop hook's one refusal, when it has something to say.
• On the status line: landfall status, refreshed every five seconds.
• In a terminal: landfall rooms, which lists the rooms the daemon holds and every reader with its cursor.
• In Landfall Edge: the Terminal pill on the status bar, with its popover of readers.

Why it is built this way

Every claim above comes from a harness that runs a real interactive Claude Code session in a recorded terminal, joins it to a live incident with other investigators, plays a scripted afternoon of ordinary work, and scores the session transcript: how often the room made the person stop, what each interruption cited, how long a teammate's item took to reach the terminal, what the status line showed, and whether anything from the working directory leaked into the room. Between the first measurement and the room daemon, plumbing-only refusals went from three per session to zero, the unprompted background fork disappeared, and a teammate's item that a helper had already read went from never reaching the person to reaching them on their next prompt and on the status line within six seconds.

What is not here yet

One piece waits on agent hosts, and two are left out on purpose:

• No push into the model: the mod puts news on your screen at once, but the model hears it only with your next message. Pushing into the model would start turns nobody asked for. If that is ever wanted, the daemon is where it plugs in, and the per-reader accounting already prevents a double delivery.
• No model in the CLI: classification and the working-directory rule are explainable rules.
• No approve or execute anywhere: a remediation is a proposal for a human.