Skip to main content
Glama
ShellPuppet
by intermeld
README.md
# ShellPuppet

![Screen recording: Claude Code runs four other coding agents (Codex, Antigravity, Grok and Qoder) side by side, each in its own ShellPuppet terminal. Codex's window lights up amber when it asks permission to run a command; the person answers in that window, declining with a reason, and Codex carries on with its review.](docs/media/demo.gif)

▶ [Watch the full demo](https://github.com/intermeld/shellpuppet/releases/download/v0.1.0/shellpuppet-demo.mp4)
(67 seconds, MP4)

**Supervised terminal sessions for AI agents.** An agent drives a real terminal
while a human watches, and types into, the same live session from a
browser. The terminal runs whatever you point it at: an agent CLI such as
Claude Code, Codex, Antigravity, OpenCode, MiMo Code, Qoder, Goose or Grok,
or any other TUI.

ShellPuppet is to the terminal what Playwright is to the browser. Playwright
gives a program a real browser: the program clicks, reads the page, waits and
works on pages only a person could use. ShellPuppet gives an agent a real
terminal the same way.

Without ShellPuppet, an agent runs a program the way you might shout through a
closed door: one instruction goes in, one note comes back, and if the program
asks a question, nobody is there to answer it. ShellPuppet opens the door. The
agent sits at the keyboard: it types, looks at the screen, waits and types
again. And there's a window on your screen, so you can pull up a chair,
watch what it's doing and take the keyboard yourself whenever you like. Some
programs only work if someone is sitting there: menus, wizards, chat-style
tools, other AI assistants. An agent couldn't use those at all. Now it can.

ShellPuppet is the open-source terminal layer of **Intermeld**, the agent
governance platform by [Red Eagle Tech](https://redeagle.tech). Everything in
this repository runs on your machine and needs nothing we operate.

> **Status: 0.2.1, with the dashboard.** The daemon, CLI, MCP server, viewer
> and dashboard install from npm (below). Watch the repository's Releases for what comes
> next, and bring questions, ideas and what you build with it to
> [Discussions](https://github.com/intermeld/shellpuppet/discussions). 🦅

## What you get

- **Real terminals, driven by tools.** Sessions run in a real PTY (ConPTY on
  Windows), rendered through a real terminal emulator and exposed as twelve
  small MCP tools: start, snapshot, type, key, wait, find, result, list,
  resize, screenshot, viewer-url, kill. The CLI has a verb for each, spelled
  `snap` for the snapshot.
- **An agent's answer without its reasoning.** Several agent CLIs draw the
  model's reasoning on screen as they work. A supervising agent can read a
  session with that left out (snapshot, find and wait take `hideReasoning`),
  or take just the answer that ended the latest turn, and so keep another
  model's reasoning out of its own context. A screenshot shows the whole
  screen.
- **A human in the same session.** When the first session starts, the dashboard
  opens on your machine. Later sessions appear there. You see what the agent sees, live, and you can type
  into it: to answer a prompt, to correct course or to take over. Your window
  sets the size: the terminal reshapes itself to fill it, as a terminal
  should. To watch from another device, or to let someone else watch, ask the
  agent for a link or run `shellpuppet viewer-url <id>`. A fresh link is live
  until it's opened, so hand it over as you would a key; it works once and for
  a few minutes, so a link in an old transcript is spent. `--read-only` gives
  one that can watch but never type.
- **Waits instead of sleeps, and prompts you're told about.** `wait` blocks on
  text, a regex, quiescence or "the program is asking a question". The daemon
  spots permission prompts in driven agent CLIs, flags sessions that sit on
  one and badges the viewer so the human knows they are needed.
- **Nothing leaves your machine unless you send it or switch it on.** Today
  the tool has no outbound path at all: no telemetry, no crash reporting, no
  update checks, and the daemon listens on `127.0.0.1` only. Diagnostics, when
  it comes, stays off until you switch it on, carries no session content and no
  identifiers, and writes every payload to a local file before it leaves. That
  rule, nothing leaves unless you send it or switch it on, is a permanent
  property of the tool rather than a default. [VISION.md](VISION.md) and
  [SECURITY.md](SECURITY.md) say why.

## Quickstart

Install, then wire it into your agent and ask it for something; or run the
five commands under *Check the install from any shell*.

You need Node.js 22 or later. On Windows you need Windows 10 version 1809
(build 18309) or later: the sessions run on ConPTY, which node-pty 1.2.0
requires (it removed its winpty fallback); a start on an older build is
refused with the minimum named. `node-pty` ships prebuilt binaries for
Windows and macOS and, in the 1.2.0 beta ShellPuppet pins, for mainstream
Linux too (glibc, x64 and arm64), so no compiler is needed there. Where no
prebuilt matches (another architecture, or musl in place of glibc), npm
builds it with node-gyp, which needs Python 3, make and a C++ compiler (on
Debian and Ubuntu: `sudo apt-get install -y python3 make g++`).

**Install:**

```sh
npm install -g shellpuppet                            # Windows and macOS
npm install -g --allow-scripts=node-pty shellpuppet   # Linux
```

On Windows, npm installs `shellpuppet` as a PowerShell script as well as a
`.cmd`, and PowerShell's default execution policy refuses the script. Run
`Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned` in that
window first, or run ShellPuppet from Command Prompt.

npm 12 runs a dependency's install script only when you allow it. On Linux,
node-pty's install script is what builds it where no prebuilt binary matches
the machine. Without the flag the install still completes; where a prebuilt
binary is present it loads that, and otherwise `shellpuppet start` refuses and
names the flag.

Recent npm 11 releases and npm 12 print a warning that node-pty has install
scripts. On Windows and macOS ShellPuppet needs none of them, so there the
warning is safe to ignore. npm 10 ignores the flag, and early npm 11 releases
warn that it is an unknown option; both run the install scripts anyway.

On macOS, ShellPuppet makes node-pty's `spawn-helper` executable itself on
the first start. If you installed with `sudo`, it can't, and that first start
tells you the `sudo chmod +x` to run once.

**From source** (the same thing, plus a build):

```sh
git clone https://github.com/intermeld/shellpuppet.git
cd shellpuppet
npm ci
npm run build
npm link            # puts `shellpuppet` on your PATH; or use `node dist/cli/index.js`
```

On Windows the shim `npm link` makes meets the same execution policy; set it
as above, or use the `node dist/cli/index.js` form instead.

**Wire it into your agent.** ShellPuppet is an MCP server. With `shellpuppet`
on your PATH, Claude Code is one command:

```sh
claude mcp add shellpuppet -- shellpuppet mcp
```

For any other MCP client, the equivalent entry:

```json
{
  "mcpServers": {
    "shellpuppet": { "command": "shellpuppet", "args": ["mcp"] }
  }
}
```

That shape works for Claude Code, Cursor, Gemini CLI and the desktop apps.
Codex reads `~/.codex/config.toml` instead:

```toml
[mcp_servers.shellpuppet]
command = "shellpuppet"
args = ["mcp"]
```

Without `npm link`, use `node` with the absolute path to `dist/cli/index.js`
and the argument `mcp`.

**Then ask your agent for something.** Tell it to run a program in a
ShellPuppet session. A window opens on your screen as the session starts: you
watch, and when the program asks a question, you click into the window and
answer it. A good first ask: *"Run `npm create vite@latest` in a ShellPuppet
session, in an empty folder, and let me choose the options."* npm first asks
whether to install the wizard: answer y, and the wizard's menus appear in the
window as they come, each one flagged for you; pick with the arrow keys and
Enter. In the recording at the top, four agents do this at once, and the
person answers Codex's permission prompt in its window.

**Check the install from any shell.** The CLI has a verb for every tool, so
you can drive a session by hand:

```sh
# 1. Start a Node REPL in a real PTY. The daemon starts itself, you get a
#    session id (s1) and the dashboard opens (or a viewer link, if no window can).
#    s1 is the first session on a fresh daemon: use whatever id start printed.
shellpuppet start --label demo --no-shell node

# 2. Wait for the REPL to paint and settle, instead of guessing at a sleep.
shellpuppet wait s1 --quiet 1000

# 3. Type as an agent would, and confirm the keystrokes landed.
shellpuppet type s1 '6 * 7' --enter --verify

# 4. Read the screen back as plain text.
shellpuppet snap s1

# 5. Kill the session: the whole process tree, not just the PTY child.
shellpuppet kill s1
```

Step 2 prints the REPL banner and prompt, step 3 says `typed 6 bytes (verified
on screen).` and step 4 shows `42` under your input. That exercises daemon
auto-start, the PTY, the renderer, waiting, input verification and tree-kill.

**No window?** By default a session start opens the dashboard in ShellPuppet's
own isolated browser profile. If that window cannot open, `start` prints a
single-session viewer link. On a headless machine, or if you'd rather have a
link, set `viewer.launchMode` to `"no-window"` in `~/.shellpuppet/config.json`:
`start` then prints a viewer link,
and an agent is given one to pass to you. Whatever the setting, `shellpuppet
viewer-url <id>` mints a fresh link whenever you want one, and `--read-only`
makes it a link that can watch but never type. The options are in
[`docs/reference/configuration.md`](docs/reference/configuration.md).

In the viewer, on Windows and Linux, Ctrl+V pastes; to send a literal Ctrl+V
to the program, there is no in-pane shortcut. Ctrl+C copies selected terminal
text, and sends `^C` when nothing is selected. On macOS, Cmd+V pastes and
Ctrl+V still sends `^V`.

**How long it takes.** On clean machines:

- **Windows 11** (a fresh Windows Sandbox, Node 24): installing ShellPuppet with
  npm took 22 to 26 s from a cold npm cache, and the five steps above 3.6 s end
  to end.
- **Linux** (a clean container, Node 22): the install took 29 s, including
  npm building node-pty, and the five steps about 2 s.

The first viewer window on a fresh machine takes longer, about 13 s in that
sandbox, because the browser is starting for the first time.

## Working with an agent

Twelve tools appear once the server is wired in: `terminal_start`,
`terminal_snapshot`, `terminal_type`, `terminal_key`, `terminal_wait`,
`terminal_find`, `terminal_result`, `terminal_list`, `terminal_resize`,
`terminal_screenshot`, `terminal_viewer_url` and `terminal_kill`.

| Tool | Prompt supervision |
| --- | --- |
| `terminal_start` | Pass `waitReady: true` when starting an agent CLI to delegate work to. Returns ready, a question, exit or a timeout with the session still running. |
| `terminal_wait` | `prompt: true` with no session or an array of ids waits for any prompt. `now: true` polls once. Both return compact details without a screen. |
| `terminal_list` | `waitingOnly: true` returns only sessions waiting on a prompt. |

`terminal_wait` with `prompt: true` can omit `session` to wait for a prompt in
any live session, or take an array of session ids to watch only those. It
returns compact waiting sessions without screens; `now: true` polls once.
`terminal_list` with `waitingOnly: true` returns the same compact view. The
CLI forms are `shellpuppet wait --prompt [id ...] [--now]` and
`shellpuppet list --waiting`. A wait with one string session id keeps its
usual screen response.

`terminal_start` does not wait by default. With `waitReady: true` it uses the
resolved agent's known ready signals, or your `readyText`/`readyQuiet`
override. `readyTimeout` defaults to 30,000 ms and is capped at 300,000 ms.
A longer explicit wait needs a longer MCP client budget, including startup
overhead. A client that gives up may lose the answer; the session still exists
and `terminal_list` shows it. Shells and unknown programs
need an explicit condition. Dashboard launches and launch profiles never
wait. See the [MCP start reference](docs/reference/mcp.md) for the outcomes.

The HTTP `GET /sessions/wait?prompt=true` response is compact, including on a
timeout or an immediate `now=true` poll:

```json
{
  "matched": true,
  "reason": "prompt",
  "waitedMs": 80,
  "sessions": [
    {
      "id": "s2",
      "label": "build delegate",
      "question": "Allow this command to run?",
      "options": ["Allow once", "Deny"],
      "selectedOption": 0,
      "waitingMs": 4200
    }
  ]
}
```

`reason` is `prompt` or `timeout`. A timeout has `matched: false` and an empty
`sessions` array. Each row always has `id`, `label` and `waitingMs` in
milliseconds; `question`, `options` and `selectedOption` are optional.
`hideReasoning=true` removes `question` and `options`. `GET
/sessions?waitingOnly=true` returns the same rows in its `sessions` array,
alongside the usual `version` field. MCP tool results frame prompt text as
untrusted terminal data, including the full `terminal_list` result. Each result
uses one matching pair of delimiter lines with a fresh random nonce. Terminal
output cannot predict the closing delimiter or end its own frame.

Text snapshots (`terminal_snapshot`, `terminal_wait`, `shellpuppet snap` and
`lastLines`) prefix a uniquely styled menu choice with `⟦SP:selected⟧ `. This
text annotation is never sent to the terminal or viewer. A detected prompt
keeps its option labels unchanged and reports `selectedOption` separately as
their zero-based index, when inverse video or a background colour identifies
one choice. Ordinary highlighting adds neither field nor marker.

When the session runs another agent CLI, `terminal_result` returns the answer
that ended its latest turn and nothing else, and `terminal_snapshot`,
`terminal_find`, `terminal_wait` and `terminal_screenshot` take `hideReasoning`
to leave out the reasoning it draws. A filtered `terminal_list` omits every
waiting prompt's question and options, whether or not the session has a
signature. Each CLI's screen is read by a signature: Claude Code,
Codex, Qoder, OpenCode, MiMo Code, Grok and Antigravity are built in. A
session started through a shell or a launcher script says which CLI it runs
with `terminal_start`'s `agent`. Snapshot, find, wait, screenshot and
`terminal_result` refuse a session with no signature rather than show it
unfiltered.

**Important:** A session whose model is a Claude model should **ALWAYS** pass
`hideReasoning: true` on every call that reads a screen: `terminal_snapshot`,
`terminal_wait`, `terminal_find`, `terminal_screenshot`, `terminal_list`, and
`--hide-reasoning` with their CLI equivalents. Claude models' safety checks can
flag another model's reasoning read off a screen as an attempt to extract
reasoning and stop the session. Leaving the reasoning out avoids that;
`terminal_result` gives the agent's answer. With the flag, a Claude model can
use every ShellPuppet tool freely. Other models can leave the flag off when
they need the full screen.

In a filtered screenshot, hidden rows are blurred and dimmed before capture;
its returned row text is filtered too. A filtered session list reports that a
prompt is waiting and for how long without its question.

`terminal_start` opens the dashboard for you when needed and tells the agent
what happened. It gives the agent a viewer link when no window could open, and
`terminal_viewer_url` mints one whenever you ask: for a
second device, a closed window or someone who should watch without typing.
Links work once and for a few minutes. An agent CLI that needs a key held only in the
client's environment gets the names you list for it in `agents.passEnv`, and any
other program the names you list in config `envNames` and ask for at start
(`docs/reference/configuration.md`). Sessions
otherwise start with a clean environment, not the daemon's, so a key in the
daemon's environment doesn't reach them. `terminal_screenshot` returns a PNG of the viewer as a
browser draws it. Use it to illustrate documentation with real screens, and to
check what is *actually* on screen when the text looks right and something
still seems wrong. A capture has 45 s to start a browser, draw the page and
take the picture; `shellpuppet screenshot --timeout <ms>` moves that budget
for a machine that is slower or in more of a hurry.

The tool descriptions carry the lessons that cost real time to learn: first
paint is not readiness; a wait for text you just typed matches your own echo;
`escape` resets a TUI that has stopped listening. The measured behaviour of
each agent CLI, with ready-text regexes and timeout budgets, is in
[`docs/reference/agent-profiles.md`](docs/reference/agent-profiles.md).

## The CLI

```
shellpuppet start [options] <command> [args...]   # options BEFORE the command
shellpuppet list | snap | type | key | wait | find | resize | kill
shellpuppet screenshot <id> [--out <file>]        # the viewer, as a browser draws it
shellpuppet viewer-url <id> [--read-only]         # a fresh single-use viewer link
shellpuppet dashboard                             # the dashboard, in its own isolated window
shellpuppet desktop                               # start or reuse ShellPuppet's dashboard
shellpuppet desktop --install                     # add or update your application shortcut
shellpuppet desktop --uninstall                   # remove that shortcut
shellpuppet daemon status|start|stop|restart     # manage the shared daemon
shellpuppet daemon stop --hold [seconds]         # pause automatic starts (default 120 s)
shellpuppet mcp
```

Use `shellpuppet start --wait-ready <agent-command>` when delegating work.
`--ready-timeout <ms>` changes the 60-second limit, up to 300 seconds.
`--ready-text` or `--ready-quiet` overrides the agent's signal and is required
for a program without one. The output names a question that needs answering,
reports an exit, or says whether the session is ready. A timeout leaves it
running. See the [CLI start reference](docs/reference/cli.md).

### Restarting a shared daemon

Build first, then run `shellpuppet daemon restart` so other clients wait for
the replacement, including while the old daemon is stopping. A peer can wait
about 20 seconds for a direct restart or about 130 seconds when the restart
uses `startWith`. A failed wrapped start may add up to 15 seconds for cleanup,
so the caller's worst case is its fixed deadline plus 15 seconds, up to about
145 seconds for a wrapped restart. The wait has a fixed deadline, and clients can resume starting
if the process performing the restart has gone. To stop before rebuilding, run `shellpuppet daemon stop
--hold`, rebuild, then run `shellpuppet daemon start`. The hold lasts 120
seconds by default (1 to 600 seconds with an explicit value), and `daemon
status` shows the time remaining. If `daemon restart` cannot read the daemon
record, wait about 15 seconds and run `daemon restart` again. If the record
is still missing, the daemon is usually stopped. Check that no ShellPuppet
daemon process is running before `daemon start`.

On Windows, `start` uses `cmd.exe /d /s /c` by default. ShellPuppet joins the
command and arguments with spaces; `cmd.exe` then parses that line. A value
containing spaces needs quotes *inside the argument sent to ShellPuppet*. For
example, from Git Bash:

```sh
shellpuppet start --agent codex node.exe codex-seat.js personal -c 'mcp_servers.x.command="C:/Program Files/nodejs/node.exe"'
```

Git Bash removes the single quotes. ShellPuppet receives one argument with
double quotes around the path; `cmd.exe` and the program's argument parser
use those quotes to retain the space. Quoting only the whole value for Git
Bash, as in `'mcp_servers.x.command=C:/Program Files/nodejs/node.exe'`, does
not protect the space from `cmd.exe`. The shell also interprets `^`, `&`,
`|`, `<`, `>` and expands `%NAME%`, even inside double quotes. For literal
arguments to an `.exe` or `.com`, use `--no-shell`; the same choice is
`shell: false` in `terminal_start` and launch profiles. On other platforms,
starts run directly by default; an explicit `shell: true` uses `/bin/sh -c`
and its shell syntax.

`shellpuppet dashboard` opens a window with a pane for every session in ShellPuppet's
isolated browser profile and prints only whether a window opened. It never
prints the link, and it never uses your default browser: if the isolated
window cannot open, the command fails rather than hand the grant to a profile
with extensions.

To share sessions across screens, use **Open on screen** in the dashboard
toolbar, or open another dashboard window and move it yourself. Each session
appears in one window. Windows fill their readable grid capacity in order;
when every window is full, extra sessions are shared according to each
window's capacity. The toolbar shows the number of sessions in this window
and the number of sharing windows. The screen buttons follow windows moved
between screens. Closing a window returns its sessions to the others. Auto fit
refits a session in the window that receives it.

Auto fit sizes each terminal to its pane. If 80 by 24 cells cannot fit at your
chosen text size, the pane keeps exactly 80 by 24 cells and shows the whole
screen with smaller text. All visible panes below that floor in a window use
the same text size, chosen to fit the smallest space. The header keeps its
"Below 80×24 floor" note. Larger panes, such as the main pane in Focus, keep
their own fit. Text is measured afresh after each change, and returns to your
chosen size when there is room. Smaller, Larger and a remembered text size do
not prevent this temporary reduction.

Loading a font or changing display scale also refreshes the fit. With Auto fit
on, visible unheld panes, including the Focus main pane, refit their grids to
their own space unless they are following another client. This never pulls
the Focus main pane down to the shared floor. With Auto fit off, grids stay
unchanged. A grid below its column and row limits shows text no larger than
the remembered size, shrinking only as needed to show the whole screen, and
returns to that size when it fits again. A grid at its column or row limit can
still use larger text to fill its pane. The saved text choice stays unchanged.
Right-click menus stay under the pointer even at the smallest text sizes.

A held session keeps its grid. As soon as you take a session in another window
or viewer, the dashboard follows that grid until you press Fit, Enlarge or
drag that pane's track with Auto fit on. These panes show
their whole screen at the shared text size when it fits, or smaller text when
their grid needs it. They may therefore look smaller beside the 80 by 24 panes.
Wheel scrolling and the history scrollbar remain usable at the reduced size.

In Focus, drag the boundary between the large pane and its strip. In Grid,
drag a boundary between columns or rows. Focus a boundary and use the arrow
keys for small steps, Shift with an arrow for larger steps, or Home to reset
that direction. A drag stops at the readable pane size, or at the strip's
minimum width. On release, a pane that grew fits its real terminal, respecting
Auto fit's rules when it is on. A pane that shrank below the floor also fits
to 80 by 24; one still above it keeps its grid and scales its text.
With Auto fit off, release keeps the real terminal size until Fit is
pressed. The boundary announces its position in pixels. Sizes stay
in this window for the session and survive a reload. Choose Auto or Grid
again to reset them.

Double-click a pane's title bar to Enlarge or Restore it. Escape restores an
enlarged pane in navigation mode or when focus is outside the terminal;
inside the terminal, Escape goes to the program. Double-clicking inside the
terminal still selects text.
In dashboard panes, on Windows and Linux, Ctrl+V pastes; to send a literal
Ctrl+V to the program, there is no in-pane shortcut. Ctrl+C copies selected
terminal text, and sends `^C` when nothing is selected. On macOS, Cmd+V
pastes and Ctrl+V still sends `^V`.

`shellpuppet --help` documents every flag. Exit codes: 0 ok · 1 the operation
failed, such as typing into a session that has exited · 2 the request itself
was wrong, whether the CLI caught it or the daemon refused it with a 400, such
as an invalid `--regex` · 3 wait did not match, or find found nothing, so
scripts can branch on either. `find` prints each matching line as
`<row>: <text>` and nothing else on stdout; with no match it prints the fixed
line `No matches.` on stderr, never the pattern, as the MCP tool does. With
`--json` it prints the response, an empty `matches` list included, and still
exits 3 when nothing matched.

### Start ShellPuppet from the Start menu

On Windows, run `shellpuppet desktop --install` once. The per-user ShellPuppet
shortcut starts the daemon using your configured [`daemon.startWith`](docs/reference/configuration.md#daemon-start-wrapper)
when needed, then opens the dashboard. Pin the shortcut to Start or the taskbar
to start ShellPuppet with one click. You can pin the dashboard window to keep
its place, but use the shortcut to start ShellPuppet. A second click while a
dashboard page is connected reports that ShellPuppet is already open. The
shortcut starts minimised, so the console should only blink. Its target is
Node and the installed package's `dist/cli/index.js` at the package's stable
global location, which an npm update replaces in place. Run `--install` again
if you move the package to a different prefix or move or replace Node at a
different path. `--uninstall` removes only ShellPuppet's shortcut.

On Linux, `--install` writes a per-user `shellpuppet.desktop` application
launcher. On macOS, shortcut installation is not available yet. You can run
`shellpuppet desktop` from a terminal on any platform. `shellpuppet dashboard`
still opens a new isolated window on every call.

## How it works

One per-user **daemon** owns every PTY and serves the browser viewer, on
loopback only, with a token on every request bar `/health`, the viewer page
and its static assets. `/health` reveals only ok, version, pid and the daemon
instance id. The MCP server and the CLI start the daemon if it isn't
running. Every CLI verb is a one-shot HTTP client that returns promptly,
except `mcp`, which stays up for the stdio transport, and `wait`, which blocks
until its condition holds or its timeout runs out (300 s at most). Because
every client talks to the one daemon, two agents' MCP servers share one set of
sessions, and so does the human at the viewer. That is the point: sessions are
shared or they are nothing.

The build specification is
[`docs/architecture/design.md`](docs/architecture/design.md). It is
self-contained. It records what was considered and rejected, and the code
follows it.

## Day one

ShellPuppet 0.2.0 adds the dashboard. Here is what to expect from it, as of
November 2026. The [roadmap](ROADMAP.md) says what comes next, and your ideas
shape it: tell us what you'd like, and where it trips you up, in
[Discussions](https://github.com/intermeld/shellpuppet/discussions), and
report bugs in the [issues](https://github.com/intermeld/shellpuppet/issues).

- **The dashboard is new.** It holds every session as a pane, across more
  than one screen, and fits the panes to the window. Its layout has been
  driven hard on Windows with real agent CLIs; tell us where it lets you
  down on your screens.
- **Prompt detection is pattern-based.** It recognises the numbered,
  pointer-only and letter-keyed choosers and the confirmation prompts real
  agent CLIs draw, and the select, multi-select and confirm steps of
  scaffolding wizards built on `@clack/prompts`, each pinned by a fixture from
  a real screen. A shape it has not seen it will miss, and output that
  imitates one can fool it. If it misses a real prompt you meet, tell us, or
  better still, send a pull request with the fix.
- **Readiness is heuristic.** "First paint is not readiness" is in the tools
  themselves, and quiet-based waits need a first paint before silence counts;
  but a program can paint and still discard input while it finishes loading.
  Wait for its own ready text.
- **Killing can take seconds on Windows.** A Windows `kill` waits for
  `taskkill` to end the whole process tree. On the clean Windows 11 machine
  behind the install timings above it took under a second; on a busy
  development workstation it took up to about nine seconds.
- **Your MCP client may have a shorter patience than the daemon.** Waits go
  up to 300 s, but some clients background a tool call after two minutes.
  Keep long waits under your client's limit and poll.
- **Linux and macOS testers wanted.** Windows has had the most real-world
  driving so far. Linux and macOS run the full test suite on every change,
  and we'd welcome people who drive agents on them to try ShellPuppet and
  tell us how it goes.

## Documentation

| Read | For |
|---|---|
| [VISION.md](VISION.md) | What the project is for, what is open and stays open, the principles it won't trade away and where Intermeld begins. **Start here.** |
| [ROADMAP.md](ROADMAP.md) | What is being worked on now, what comes next and what is further off, without dates. |
| [`docs/architecture/design.md`](docs/architecture/design.md) | The build specification. |
| [`docs/reference/security-model.md`](docs/reference/security-model.md) | What running this grants, the token model, the limits that remain and the recorded prompt-injection drill. |
| [`docs/reference/configuration.md`](docs/reference/configuration.md) | Every `config.json` option: command policy, environment hygiene, audit, viewer launch. |
| [`docs/reference/agent-profiles.md`](docs/reference/agent-profiles.md) | Measured agent-CLI behaviour, ready-text regexes, timeout budgets, recipes. |
| [`docs/decisions/`](docs/decisions/) | Decision records: [ADR-001 naming](docs/decisions/ADR-001-two-brand-open-core-naming.md), [ADR-002 licence](docs/decisions/ADR-002-apache-2-licence.md), [ADR-003 TypeScript](docs/decisions/ADR-003-typescript-implementation.md), [ADR-004 contribution policy](docs/decisions/ADR-004-contribution-policy.md), [ADR-005 diagnostics and feedback](docs/decisions/ADR-005-diagnostics-and-feedback.md), [ADR-006 agent modules](docs/decisions/ADR-006-per-agent-modules.md), [ADR-007 connected features](docs/decisions/ADR-007-connected-features.md), [ADR-008 clean session environment](docs/decisions/ADR-008-clean-session-environment-by-default.md), [ADR-009 dashboard](docs/decisions/ADR-009-dashboard-and-sessions-you-start-yourself.md). |
| [SECURITY.md](SECURITY.md) · [SUPPORT.md](SUPPORT.md) · [CONTRIBUTING.md](CONTRIBUTING.md) | Reporting a vulnerability · getting help · building, testing and sending changes. |

## Contributing

Contributions are accepted under the Developer Certificate of Origin: sign off
each commit (`git commit -s`), and there's no contributor licence agreement,
ever ([ADR-004](docs/decisions/ADR-004-contribution-policy.md)). The sign-off
check runs on every pull request. Bug reports are welcome in the issues, and
questions, ideas and any other feedback in
[Discussions](https://github.com/intermeld/shellpuppet/discussions);
[SUPPORT.md](SUPPORT.md) says where everything goes.

## Licence

[Apache-2.0](LICENSE). See also [NOTICE](NOTICE). Code released under
Apache-2.0 stays Apache-2.0; the pledge is in
[VISION.md](VISION.md#licensing-and-contributions). The names are trademarks:
see [TRADEMARKS.md](TRADEMARKS.md).