🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
Sign In

wolfpack-bridge

Package Overview
Dependencies
Maintainers
1
Versions
50
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

wolfpack-bridge - npm Package Compare versions

Comparing version
1.6.8
 to
1.6.10
THIRD_PARTY_NOTICES

Sorry, the diff of this file is not supported yet

+144
-21
docs/agent-skills.md
# Agent Skills
Wolfpack ships optional agent skills in `skills/`. They are plain directories
that users can copy or symlink into the skill path for their agent.
Wolfpack skills are executable agent instructions stored as ordinary repository
files under `skills/`. Audit each requested `SKILL.md` before installing it.
The repository, not a compiled executable, is the source of truth.
Bundled skills:
Bundled skill:
- `wolfpack-plan` - plan-file task header conventions Ralph can parse.
- `wolfpack-ralph` - Ralph response-file contract, notifications, and sandbox
caveats.
- `wolfpack-tailnet-control` - safe local/Tailscale session inspection and
explicitly authorized control workflows.
- `wolfpack-tailnet-control` - top-level session creation, same-harness child
spawning, and safe local/Tailscale session inspection/control workflows.
The npm package includes `skills/` so `bunx wolfpack-bridge` and installed
packages expose the same skill text as the repository. Platform binary packages
only contain executables.
## Pi opt-in setup
For shared skill directories, prefer symlinking each desired Wolfpack skill
directory into the agent-specific skill root. Updating Wolfpack then updates
the source skill content without hardcoded local paths. If your agent copies
skills instead of symlinking, refresh the copied directories after upgrading
Wolfpack.
`wolfpack setup` checks for `pi` on `PATH`. Pi users receive one default-no,
opt-in offer for the complete subagent integration; users without Pi receive no
offer. Accepting runs Pi's package manager with these commands in order:
The control skill intentionally references `README.md`, related skills, and
`docs/broker-protocol.md` only for the server-broker wire contract. It does not
treat broker protocol docs as the browser `/ws/pty` attach/take-control contract.
Keep the referenced docs authoritative for their own API/auth boundaries rather
than duplicating protocol details in skill text.
```bash
pi install npm:wolfpack-bridge
pi install npm:@sgtbeatdown/pi-tasks
```
The packages and resources have distinct ownership:
| Owner | Resource | Responsibility |
| --- | --- | --- |
| Wolfpack | `wolfpack-tailnet-control` | Creates and controls visible Wolfpack sessions through the canonical CLI. |
| Pi Tasks extension | `agent_task_*` | Delivers assignments and stores structured task status/results; it does not spawn sessions. |
| Pi Tasks skill | `wolfpack-pi-task-delegation` | Teaches Pi how to combine the session-control skill with task dispatch, completion, and parent-owned cleanup. |
`npm:wolfpack-bridge` exposes the bundled Wolfpack skills to Pi.
`npm:@sgtbeatdown/pi-tasks` contains both the extension and its matching
delegation skill, so those two stay version-aligned. Every participating Pi
session needs Pi Tasks loaded. Its default filesystem task store also requires
parent and child sessions to use the same project directory; cross-repository or
multi-host task state needs a shared store.
Declining changes nothing. Non-interactive setup installs nothing and prints the
two commands only when Pi is detected. Package extensions and skills can execute
commands with the user's permissions, so review them before opting in. Start a
fresh agent context afterward, or run `/reload` in an existing Pi session.
## Clone or update the auditable source
Use a dedicated clone. Updating is fast-forward-only so this workflow does not
silently create a merge:
```bash
REPO="$HOME/src/wolfpack"
if [ -d "$REPO/.git" ]; then
git -C "$REPO" pull --ff-only
else
git clone https://github.com/almogdepaz/wolfpack "$REPO"
fi
```
Before installing the control skill, review its complete instruction file:
```bash
less "$REPO/skills/wolfpack-tailnet-control/SKILL.md"
```
Skills can direct an agent to run commands. Do not skip this audit merely
because the source came from the Wolfpack repository.
## Install one reviewed skill
Supported global roots relevant to Wolfpack are:
- Pi global: `~/.pi/agent/skills/`
- shared Agent Skills root supported by Pi: `~/.agents/skills/`
- Claude global where used: `~/.claude/skills/`
For shared skill directories, prefer symlinking each desired Wolfpack skill so
a later reviewed `git pull --ff-only` updates the installed source. Choose one
root; this example uses Pi global:
```bash
REPO="$HOME/src/wolfpack"
SOURCE="$REPO/skills/wolfpack-tailnet-control"
DEST_ROOT="$HOME/.pi/agent/skills"
DEST="$DEST_ROOT/wolfpack-tailnet-control"
[ -d "$SOURCE" ] || {
printf 'skill source not found: %s\n' "$SOURCE" >&2
exit 1
}
mkdir -p "$DEST_ROOT"
[ ! -e "$DEST" ] && [ ! -L "$DEST" ] || {
printf 'refusing to replace existing skill: %s\n' "$DEST" >&2
exit 1
}
ln -s "$SOURCE" "$DEST"
```
To target the shared Pi-compatible root or Claude global root, set `DEST_ROOT`
to `$HOME/.agents/skills` or `$HOME/.claude/skills` before running the same
existence checks. Never force the link or overwrite an existing destination.
Copying is an alternative for agents or environments that cannot follow
symlinks. It uses the same fail-closed destination check:
```bash
REPO="$HOME/src/wolfpack"
SOURCE="$REPO/skills/wolfpack-tailnet-control"
DEST_ROOT="$HOME/.pi/agent/skills"
DEST="$DEST_ROOT/wolfpack-tailnet-control"
[ -d "$SOURCE" ] || {
printf 'skill source not found: %s\n' "$SOURCE" >&2
exit 1
}
mkdir -p "$DEST_ROOT"
[ ! -e "$DEST" ] && [ ! -L "$DEST" ] || {
printf 'refusing to replace existing skill: %s\n' "$DEST" >&2
exit 1
}
cp -R "$SOURCE" "$DEST"
```
A copied skill must be refreshed manually after reviewing repository updates.
In either case, start a fresh agent context so skill descriptions are rescanned.
## Invoke the control skill
For a top-level project session:
```bash
wolfpack session create <project> --harness pi --plan .plans/000-task.md --json
```
For a same-harness child of the current agent:
```bash
wolfpack agent spawn <project> --name 200-implementation --plan .plans/000-task.md --notify-parent --json
```
Use `--name` to pick a short issue/role slug, `--plan` for plan work, and
`--prompt-file` for long bespoke instructions; avoid pasting full plans or repository policy into the launch command. The
control skill documents the tailnet/global auth boundary and references
canonical session-control and identity docs instead of duplicating those
contracts.
## Distribution boundary
The npm package includes `skills/` so users inspecting that package can read the
same repository files. Platform binary packages only contain executables;
platform binaries do not contain skills. After explicit opt-in, the setup wizard
delegates package installation to Pi instead of embedding skill payloads,
editing Pi settings, or overwriting skill directories. The cloned repository
remains the auditable source of truth for manual installation.
+85
-29
docs/session-control.md
# Session Control CLI/API
Wolfpack exposes a small scriptable surface for agent automation. The server
stays authoritative for auth, session validation, and broker access; the CLI
only calls the local authenticated HTTP API except for `current-context`, which
reads Wolfpack-provided environment variables in an agent process.
Wolfpack exposes a scriptable session surface for agents and operators. The server remains authoritative for auth, project containment, session naming, stable broker identity, and PTY operations. Commands use Wolfpack's ordinary global API auth policy and add no inter-session authorization layer.
## Command Surface
## Create a top-level session
- `wolfpack session read <session> [--json]`
- prints the current broker snapshot for a live session.
- json: `{ "session": string, "output": string }`
- `wolfpack session send <session> <text...> [--no-enter] [--json]`
- sends text through the server to the broker input plane.
- appends Enter unless `--no-enter` is set.
- json: `{ "ok": true, "session": string }`
- `wolfpack session wait <session> <text> [--timeout-ms <ms>] [--json]`
- waits for literal UTF-8 output text in the broker output stream.
- checks the current snapshot first, then subscribes to structured broker
output frames until timeout.
- json: `{ "ok": true, "session": string, "matched": true }`
- `wolfpack session current-context [--json|--shell]`
- reports only context Wolfpack injected into the current process:
`WOLFPACK_SESSION_NAME` and `WOLFPACK_PROJECT_DIR`.
- it never guesses a target from terminal text or process ancestry.
```bash
wolfpack session create <project> [--harness <agent>] [--prompt|--prompt-file|--plan <value>] [--json]
```
`split` is deliberately not part of this surface. Wolfpack grid/layout state is
browser-owned today, and adding a CLI layout command would create a second
authority path.
- performs one `POST /api/session-create` request.
- requires an exact existing project under `WOLFPACK_DEV_DIR`.
- selects the configured default command when `--harness` is omitted.
- accepts `pi`, `claude`, `codex`, `gemini`, or `cursor` as explicit harnesses.
- allocates `<project>`, then `<project>-2`, `<project>-3`, and so on with bounded collision retries.
- passes one explicit prompt as an opaque argv value when the harness starts; no terminal-readiness send race is involved.
- `--prompt-file <file>` reads instruction text from disk to avoid shell heredoc/quoting failures.
- `--plan <file>` verifies the file exists and generates a compact "read and implement this plan" startup prompt without copying plan contents.
- rejects prompts when the effective command is a plain shell.
- json success: `{ "ok": true, "session": string, "sessionId": string, "project": string, "harness": string }`.
## Exit Codes
## Spawn a child agent
```bash
wolfpack agent spawn <project> [--name <session>] [--prompt|--prompt-file|--plan <value>] [--notify-parent] [--json]
```
- performs one `POST /api/session-open` request.
- requires `WOLFPACK_SESSION_NAME` and `WOLFPACK_AGENT_KIND` from the current parent agent.
- resolves the parent through structured broker identity and launches the same supported harness.
- accepts `--name <session>` for meaningful child names such as `200-security-review`; if omitted, derives `<parent>-sub-agent`, then numbered names.
- passes only explicit startup instructions; it does not inherit the parent transcript, model context, or summary.
- supports `--plan <file>` and `--prompt-file <file>` like top-level creation.
- `--notify-parent` adds a compact child instruction to call `wolfpack agent notify-parent` when done or blocked.
- stores structured parent ID/name metadata and sends a best-effort typed browser notification when opened.
- json success has the same fields as top-level creation, including stable `sessionId`.
`wolfpack session open` remains a deprecated compatibility alias for `wolfpack agent spawn`. It never means top-level creation.
## Keep handoffs short
For plan work, prefer the compact generator:
```bash
wolfpack agent spawn <project> --name 200-implementation --plan .plans/000-task.md --notify-parent --json
```
Put durable instructions in the repository plan. Pick a short issue/role slug for `--name` so the delegation graph stays readable. Do not duplicate the plan, source inventory, testing policy, and architecture in every launch prompt. For bespoke long text, write it to a file and use `--prompt-file`.
## List and inspect without terminal scraping
```bash
wolfpack list --json
wolfpack session status <session-or-id> [--json]
wolfpack session read <session-or-id> [--json]
```
- `list --json` uses the lightweight `/api/session-control/list` route and returns active structured identities as one JSON envelope, without terminal previews.
- `status` returns canonical name, stable ID, active state, project path, `projectDir` alias, project name, harness, optional parent identity, and bounded `terminal` liveness (`ready | dead | unavailable`). Dead targets return `SESSION_DEAD`; unknown, ambiguous, and backend-unavailable targets use the same structured failure envelope. It does not capture terminal output.
- `read` is the explicit full broker-snapshot operation.
- names remain accepted for humans; automation should retain and use `sessionId` returned by create, spawn, list, or status.
- selectors that ambiguously match a name and another session's ID fail closed.
- Pi/agent task layers may use `session status <selector> --json` only as Wolfpack-owned target evidence: selector resolution, broker/session existence, stable identity, project path, harness, and terminal liveness. They must not infer Pi model readiness, task completion, or agent state from Wolfpack status.
## Send and wait
```bash
wolfpack session send <session-or-id> <text...> [--no-enter] [--json]
wolfpack session wait <session-or-id> <text> [--timeout-ms <1..600000>] [--json]
wolfpack session prompt <session-or-id> <prompt...> --until <text> [--no-enter] [--timeout-ms <1..600000>] [--json]
```
- `send` writes through the broker input plane and appends Enter unless `--no-enter` is set.
- `wait` checks the current snapshot, then subscribes from its sequence number with a bounded buffer and timeout.
- `prompt` performs one `POST /api/session-control/prompt` request. The server resolves the selector once, pins the returned `sessionId`, registers broker output observation, waits for subscription readiness, records `outputBoundarySeq`, and only then writes input to that stable ID.
- `prompt --until` is explicitly an `output contains` terminal primitive. It does not infer agent or task completion. Typed agent-state and delegated-task predicates remain deferred to #209 and #211.
- prompt outcomes are `matched`, `timed_out`, `target_exited`, `target_unavailable`, `target_replaced`, `replay_gap`, or `backend_unavailable`. The bounded JSON envelope always includes canonical `session`, stable `sessionId`, `outcome`, and nullable `outputBoundarySeq`.
- `target_replaced` means the pinned stable ID disappeared while its resolved session name now maps to a different stable ID; callers must re-resolve explicitly before retrying.
- typed agent-state/delegated-task predicates and explicit cancellation are still deferred until #211 provides the structured event/cursor substrate; `prompt --until` remains output-contains only.
- JSON responses from standalone send/wait retain their existing shape for backward compatibility.
`wolfpack agent notify-parent [--message <text>] [--json]` wraps `POST /api/notify`; it is intended for child agents launched with `--notify-parent`.
`wolfpack session current-context [--json|--shell]` reports only Wolfpack-injected name/project context. It never infers identity from process names or terminal prose.
## Exit codes
- `0`: success
- `1`: unexpected server/API failure
- `2`: command usage error
- `3`: missing or unknown session/context
- `1`: unexpected API failure or ambiguous selector
- `2`: usage error
- `3`: missing/unknown project, session, or context
- `4`: wait timeout
- `5`: auth failure
- `6`: backend/broker unavailable
- `6`: backend unavailable
Grid/layout ownership remains in the browser. Session commands never reconstruct browser state from terminal output.
+2
-3
llms.txt

@@ -23,3 +23,2 @@ # Wolfpack

- Multi-machine session list and desktop terminal grid
- Optional Ralph autonomous plan runner

@@ -31,4 +30,4 @@ ## Important docs

- docs/broker-protocol.md: broker wire protocol
- docs/ralph-macchio.md: Ralph autonomous plan runner
- docs/ralph-behavior.md: Ralph behavior notes
- docs/session-control.md: scriptable session control API
- docs/cli-attach.md: local terminal attach

@@ -35,0 +34,0 @@ ## Install

+10
-6
package.json
{
"name": "wolfpack-bridge",
"version": "1.6.8",
"version": "1.6.10",
"type": "module",

@@ -16,2 +16,3 @@ "description": "Self-hosted browser terminal manager for AI coding agents on your own machines",

"bin/install.cjs",
"THIRD_PARTY_NOTICES",
"llms.txt",

@@ -29,10 +30,10 @@ "docs/agent-skills.md",

"perf:terminal-load": "bun scripts/terminal-load-perf.ts",
"typecheck": "bunx tsc --noEmit -p . && bunx tsc --noEmit -p public/",
"typecheck": "bunx tsc --noEmit -p . && bunx tsc --noEmit -p public/ && bunx tsc --noEmit -p public/tsconfig.strict.json",
"postinstall": "node bin/install.cjs"
},
"optionalDependencies": {
"wolfpack-bridge-darwin-arm64": "1.6.8",
"wolfpack-bridge-darwin-x64": "1.6.8",
"wolfpack-bridge-linux-arm64": "1.6.8",
"wolfpack-bridge-linux-x64": "1.6.8"
"wolfpack-bridge-darwin-arm64": "1.6.10",
"wolfpack-bridge-darwin-x64": "1.6.10",
"wolfpack-bridge-linux-arm64": "1.6.10",
"wolfpack-bridge-linux-x64": "1.6.10"
},

@@ -79,3 +80,6 @@ "keywords": [

"typescript": "^6.0.3"
},
"patchedDependencies": {
"ghostty-web@0.4.0": "patches/ghostty-web@0.4.0.patch"
}
}
+84
-13
README.md

@@ -15,7 +15,14 @@ # Wolfpack — browser terminal manager for AI coding agents

<p align="center">
<img src="docs/desktop-grid.png" width="700" alt="Desktop — multi-terminal grid view" />
<img src="docs/assets/wolfpack-desktop-grid.png" width="700" alt="Desktop — multi-terminal grid" />
</p>
<p align="center">
<img src="docs/mobile-sessions.png" width="250" alt="Mobile — session list across machines" />
<img src="docs/assets/wolfpack-mobile-menu.jpeg" width="250" alt="Mobile — session menu" />
<img src="docs/assets/wolfpack-mobile-terminal.jpeg" width="250" alt="Mobile — terminal session" />
</p>
<p align="center">
<img src="docs/assets/wolfpack-usage-demo.gif" width="700" alt="Wolfpack usage demo showing real broker-backed terminal sessions" />
</p>
<p align="center">
<a href="docs/assets/wolfpack-usage-demo.mp4">Watch/download the MP4 demo</a>
</p>

@@ -29,3 +36,3 @@ ## Quickstart

The installer downloads the right pre-built binaries for your platform, runs setup, and can install Wolfpack as a login service.
The installer downloads the right pre-built binaries for your platform, runs setup, and can install Wolfpack as a login service. The bundled `wolfpack-broker` includes its Ghostty VT engine; release installs do not need Zig, Ghostty, or extra system libraries.
Supported: macOS arm64/x64 and Linux x64/arm64.

@@ -56,3 +63,3 @@

1. Run the installer.
2. Choose your projects directory and port.
2. Choose your projects directory and port. On a fresh install, setup enables `shell` plus supported providers detected on `PATH`; existing agent settings are never overwritten.
3. Let setup detect your Tailscale hostname and configure `tailscale serve` for HTTPS remote access.

@@ -77,3 +84,3 @@ 4. Install the service when prompted if you want Wolfpack to survive login/reboots.

- **Agent-agnostic** — use built-in commands or add your own shell command in Settings → Agents.
- **Ralph loop** — optional autonomous plan runner. See [docs/ralph-macchio.md](docs/ralph-macchio.md).
- **Provider readiness** — First-run setup enables detected supported CLIs; Settings → Agents shows path/version and login guidance and lets you add providers installed later.

@@ -91,2 +98,4 @@ ## Agent recipes

| Gemini | `gemini` |
| Cursor | `cursor` |
| Pi | `pi` |
| Custom wrapper | any command on `PATH`, for example `opencode` or `my-agent --flag` |

@@ -101,6 +110,9 @@

wolfpack setup Re-run the setup wizard
wolfpack ls List active broker sessions
wolfpack list [--json] List active broker sessions
wolfpack session create Create a top-level project session
wolfpack agent spawn Spawn a same-harness child agent
wolfpack session ... Status/read/send/wait/prompt helpers for agent automation
wolfpack attach [name] Attach the local terminal to an existing session
wolfpack kill <name> Kill a session
wolfpack session ... Scriptable read/send/wait helpers for automation
wolfpack kill <name|id> Kill a session
wolfpack --version Print the installed version
wolfpack doctor Diagnose broker, binaries, JWT, Tailscale

@@ -111,2 +123,16 @@ wolfpack service ... install / start / stop / restart / status / uninstall (add --broker to include broker)

Create a top-level project session with its initial instruction delivered at launch:
```bash
wolfpack session create branchout --harness pi --plan .plans/000-task.md --json
```
Spawn a same-harness child from an existing Wolfpack agent:
```bash
wolfpack agent spawn wolfpack --plan .plans/000-review.md --notify-parent --json
```
Each command makes one server-owned request and returns the stable broker `sessionId`. The server validates the project, allocates the name, persists identity, and passes startup instructions directly to the harness instead of racing terminal readiness. `--plan` generates a compact plan handoff without copying plan contents; `--prompt-file` avoids shell heredoc/quoting failures for bespoke long prompts. Child spawning derives the parent harness and structured hierarchy without inheriting its transcript or context. `wolfpack session open` remains a deprecated child-spawn alias.
Direct terminal attach: [docs/cli-attach.md](docs/cli-attach.md). Scriptable session control: [docs/session-control.md](docs/session-control.md).

@@ -125,2 +151,3 @@

- Optional JWT auth can be layered on top of Tailscale.
- Session control follows the ordinary global API auth policy when configured and adds no inter-session authorization layer. Tailnet/global Wolfpack access remains the trust boundary; sessions can list and communicate with other sessions.
- Wolfpack does not provide a hosted relay, managed account, or prompt upload service.

@@ -148,3 +175,3 @@

- **Server** — Bun HTTP + WebSocket. Pure broker client; owns no PTYs.
- **Broker** — `wolfpack-broker`, Rust daemon. Owns every PTY, keeps per-session output rings. One Unix-domain socket per host (`$XDG_RUNTIME_DIR/wolfpack-broker.sock`, fallback `~/.wolfpack/broker.sock`). Wire protocol in [docs/broker-protocol.md](docs/broker-protocol.md).
- **Broker** — `wolfpack-broker`, Rust daemon. Owns every PTY, keeps per-session output rings, and uses a statically linked Ghostty VT engine for authoritative terminal state/snapshots. One Unix-domain socket per host (`$XDG_RUNTIME_DIR/wolfpack-broker.sock`, fallback `~/.wolfpack/broker.sock`). Wire protocol in [docs/broker-protocol.md](docs/broker-protocol.md).

@@ -179,10 +206,54 @@ ## Optional JWT auth

Wolfpack exposes repository-local agent skills in `skills/`:
Wolfpack exposes one repository-local agent skill in `skills/`:
- `wolfpack-plan` — plan-file task header conventions that Ralph can parse.
- `wolfpack-ralph` — Ralph loop response contract, notifications, and sandbox/socket caveats.
- `wolfpack-tailnet-control` — discover, inspect, and control Wolfpack terminal sessions across Tailscale hosts.
Copy or symlink these skill directories into an agent's skill path when you want that agent to opt in. Installation/update details: [docs/agent-skills.md](docs/agent-skills.md).
### Pi subagent integration
When setup detects `pi` on `PATH`, it offers one default-no, opt-in installation.
Accepting uses Pi's package manager to install the complete integration:
```bash
pi install npm:wolfpack-bridge
pi install npm:@sgtbeatdown/pi-tasks
```
The pieces have separate jobs:
| Owner | Resource | Responsibility |
| --- | --- | --- |
| Wolfpack | `wolfpack-tailnet-control` | Creates, selects, inspects, and closes visible Wolfpack sessions. |
| Pi Tasks extension | `agent_task_*` | Sends assignments and records durable structured status/results; it does not create sessions. |
| Pi Tasks skill | `wolfpack-pi-task-delegation` | Teaches Pi to combine Wolfpack session control with the task tools and completion protocol. |
The first package exposes Wolfpack's bundled skills to Pi. The second package
contains both the Pi Tasks extension and its matching delegation skill. Every
participating Pi session needs Pi Tasks loaded; its default filesystem store
also requires parent and child sessions to use the same project directory.
Declining the setup prompt changes nothing. Non-interactive setup never installs
Pi packages and prints the commands instead.
Skills and extensions can execute commands with your user permissions. Review
the packages before accepting. Start a fresh Pi session afterward, or run
`/reload` in an existing session.
### Manual skill installation
Skills are executable agent instructions, so install only the ones you have audited. Clone or update `https://github.com/almogdepaz/wolfpack`, review the requested file (for example `skills/wolfpack-tailnet-control/SKILL.md`), then symlink that skill directory into one supported root:
- Pi global: `~/.pi/agent/skills/`
- shared Agent Skills root supported by Pi: `~/.agents/skills/`
- Claude global where used: `~/.claude/skills/`
Prefer symlinks so a reviewed `git pull --ff-only` updates the source. Refuse installation when the destination already exists; copying is also supported but must be refreshed manually. Start a fresh agent context afterward so skill descriptions are rescanned. Full fail-safe commands: [docs/agent-skills.md](docs/agent-skills.md).
For a top-level session or a same-harness child, invoke:
```bash
wolfpack session create <project> --harness pi --plan .plans/000-task.md --json
wolfpack agent spawn <project> --plan .plans/000-task.md --notify-parent --json
```
Platform binaries do not contain skills. The setup wizard only asks Pi's package manager to install them after explicit opt-in; the cloned repository remains the auditable source for manual installation.
## Contributing

@@ -189,0 +260,0 @@ 

+25
-151
skills/wolfpack-tailnet-control/SKILL.md
---
name: wolfpack-tailnet-control
description: Use when an agent needs safe, user-authorized inspection or control of Wolfpack terminal sessions on local or Tailscale-reachable hosts.
description: Create top-level Wolfpack sessions, spawn child agents, and inspect or control local/Tailscale sessions through the canonical CLI.
---
# Wolfpack Tailnet Session Control
# Wolfpack Session Control
Use this skill for safe Wolfpack session inspection and control. Wolfpack access
is shell access to the target machine; prefer read-only inspection until the
user explicitly asks for input/control.
Use the canonical CLI. Do not discover or reconstruct browser/private HTTP flows.
Wolfpack uses its ordinary global API auth policy and adds no inter-session authorization layer.
## Existing References
## Fast path
- User setup, Tailscale, and JWT auth model: `README.md`
- Broker/session authority and server-broker wire protocol: `docs/broker-protocol.md`
- Ralph runner response and sandbox caveats: `skills/wolfpack-ralph/SKILL.md`
- Troubleshooting local service/config failures: `docs/troubleshooting.md`
A **top-level** project session:
Do not copy protocol details from those docs into task output. Link or cite the
doc and use the structured CLI/API commands below.
## Current Context
Prefer explicit context from the user, runner, or environment over discovery.
Treat session selectors as opaque handles; do not parse human-readable terminal
text, card labels, previews, or UI prose to infer protocol state.
Supported current-context variables:
```bash
WOLFPACK_BASE_URL="http://127.0.0.1:18790"
WOLFPACK_CURRENT_MACHINE_URL="https://machine.tailnet.ts.net"
WOLFPACK_CURRENT_SESSION_ID="session-handle"
WOLFPACK_AUTH_TOKEN="optional-jwt"
wolfpack session create <project> --harness <pi|claude|codex|gemini|cursor> --prompt '<instruction>' --json
```
Use `WOLFPACK_CURRENT_MACHINE_URL` when the task is explicitly about a remote
machine; otherwise use `WOLFPACK_BASE_URL`. If neither is present, inspect local
config only enough to build a base URL.
A same-harness **child** of the current agent:
## Allowed Workflows
Allowed without additional confirmation when the user asks you to inspect:
- Inspect current context: identify base URL, auth token presence, and current
session handle.
- Discover/list sessions with the HTTP API or `wolfpack ls`.
- Read a session pane or copy-text output.
- Check session git status.
- Wait/poll for state changes by repeating read-only API calls.
- Ask for attach/control guidance when the task requires live interaction.
Requires explicit user intent for the exact target/session/action:
- Send input to a session.
- Take control from another viewer.
- Create, kill, resize, or otherwise change sessions.
- Open remote hosts or expose service/network configuration.
- Trigger user-visible notifications.
Forbidden:
- Scraping browser UI prose, terminal prompts, logs, or error text as a
protocol when structured CLI/API data exists.
- Guessing auth tokens, reading unrelated secret files, or bypassing JWT auth.
- Treating a display name as stable identity if an opaque current-context
handle is available.
- Killing or taking over sessions as cleanup unless the user asked.
## Auth and Base URL
Build helpers in shell examples:
```bash
BASE="${WOLFPACK_CURRENT_MACHINE_URL:-${WOLFPACK_BASE_URL:-http://127.0.0.1:18790}}"
SESSION="${WOLFPACK_CURRENT_SESSION_ID:-}"
AUTH_ARGS=()
if [ -n "${WOLFPACK_AUTH_TOKEN:-}" ]; then
AUTH_ARGS=(-H "Authorization: Bearer ${WOLFPACK_AUTH_TOKEN}")
fi
wolfpack agent spawn <project> --name 200-implementation --plan .plans/000-task.md --notify-parent --json
```
Missing context handling:
`wolfpack session open` is only a deprecated child-spawn alias. Never use it for a top-level request.
Both creation commands perform one server-owned request and pass startup instructions without inheriting parent transcript/context.
- Missing `BASE`: read `~/.wolfpack/config.json` for `port` and
`tailscaleHostname`; if the file is absent, ask the user which host to use.
- Missing `SESSION`: list sessions and ask the user which one to target unless
the task already names one.
- HTTP 401/403: stop and ask for `WOLFPACK_AUTH_TOKEN` or user-side auth setup.
- Tailscale/DNS failure: ask the user to verify Tailscale and `tailscale serve`;
do not fall back to public-network exposure.
Use `--name <session>` for child agents and choose a short meaningful issue/role slug, for example `200-implementation`, `200-delivery-review`, or `auth-boundary-audit`. Avoid generic `*-sub-agent` names when the task purpose is known; Wolfpack will allocate a numbered suffix if the requested name is already taken. Prefer `--plan <file>` for plan work: Wolfpack generates the compact handoff prompt and verifies the file exists without copying plan contents into the parent transcript. Use `--prompt-file <file>` for long bespoke instructions. Use raw `--prompt` only for one short prompt sentence. Do NOT paste repository policy, architecture context, or full plans into the launch command.
## Read-Only Examples
## Structured inspection and control
List sessions:
```bash
curl -fsS "${AUTH_ARGS[@]}" "$BASE/api/sessions" | jq .
wolfpack list --json
wolfpack session status <session-or-id> --json
wolfpack session read <session-or-id> --json
wolfpack session send <session-or-id> '<text>' --json
wolfpack session wait <session-or-id> '<text>' --json
```
Read the current session pane:
Treat session selectors as opaque handles. Prefer the stable `sessionId` returned by create/spawn/list/status. If the user already supplied an exact target, do not list first.
```bash
test -n "$SESSION" || { echo "missing WOLFPACK_CURRENT_SESSION_ID" >&2; exit 2; }
curl -fsS "${AUTH_ARGS[@]}" \
"$BASE/api/poll?session=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "$SESSION")" \
| jq -r .pane
```
Read-only inspection is allowed when requested. Creation, sending input, killing, taking control, remote-host access, and notifications require explicit user intent for that action and target. Never scrape terminal/UI prose as protocol, bypass auth, guess tokens, or kill a mistaken session as cleanup without permission.
Fetch plain text for copy/debugging:
## References — load only when needed
```bash
test -n "$SESSION" || { echo "missing WOLFPACK_CURRENT_SESSION_ID" >&2; exit 2; }
curl -fsS "${AUTH_ARGS[@]}" \
"$BASE/api/copy-text?session=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "$SESSION")"
```
Check git status for the session project:
```bash
test -n "$SESSION" || { echo "missing WOLFPACK_CURRENT_SESSION_ID" >&2; exit 2; }
curl -fsS "${AUTH_ARGS[@]}" \
"$BASE/api/git-status?session=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "$SESSION")" \
| jq -r .status
```
Wait for idle-ish stability with structured polling:
```bash
for _ in 1 2 3 4 5; do
curl -fsS "${AUTH_ARGS[@]}" "$BASE/api/sessions" | jq .
sleep 2
done
```
## User-Visible Control Examples
Only run these after the user asked for the exact action.
Create a session in an existing project under the host's configured dev dir:
```bash
curl -fsS "${AUTH_ARGS[@]}" "$BASE/api/create" \
-H 'Content-Type: application/json' \
-d '{"project":"repo-name","cmd":"codex","sessionName":"repo-name-codex"}' | jq .
```
Kill a session:
```bash
test -n "$SESSION" || { echo "missing WOLFPACK_CURRENT_SESSION_ID" >&2; exit 2; }
curl -fsS "${AUTH_ARGS[@]}" "$BASE/api/kill" \
-H 'Content-Type: application/json' \
-d "$(jq -nc --arg session "$SESSION" '{session:$session}')" | jq .
```
For interactive attach/take-control automation, prefer the Wolfpack UI first.
Do not use `docs/broker-protocol.md` as a browser attach contract; it documents
the server-broker wire protocol, not `/ws/pty` viewer conflict, take-control,
prefill, or browser token-query behavior. If low-level browser attach automation
is explicitly required, inspect the current server/client implementation and
attach tests instead of guessing from the broker protocol. Browser-style
WebSocket clients that cannot set headers may pass `token=<jwt>` in the query
string; keep tokens out of logs.
## Notify the User
Only notify when the user asked or when the active task cannot proceed without
human input:
```bash
curl -fsS "${AUTH_ARGS[@]}" "$BASE/api/notify" \
-H 'Content-Type: application/json' \
-d '{"message":"agent needs input"}'
```
- command/API behavior: `docs/session-control.md`
- setup, auth, and Tailscale: `README.md`
- troubleshooting: `docs/troubleshooting.md`
- broker internals only when changing transport: `docs/broker-protocol.md`
-10
skills/wolfpack-plan/SKILL.md
---
name: wolfpack-plan
description: Context injected into interactive claude sessions via --append-system-prompt. Defines the plan-file header conventions the task extractor recognizes. Loaded by src/wolfpack-context.ts.
---
## Wolfpack Plan Conventions
Plan task headers MUST use: `## N. Title` (e.g. `## 1. Add auth`), subtasks: `## Na. Title` (e.g. `## 1a. Tests`). Completed: wrap in `~~` (e.g. `## ~~1. Done~~`). No other header styles — the task extractor only recognizes this pattern.
Each task = a meaningful deliverable (3-5 per feature). NOT individual lines of code — a unit of work a senior dev would recognize. Subtask breakdowns follow the same rule: 3-5 max, each coherent.
-41
skills/wolfpack-ralph/SKILL.md
---
name: wolfpack-ralph
description: Optional Ralph skill context for agents/users who install it. Defines the structured response expectations and user-notification endpoint; Wolfpack does not runtime-inject this skill into prompts.
---
## Ralph Agent Context
Before exiting, write the structured JSON response file requested by the runner prompt. The response file is the ONLY runner control channel for every supported agent; do not emit XML-ish control tags in stdout.
When a task is too large to implement directly, do not make code changes. Write a response with `"status": "needs_subtasks"` and `"subtasks"` as an array of meaningful deliverables:
```json
{
"version": 1,
"status": "needs_subtasks",
"prereqs": ["assumption or prerequisite"],
"tests": ["test command or planned test"],
"done": ["completion criterion"],
"subtasks": [
"Implement auth middleware with JWT validation",
"Add integration tests for auth endpoints"
]
}
```
Each subtask = a meaningful deliverable (3-5 per breakdown). NOT single lines of code or imports — a unit of work a senior dev would recognize as coherent.
To notify the user (push notification to their phone/desktop):
curl -s http://localhost:18790/api/notify -H 'Content-Type: application/json' -d '{"message": "your message"}'
## Srt Sandbox and Local Sockets
Default Ralph srt is intentionally restrictive. Do not plan default-srt work that requires starting local listeners unless the plan explicitly includes a host/non-srt verification phase.
Known default-srt blockers:
- Unix domain socket bind/listen, including starting `wolfpack-broker` inside srt.
- Localhost TCP bind/listen unless a socket-capable profile explicitly enables local binding.
- Broker-backed perf/integration tests that spawn their own broker process.
Preferred handling:
- Normal Ralph tasks must not access Wolfpack's host broker socket from inside srt; broker socket access is equivalent to host PTY control.
- For broker startup tests, perf harnesses, browser/dev servers, or anything that must bind/listen locally, run that step with `--sandbox false` or ask for an explicit socket-capable srt profile.
- Do not enable `allowAllUnixSockets` in default Ralph runs. If a task truly needs Unix sockets inside srt, scope `network.allowUnixSockets` to the exact socket path/dir and ensure the socket directory is writable only when bind/listen is required.