portzilla 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +148 -280
- package/package.json +2 -1
- package/skills/portzilla/SKILL.md +29 -0
package/README.md
CHANGED
|
@@ -1,368 +1,236 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="logo.png" alt="Portzilla" width="360">
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
<h1 align="center">portzilla</h1>
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
<p align="center">
|
|
8
|
+
<strong>Lease registry for localhost ports — stop killing your sibling's dev server.</strong>
|
|
9
|
+
</p>
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
<p align="center">
|
|
12
|
+
<a href="https://github.com/011010/portzilla/actions/workflows/ci.yml"><img src="https://github.com/011010/portzilla/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
13
|
+
<a href="https://crates.io/crates/portzilla"><img src="https://img.shields.io/crates/v/portzilla" alt="crates.io"></a>
|
|
14
|
+
<a href="https://www.npmjs.com/package/portzilla"><img src="https://img.shields.io/npm/v/portzilla" alt="npm"></a>
|
|
15
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
|
|
16
|
+
</p>
|
|
8
17
|
|
|
9
|
-
|
|
18
|
+
> AI coding agents (Claude Code, Cursor, etc.) run parallel sessions in git worktrees — each starting its own dev server. Today they coordinate by killing whatever is on a port. `portzilla` is the layer that **prevents the conflict**.
|
|
10
19
|
|
|
11
|
-
|
|
20
|
+
- **Claim, don't kill** — `portzilla claim 3000 --tag next-dev` gives you a port with owner PID + purpose tag. Conflicts and already-bound ports get the next available port instead of stealing.
|
|
21
|
+
- **Ask before you kill** — `portzilla who 3000` tells you who owns a port. JSON everywhere so agents can consume it directly.
|
|
22
|
+
- **Guard by default** — intercepts `kill`, `lsof | xargs kill`, `fuser -k`, `kill-port` and blocks kills against another session's live lease.
|
|
23
|
+
|
|
24
|
+
Port allocators and proxies such as [Portless](https://portless.sh) solve addressability and automatic port selection. `portzilla` focuses on a different boundary: declaring which agent session owns a process and preventing another agent from killing it. It stays daemon-less by default, requires no local proxy or CA, and works with any server command that consumes the assigned port.
|
|
25
|
+
|
|
26
|
+

|
|
27
|
+
|
|
28
|
+
## Contents
|
|
29
|
+
|
|
30
|
+
- [Quick start](#quick-start)
|
|
31
|
+
- [Demo](#demo)
|
|
32
|
+
- [Install](#install)
|
|
33
|
+
- [Commands](#commands)
|
|
34
|
+
- [Agent skill](#agent-skill)
|
|
35
|
+
- [Watch mode](#watch-mode)
|
|
36
|
+
- [MCP server](#mcp-server)
|
|
37
|
+
- [Kill guard](#kill-guard)
|
|
38
|
+
- [Data file & config](#data-file--config)
|
|
39
|
+
- [Limitations](#limitations)
|
|
40
|
+
|
|
41
|
+
## Quick start
|
|
12
42
|
|
|
13
43
|
```console
|
|
14
|
-
$ portzilla claim 3000 --tag next-dev --
|
|
44
|
+
$ portzilla claim 3000 --tag next-dev --session "$CLAUDE_CODE_SESSION_ID"
|
|
15
45
|
claimed port 3000 for pid 57107 (tag: next-dev)
|
|
16
46
|
|
|
17
|
-
$ portzilla
|
|
18
|
-
port 3000
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
port: 3001
|
|
22
|
-
pid: 57108
|
|
23
|
-
tag: vite-dev
|
|
24
|
-
session: (none)
|
|
25
|
-
age: 3s
|
|
47
|
+
$ portzilla who 3000
|
|
48
|
+
port: 3000
|
|
49
|
+
pid: 57107
|
|
50
|
+
tag: next-dev
|
|
26
51
|
status: alive
|
|
27
52
|
|
|
28
|
-
$ portzilla who 3001 --json
|
|
29
|
-
{"port":3001,"pid":57108,"tag":"vite-dev","created_at":1785959877,"session":null,"age_secs":3,"alive":true}
|
|
30
|
-
|
|
31
53
|
$ portzilla ls
|
|
32
54
|
PORT PID STATUS AGE TAG
|
|
33
55
|
3000 57107 alive 5s next-dev
|
|
34
|
-
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Data-producing commands accept `--json` for agent consumption. See [CLI reference](docs/CLI.md).
|
|
59
|
+
|
|
60
|
+
Prefer `run` when starting a server — it claims the port and holds the lease for the real server process:
|
|
61
|
+
|
|
62
|
+
```console
|
|
63
|
+
$ portzilla run 3000 --tag "vite dev" -- sh -c 'npm run dev -- --port "$PORTZILLA_PORT"'
|
|
64
|
+
running on port 3000
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The exact child command is framework-specific: whatever starts your server must read the assigned port from `$PORTZILLA_PORT`. On conflict `run` reassigns to the next free port and reports it on stderr; the server child's stdout stays untouched.
|
|
68
|
+
|
|
69
|
+
## Demo
|
|
70
|
+
|
|
71
|
+
```console
|
|
72
|
+
$ portzilla claim 3000 --tag next-dev --pid 57107
|
|
73
|
+
claimed port 3000 for pid 57107 (tag: next-dev)
|
|
74
|
+
|
|
75
|
+
$ portzilla claim 3000 --tag vite-dev --pid 57108
|
|
76
|
+
port 3000 is busy (lease conflict); claimed port 3001 instead for pid 57108 (tag: vite-dev)
|
|
77
|
+
|
|
78
|
+
$ portzilla who 3001 --json
|
|
79
|
+
{"port":3001,"pid":57108,"tag":"vite-dev","created_at":1785959877,"session":null,"process_start_time":1785959876,"age_secs":3,"alive":true}
|
|
35
80
|
|
|
36
81
|
$ portzilla release 3001
|
|
37
82
|
warning: released port 3001 whose owning pid 57108 is still alive
|
|
38
83
|
port: 3001
|
|
39
84
|
pid: 57108
|
|
40
85
|
tag: vite-dev
|
|
41
|
-
session: (none)
|
|
42
|
-
age: 3s
|
|
43
86
|
status: alive
|
|
44
87
|
|
|
45
88
|
$ portzilla prune
|
|
46
89
|
no dead leases to prune
|
|
47
90
|
```
|
|
48
91
|
|
|
49
|
-
|
|
92
|
+
> Output is real — captured with `PORTZILLA_DATA_DIR` pointed at a temp directory with two live processes.
|
|
50
93
|
|
|
51
94
|
## Install
|
|
52
95
|
|
|
53
|
-
|
|
54
|
-
|
|
96
|
+
**Cargo:**
|
|
55
97
|
```console
|
|
56
98
|
$ cargo install portzilla
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
To install from a local checkout:
|
|
60
|
-
|
|
61
|
-
```console
|
|
99
|
+
# from local checkout:
|
|
62
100
|
$ cargo install --path .
|
|
63
101
|
```
|
|
64
102
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
Downloads a prebuilt binary from GitHub Releases into `~/.local/bin`:
|
|
68
|
-
|
|
103
|
+
**curl** (prebuilt binary to `~/.local/bin`, falls back to cargo):
|
|
69
104
|
```console
|
|
70
105
|
$ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | sh
|
|
106
|
+
# specific version / directory:
|
|
107
|
+
$ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | PORTZILLA_VERSION=0.3.0 PORTZILLA_INSTALL_DIR=/usr/local/bin sh
|
|
71
108
|
```
|
|
72
109
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
```console
|
|
76
|
-
$ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | PORTZILLA_VERSION=0.1.0 PORTZILLA_INSTALL_DIR=/usr/local/bin sh
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
If a release asset is unavailable, the installer falls back to `cargo install portzilla`.
|
|
80
|
-
|
|
81
|
-
### npm
|
|
82
|
-
|
|
110
|
+
**npm** (same native binary):
|
|
83
111
|
```console
|
|
84
112
|
$ npm install -g portzilla
|
|
85
113
|
```
|
|
86
114
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
Release binaries are currently available for Linux x86_64/ARM64, macOS Intel/Apple Silicon, and Windows x86_64/ARM64. Each release asset includes a `.sha256` checksum file.
|
|
90
|
-
|
|
91
|
-
## Command reference
|
|
92
|
-
|
|
93
|
-
Every command accepts `--json` to print a single JSON value on stdout instead of human-readable text. Every command reads and writes the same file-locked JSON state file, so concurrent invocations from different processes are serialized safely.
|
|
94
|
-
|
|
95
|
-
### `portzilla claim <PORT> --tag <TAG> [--pid <PID>] [--session <SESSION>] [--json]`
|
|
96
|
-
|
|
97
|
-
Claims `<PORT>` for the given (or default) PID and tag.
|
|
98
|
-
|
|
99
|
-
- `--tag <TAG>` — required. Human-readable description of what the port is for.
|
|
100
|
-
- `--pid <PID>` — optional. Defaults to the PID of the parent process (the shell or agent invoking `portzilla`); falls back to `portzilla`'s own PID if the parent cannot be determined.
|
|
101
|
-
- `--session <SESSION>` — optional. Groups related leases under a session identifier.
|
|
102
|
-
- `--json` — print the outcome as JSON instead of a one-line summary.
|
|
103
|
-
|
|
104
|
-
Conflict resolution:
|
|
105
|
-
|
|
106
|
-
- No lease on the requested port, or the existing lease's owning PID is dead: the port is claimed (or re-taken) directly. Not reassigned.
|
|
107
|
-
- A live lease on the requested port already owned by the same PID: the lease is updated in place (idempotent re-claim — tag and session can change, the port does not). Not reassigned.
|
|
108
|
-
- A live lease on the requested port owned by a different PID: `portzilla` finds the next free port at or after `requested_port + 1` (skipping ports with a live lease and ports the OS reports as bound) and claims that instead. Reassigned.
|
|
109
|
-
|
|
110
|
-
### `portzilla ls [--json]`
|
|
111
|
-
|
|
112
|
-
Lists every recorded lease. Human output is a table (`PORT PID STATUS AGE TAG`); JSON output is an array of lease objects (see shape below).
|
|
113
|
-
|
|
114
|
-
### `portzilla who <PORT> [--json]`
|
|
115
|
-
|
|
116
|
-
Shows the lease recorded on `<PORT>`. Exits with code `2` and prints nothing to stdout if no lease exists on that port.
|
|
117
|
-
|
|
118
|
-
### `portzilla release <PORT> [--json]`
|
|
119
|
-
|
|
120
|
-
Removes the lease recorded on `<PORT>` and prints the removed lease. Exits with code `2` if no lease exists on that port. If the owning PID is still alive at the time of release, a warning is printed to stderr (`release` always wins — it does not check ownership or refuse to act).
|
|
121
|
-
|
|
122
|
-
### `portzilla prune [--json]`
|
|
123
|
-
|
|
124
|
-
Removes every lease whose owning PID is no longer alive and prints each one that was removed. Human output prints `no dead leases to prune` if nothing was pruned; JSON output prints `[]`.
|
|
125
|
-
|
|
126
|
-
## Exit codes
|
|
127
|
-
|
|
128
|
-
| Code | Meaning |
|
|
129
|
-
|------|---------|
|
|
130
|
-
| `0` | Success |
|
|
131
|
-
| `1` | Unexpected error (I/O failure, corrupt state file, lock failure) |
|
|
132
|
-
| `2` | Requested lease not found (`who` / `release` on a port with no lease) |
|
|
133
|
-
|
|
134
|
-
## JSON output shapes
|
|
135
|
-
|
|
136
|
-
### Lease object (`ls`, `who`, `release`, `prune`)
|
|
137
|
-
|
|
138
|
-
Used as a single object by `who` and `release`, and as an array of these objects by `ls` and `prune`:
|
|
139
|
-
|
|
140
|
-
```json
|
|
141
|
-
{
|
|
142
|
-
"port": 3001,
|
|
143
|
-
"pid": 57108,
|
|
144
|
-
"tag": "vite-dev",
|
|
145
|
-
"created_at": 1785959877,
|
|
146
|
-
"session": null,
|
|
147
|
-
"age_secs": 3,
|
|
148
|
-
"alive": true
|
|
149
|
-
}
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
`created_at` is a Unix timestamp in seconds. `session` is `null` unless `--session` was given at claim time. `alive` reflects a live PID-table check at the moment of the query, not a cached value.
|
|
153
|
-
|
|
154
|
-
### Claim outcome (`claim --json`)
|
|
155
|
-
|
|
156
|
-
```json
|
|
157
|
-
{
|
|
158
|
-
"port": 3001,
|
|
159
|
-
"pid": 57285,
|
|
160
|
-
"tag": "vite-dev",
|
|
161
|
-
"created_at": 1785959898,
|
|
162
|
-
"session": null,
|
|
163
|
-
"requested_port": 3000,
|
|
164
|
-
"reassigned": true
|
|
165
|
-
}
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
`requested_port` is the port that was originally asked for; `port` is the port actually leased. `reassigned` is `true` only when `port != requested_port` because of a live conflicting claim.
|
|
169
|
-
|
|
170
|
-
## MCP server
|
|
171
|
-
|
|
172
|
-
`portzilla serve --mcp` runs an [MCP](https://modelcontextprotocol.io) server over stdio, exposing `claim`, `who`, `ls`, `release`, and `prune` as MCP tools (those are the registered tool names — no `portzilla_` prefix). This is for AI coding agents with MCP tool access (Claude Code, and any other MCP client): they call `who` the same way they call any other structured tool — typed JSON in, typed JSON out — instead of shelling out to the CLI and parsing text.
|
|
173
|
-
|
|
174
|
-
Register it with Claude Code:
|
|
175
|
-
|
|
176
|
-
```console
|
|
177
|
-
$ claude mcp add portzilla -- portzilla serve --mcp
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
Every tool's description is written to make the intended behavior explicit to the calling agent — the `claim` tool description, for example, says outright to use it *instead of* killing whatever occupies a port. Tool results use the exact same flat JSON shapes documented above for `--json` output (see [JSON output shapes](#json-output-shapes)), so anything already written against the CLI's JSON recognizes MCP results too.
|
|
181
|
-
|
|
182
|
-
- **`claim(port, tag, pid?, session?)`** — same semantics as `portzilla claim`. `pid` is optional here for a different reason than on the CLI: there is no meaningful "parent process" to default to (the MCP client, not a shell, owns the session), so an omitted `pid` falls back to the portzilla server process's own PID — almost never what you want — and the result carries an extra `note` field saying so. Always pass the PID of the process you started (or are about to start) on that port when you have it.
|
|
183
|
-
- **`who(port)`** — same semantics as `portzilla who`.
|
|
184
|
-
- **`ls()`** — same semantics as `portzilla ls`, no arguments.
|
|
185
|
-
- **`release(port)`** — same semantics as `portzilla release`, including the still-alive warning (surfaced as a `was_alive` field on the result instead of a stderr line).
|
|
186
|
-
- **`prune()`** — same semantics as `portzilla prune`, no arguments.
|
|
187
|
-
|
|
188
|
-
**Errors**: a missing lease (`who`/`release` on a port with no lease) comes back as a *tool-level* error — the JSON-RPC call still succeeds, but the tool result is flagged `isError: true` with a structured `{"error": "not_found", "port": ..., "message": ...}` body. This mirrors the CLI's exit code `2`: it is an expected, well-formed outcome the calling agent should see and act on, not a protocol failure. Actual portzilla failures (I/O errors, corrupt state, lock failures — the CLI's exit code `1`) come back as real JSON-RPC protocol errors instead, since those mean the server itself couldn't do its job.
|
|
189
|
-
|
|
190
|
-
The MCP server reads and writes the exact same locked `leases.json` the CLI does (respecting `PORTZILLA_DATA_DIR`) — it is a second front end onto the same on-disk state, not a separate store.
|
|
191
|
-
|
|
192
|
-
## Kill guard
|
|
193
|
-
|
|
194
|
-
MCP tool access (above) makes it *possible* for an agent to check ownership before acting. The kill guard is what makes checking the *default*: it intercepts kill-shaped commands before they run and blocks the ones that would kill another session's live, leased process — instead of relying on the agent to remember to run `who` first.
|
|
195
|
-
|
|
196
|
-
The guard itself (`src/guard.rs`) is harness-agnostic: it takes a shell command string and the current lease list and returns a verdict, with no knowledge of Claude Code, Cursor, Gemini CLI, Codex CLI, Kimi CLI, OpenCode, Windsurf, or any other tool. Each harness gets a thin adapter over the same core (`src/claude_code.rs`, `src/cursor.rs`, `src/gemini.rs`, `src/codex.rs`, `src/kimi.rs`, `src/opencode.rs`, `src/windsurf.rs`) that only translates the harness's hook payload in and its response shape out — adding a new harness means writing another adapter like these, never touching the guard itself.
|
|
197
|
-
|
|
198
|
-
It recognizes:
|
|
199
|
-
|
|
200
|
-
- `kill <pid>` / `kill -9 <pid>` — explicit PIDs, including `sudo kill ...`, `FOO=1 kill ...` (leading env-var assignments), and `/usr/bin/kill ...` (matched by basename)
|
|
201
|
-
- `pkill <name>` / `killall <name>` — process names (can't be resolved to a specific lease, so this only ever warns, never denies)
|
|
202
|
-
- `lsof -ti:<port> | xargs kill` (and the `lsof -ti :<port>` / `-9` variants) — only when actually piped together, not merely run one after another with `;`/`&&`
|
|
203
|
-
- `fuser -k <port>/tcp` (and `/udp`) — a bare `fuser -k <port>` with no protocol suffix is not treated as a port kill, matching real `fuser`'s own argument parsing
|
|
204
|
-
- `npx kill-port <port>` / `kill-port <port>` (including `npx -y kill-port ...` / `npx --yes kill-port ...`)
|
|
205
|
-
|
|
206
|
-
Leading wrapper prefixes are stripped before the verb is read, so the kill intent is detected whether it appears directly or behind one of `env`, `command`, `exec`, `nohup`, `builtin`, or any combination with `sudo` — `sudo env FOO=1 command kill <pid>` resolves to `kill <pid>`. A leading `sh -c '<payload>'` invocation is also unwrapped (the same shape the universal `guard` wrapper handles for argv), so a kill hidden inside the payload is detected through the hook adapters too.
|
|
207
|
-
|
|
208
|
-
For each, it resolves the target PID or port against the lease registry and decides:
|
|
209
|
-
|
|
210
|
-
- **Allow** — no kill intent detected, the target has no live lease, the lease is dead, or the lease is yours (you're allowed to kill/restart your own claimed process — see "Session ownership" below).
|
|
211
|
-
- **Deny** — the target has a live lease owned by someone else. The explanation names the port, PID, and tag, and says what to do instead: check `portzilla who <port>`, claim a different port, or ask before proceeding if the lease looks stale.
|
|
212
|
-
- **Warn** — a kill intent was detected but can't be resolved to a specific port/PID (killing by process name). portzilla can't verify safety here, so it surfaces a warning instead of silently allowing or incorrectly denying.
|
|
213
|
-
|
|
214
|
-
This is intentionally not a real shell parser — see the module doc comment in `src/guard.rs` for the exact approximation (split on `|`/`;`/`&&`/`||`, look at each segment's first word) and its tested boundaries, e.g. `killall-whatever` doesn't trigger `killall` detection, and `echo "kill 123"` doesn't trigger `kill` detection. False negatives are an accepted tradeoff; false positives are not.
|
|
215
|
-
|
|
216
|
-
### Support matrix
|
|
217
|
-
|
|
218
|
-
| Harness | Mechanism | Deny reason reaches the model? | Own-lease recognition? |
|
|
219
|
-
|---|---|---|---|
|
|
220
|
-
| **Claude Code** | `PreToolUse` hook, `portzilla hook claude-code` | Yes — `permissionDecisionReason` | **Yes** — `--session "$CLAUDE_CODE_SESSION_ID"` |
|
|
221
|
-
| **Cursor** | `beforeShellExecution` hook, `portzilla hook cursor` | Likely — `agent_message` is documented for this event without a deny-only qualifier (unlike some other Cursor hook events' docs); delivery on `permission: "allow"` is not positively confirmed, only not ruled out — needs a live Cursor smoke test | No — `conversation_id` isn't exposed to the agent's shell commands |
|
|
222
|
-
| **Gemini CLI** | `BeforeTool` hook on `run_shell_command`, `portzilla hook gemini` | Yes for Deny (`reason`); **no non-blocking channel for Warn** (human-only, `systemMessage`) | No — the shell tool only sets `GEMINI_CLI=1`, not a session id |
|
|
223
|
-
| **Codex CLI** | `PreToolUse` hook, `portzilla hook codex` | Yes — `permissionDecisionReason` on deny; **yes for Warn** — `additionalContext` is added as extra developer context the model sees | No — `session_id` reaches the hook payload but not the agent's shell commands |
|
|
224
|
-
| **Kimi CLI** | `PreToolUse` hook, `portzilla hook kimi` | Yes — stderr on exit 2 is fed back to the model; **yes for Warn** — exit-0 stdout is added to the model's context | No — `session_id` reaches the hook payload but not the agent's shell commands |
|
|
225
|
-
| **OpenCode** | Plugin shim (`portzilla init opencode` prints `portzilla.js`) shelling out to `portzilla hook opencode` | Yes for Deny — throwing surfaces the reason as a tool error; **yes for Warn** — appended to the tool result via `tool.execute.after` | **Yes** — the shim injects `PORTZILLA_SESSION` into bash subprocess env via `shell.env`, and the guard gets the session id from `tool.execute.before` |
|
|
226
|
-
| **Windsurf** | `pre_run_command` hook, `portzilla hook windsurf` | Yes for Deny — stderr on exit 2 is shown to the Cascade agent; **no non-blocking channel for Warn** (stderr on exit 0 is human-visible only; with `show_output: true`) | No — `trajectory_id` reaches the hook payload but not the agent's shell commands |
|
|
227
|
-
| **Anything else** (Aider, scripts, a human) | `portzilla guard -- <command...>` | N/A — the command is simply not run (exit 2); there's no model in the loop to explain to | **Yes** — `--session <S>` or `PORTZILLA_SESSION` |
|
|
228
|
-
|
|
229
|
-
"Own-lease recognition" means: a lease claimed with the right session identifier is recognized as *yours*, so the guard lets you kill/restart your own process. Without it, the guard still protects you from killing *other* sessions' processes — it just can't yet tell your own process apart from a stranger's, so it protects everyone equally, including you.
|
|
230
|
-
|
|
231
|
-
### Claude Code setup
|
|
232
|
-
|
|
233
|
-
```console
|
|
234
|
-
$ portzilla init claude-code
|
|
235
|
-
```
|
|
236
|
-
|
|
237
|
-
prints the exact `.claude/settings.json` snippet to add (project-level `.claude/settings.json` or user-level `~/.claude/settings.json`), registering `portzilla hook claude-code` as a `PreToolUse` hook on the `Bash` tool. This only prints instructions — it never writes to your settings file.
|
|
115
|
+
Binaries for Linux x86_64/ARM64, macOS Intel/Apple Silicon, Windows x86_64/ARM64 — each with `.sha256` checksums.
|
|
238
116
|
|
|
239
|
-
|
|
117
|
+
## Commands
|
|
240
118
|
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
119
|
+
| Command | What it does |
|
|
120
|
+
|---------|--------------|
|
|
121
|
+
| `portzilla claim <PORT> --tag <TAG> [--pid <PID>] [--session <S>]` | Claim a port; on conflict with a live lease from another PID, auto-claims next free port |
|
|
122
|
+
| `portzilla ls` | List all leases (`PORT PID STATUS AGE TAG`) |
|
|
123
|
+
| `portzilla who <PORT>` | Show lease on a port (exit `2` if none) |
|
|
124
|
+
| `portzilla release <PORT>` | Remove lease (always wins; warns if PID still alive) |
|
|
125
|
+
| `portzilla prune` | Remove all leases whose PID is dead |
|
|
126
|
+
| `portzilla run <PORT> --tag <TAG> [--session <S>] -- <cmd...>` | Claim a port and run a server with it; the lease follows the child PID |
|
|
127
|
+
| `portzilla watch [--interval <SECONDS>]` | Repeatedly prune leases whose recorded PID is dead |
|
|
250
128
|
|
|
251
|
-
|
|
129
|
+
Data-producing commands are file-locked and support `--json`. Full flags, conflict semantics, exit codes and JSON shapes → **[docs/CLI.md](docs/CLI.md)**.
|
|
252
130
|
|
|
253
|
-
|
|
131
|
+
## Agent skill
|
|
254
132
|
|
|
255
|
-
|
|
133
|
+
For OpenCode agents, install the checked-in `portzilla` skill explicitly:
|
|
256
134
|
|
|
257
135
|
```console
|
|
258
|
-
$
|
|
136
|
+
$ mkdir -p .opencode/skills/portzilla
|
|
137
|
+
$ portzilla init skill > .opencode/skills/portzilla/SKILL.md
|
|
259
138
|
```
|
|
260
139
|
|
|
261
|
-
prints the
|
|
140
|
+
`init skill` only prints the skill file to stdout — it never writes configuration for you; the redirect above is what saves it. The skill teaches the agent to start servers with `portzilla run` and `$PORTZILLA_PORT`. Kill-guard setup stays separate: `portzilla init opencode` prints the `portzilla.js` plugin shim (see [Kill guard](#kill-guard)).
|
|
262
141
|
|
|
263
|
-
|
|
142
|
+
## Watch mode
|
|
264
143
|
|
|
265
|
-
|
|
144
|
+
`portzilla watch` is an optional foreground watcher. It is not a central IPC
|
|
145
|
+
daemon: it uses the same locked local state file as the other commands, does
|
|
146
|
+
not listen for clients, and agents continue to use the CLI or MCP server for
|
|
147
|
+
claims and queries.
|
|
266
148
|
|
|
267
149
|
```console
|
|
268
|
-
$ portzilla
|
|
150
|
+
$ portzilla watch --interval 30
|
|
151
|
+
no leases pruned
|
|
152
|
+
pruned port 3000 (pid 57107, tag: next-dev)
|
|
269
153
|
```
|
|
270
154
|
|
|
271
|
-
|
|
155
|
+
The watcher validates that `--interval` is a positive number of seconds and
|
|
156
|
+
defaults to `60`. It runs one prune cycle immediately, waits for the interval,
|
|
157
|
+
then repeats until Ctrl-C. Each cycle checks recorded process liveness, not
|
|
158
|
+
lease age, and removes only leases whose recorded server process is no longer
|
|
159
|
+
alive. For a new lease, preservation requires a verified process identity: the
|
|
160
|
+
current process must match both the recorded PID and `process_start_time`. If
|
|
161
|
+
identity could not be resolved when the lease was created, it is intentionally
|
|
162
|
+
unverified/dead and may be pruned even when that numeric PID currently exists.
|
|
163
|
+
Legacy leases without identity metadata retain PID-only liveness behavior. If
|
|
164
|
+
an agent exits while a new lease's verified recorded server process remains
|
|
165
|
+
alive, that lease is preserved.
|
|
272
166
|
|
|
273
|
-
|
|
167
|
+
Ordinary store errors are printed to stderr and retried on the next cycle. A
|
|
168
|
+
startup error, such as an inability to open the data directory, is fatal and
|
|
169
|
+
exits the command instead of entering the retry loop. Ctrl-C shuts down the
|
|
170
|
+
watcher successfully.
|
|
274
171
|
|
|
275
|
-
|
|
172
|
+
With `--json`, stdout contains one event per completed cycle, including empty
|
|
173
|
+
cycles:
|
|
276
174
|
|
|
277
|
-
```
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
prints the exact `~/.kimi/config.toml` snippet to add, registering `portzilla hook kimi` as a `[[hooks]]` entry on `PreToolUse` matched on `Shell`. Kimi's hooks are Beta (implementation details may change), and Kimi CLI is being [wound down in favor of Kimi Code CLI](https://github.com/MoonshotAI/kimi-cli) — re-verify this integration when adopting the successor.
|
|
282
|
-
|
|
283
|
-
Kimi's `PreToolUse` contract is exit-code driven rather than JSON-response driven: `portzilla hook kimi` exits 2 (with the reason on stderr, which Kimi feeds back to the model) to deny, and prints `Warn` explanations as plain text on stdout, which Kimi adds to the model's context on allow. As with Cursor/Gemini/Codex, the session id reaches the hook payload but not the agent's own shell commands, so own-lease recognition isn't available yet.
|
|
284
|
-
|
|
285
|
-
### OpenCode setup
|
|
286
|
-
|
|
287
|
-
```console
|
|
288
|
-
$ portzilla init opencode
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
prints the full source of the `portzilla.js` plugin shim to save as `.opencode/plugin/portzilla.js` (project) or `~/.config/opencode/plugin/portzilla.js` (user), then restart OpenCode — plugins load once at startup, not hot-reloaded. Your editor needs `portzilla` on PATH. OpenCode hooks run in-process as JS/TS plugin modules, which is why this harness uses a shim instead of running `portzilla` as the hook directly.
|
|
292
|
-
|
|
293
|
-
The shim hooks `tool.execute.before` for the `bash` tool, shells out to `portzilla hook opencode`, and throws with the deny reason (OpenCode surfaces it to the model as a tool error) or defers a warn to `tool.execute.after` so the model sees it on the tool result without blocking. Because the shim also adds a `shell.env` hook that injects `PORTZILLA_SESSION` into every bash subprocess, this is the only non-Claude harness where end-to-end own-lease recognition works:
|
|
294
|
-
|
|
295
|
-
```console
|
|
296
|
-
$ portzilla claim 3000 --tag "vite dev" --session "$PORTZILLA_SESSION"
|
|
297
|
-
```
|
|
298
|
-
|
|
299
|
-
### Windsurf setup
|
|
300
|
-
|
|
301
|
-
```console
|
|
302
|
-
$ portzilla init windsurf
|
|
175
|
+
```json
|
|
176
|
+
{"event":"watch_cycle","pruned":[]}
|
|
177
|
+
{"event":"watch_cycle","pruned":[{"port":3000,"pid":57107,"tag":"next-dev","created_at":1785959877,"session":null,"process_start_time":1785959876,"age_secs":3,"alive":false}]}
|
|
303
178
|
```
|
|
304
179
|
|
|
305
|
-
|
|
180
|
+
Diagnostics, including retry and shutdown messages, go to stderr. See the
|
|
181
|
+
[CLI reference](docs/CLI.md) for the complete event shape.
|
|
306
182
|
|
|
307
|
-
|
|
183
|
+
## MCP server
|
|
308
184
|
|
|
309
|
-
For
|
|
185
|
+
For agents with MCP access (Claude Code, etc.) — typed JSON in/out instead of shelling out:
|
|
310
186
|
|
|
311
187
|
```console
|
|
312
|
-
$ portzilla
|
|
313
|
-
portzilla guard: blocked — Port 3000 is leased to pid 57107 (tag: "next-dev") — a live process owned by another session, not a stale one. ...
|
|
314
|
-
$ echo $?
|
|
315
|
-
2
|
|
188
|
+
$ claude mcp add portzilla -- portzilla serve --mcp
|
|
316
189
|
```
|
|
317
190
|
|
|
318
|
-
|
|
319
|
-
- **Warn** — a warning goes to stderr, then the command runs.
|
|
320
|
-
- **Allow** — the command runs with no extra output.
|
|
321
|
-
- `--session <S>`, or the `PORTZILLA_SESSION` environment variable if `--session` is omitted, enables own-lease recognition the same way `--session` does for `claim`.
|
|
322
|
-
- The command after `--` is executed directly — no shell, so pipes and compounds are not interpreted by `portzilla guard` itself. On Unix this replaces the current process via `exec`, so exit codes pass straight through as if `portzilla guard` were never there (and if the command itself can't be started, `portzilla guard` exits with the same POSIX convention a shell would: `127` if it wasn't found, `126` for any other reason — not executable, permission denied, etc.). For a pipe or compound command, wrap it in `sh -c`:
|
|
323
|
-
|
|
324
|
-
```console
|
|
325
|
-
$ portzilla guard -- sh -c 'lsof -ti:3000 | xargs kill'
|
|
326
|
-
```
|
|
191
|
+
Exposes `claim`, `who`, `ls`, `release`, `prune` as MCP tools with the same JSON shapes as `--json`. See **[docs/CLI.md#mcp-server](docs/CLI.md#mcp-server)**.
|
|
327
192
|
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
### Fail-open, always
|
|
193
|
+
## Kill guard
|
|
331
194
|
|
|
332
|
-
|
|
195
|
+
Makes *checking ownership the default* — blocks `kill` commands that would kill another session's live leased process.
|
|
333
196
|
|
|
334
|
-
|
|
197
|
+
Recognizes `kill <pid>`, `pkill`/`killall`, `lsof -ti:<port> | xargs kill`, `fuser -k <port>/tcp`, `kill-port <port>` (including `sudo`, `env` wrappers and `sh -c` payloads). Verdict: **Allow** / **Deny** (live foreign lease) / **Warn** (unresolvable).
|
|
335
198
|
|
|
336
|
-
|
|
199
|
+
| Harness | Hook | Deny reaches model? | Own-lease? |
|
|
200
|
+
|---------|------|---------------------|------------|
|
|
201
|
+
| **Claude Code** | `PreToolUse` — `portzilla hook claude-code` | Yes (`permissionDecisionReason`) | **Yes** (`$CLAUDE_CODE_SESSION_ID`) |
|
|
202
|
+
| **Cursor** | `beforeShellExecution` — `portzilla hook cursor` | Likely (`agent_message`) | No |
|
|
203
|
+
| **Gemini CLI** | `BeforeTool` — `portzilla hook gemini` | Yes (Deny), no Warn channel | No |
|
|
204
|
+
| **Codex CLI** | `PreToolUse` — `portzilla hook codex` | Yes (Deny + Warn via `additionalContext`) | No |
|
|
205
|
+
| **Kimi CLI** | `PreToolUse` — `portzilla hook kimi` | Yes (stderr on exit 2) | No |
|
|
206
|
+
| **OpenCode** | Plugin shim — `portzilla init opencode` | Yes (Deny + Warn) | **Yes** (`$PORTZILLA_SESSION`) |
|
|
207
|
+
| **Windsurf** | `pre_run_command` — `portzilla hook windsurf` | Yes (stderr) | No |
|
|
208
|
+
| **Anything else** | `portzilla guard -- <cmd>` | N/A (exit 2) | **Yes** (`--session` / `$PORTZILLA_SESSION`) |
|
|
337
209
|
|
|
338
|
-
|
|
210
|
+
Setup: `portzilla init <harness>` prints the snippet to add — never writes files for you. Guard fails open by default; `PORTZILLA_FAIL_CLOSED=1` opts into fail-closed.
|
|
339
211
|
|
|
340
|
-
|
|
341
|
-
- `tag` is capped at 1024 characters and `session` at 512; oversized values are rejected with a clear error before the store is touched.
|
|
342
|
-
- Hook runners cap stdin at 1 MiB; over-cap inputs are treated like a malformed payload.
|
|
212
|
+
Full harness setup, `sh -c` unwrapping rules, and fail-open/closed semantics → **[docs/GUARD.md](docs/GUARD.md)**.
|
|
343
213
|
|
|
344
|
-
## Data file
|
|
214
|
+
## Data file & config
|
|
345
215
|
|
|
346
|
-
`portzilla`
|
|
216
|
+
Resolution order: `PORTZILLA_DATA_DIR` → `$XDG_DATA_HOME/portzilla` → `~/.local/share/portzilla`. State at `leases.json` (atomic write + `leases.json.lock`).
|
|
347
217
|
|
|
348
|
-
|
|
349
|
-
2. `$XDG_DATA_HOME/portzilla`.
|
|
350
|
-
3. `$HOME/.local/share/portzilla`.
|
|
218
|
+
`PORTZILLA_DATA_DIR` isolates tests/CI. `tag` max 1024 chars, `session` max 512, hook stdin capped at 1 MiB. New leases persist `process_start_time` when available; reassignment JSON includes `reassignment_reason` (`lease_conflict` or `os_occupied`). Claims for an explicit PID that does not exist yet are retained as unverified/dead records, not as ownership promises. The normal CLI default attributes a claim to its live parent process. See **[docs/CLI.md](docs/CLI.md)**.
|
|
351
219
|
|
|
352
|
-
|
|
220
|
+
## Limitations
|
|
353
221
|
|
|
354
|
-
|
|
222
|
+
**PID reuse.** New leases record `process_start_time` when it can be resolved and require a verified match for both the PID and start time during liveness checks. New leases whose identity cannot be resolved are intentionally unverified/dead and can be pruned even if the numeric PID exists. Legacy leases without identity metadata retain PID-only checks. `sysinfo` reports start times at one-second resolution, so a PID recycled within the same second cannot be distinguished perfectly. Checks are point-in-time: `prune` sweeps on demand, and the optional foreground `watch` command repeats those sweeps. An active expiry daemon remains on the [roadmap](docs/ROADMAP.md). See [PRD non-goals](docs/PRD.md).
|
|
355
223
|
|
|
356
|
-
|
|
224
|
+
**OS occupancy.** `claim` also probes IPv4 wildcard/loopback and usable IPv6 wildcard/loopback addresses. A bound but unregistered port is skipped and reports `reassignment_reason: "os_occupied"`; socket state can change immediately after the probe, so claiming is coordination, not a reservation.
|
|
357
225
|
|
|
358
|
-
**
|
|
226
|
+
**State-file versions.** New writes use a versioned `leases.json` envelope (`format_version: 2`) so newer identity fields cannot be silently discarded. Legacy bare-array files are read and upgraded on the next write. Older binaries cannot safely read v2 files and must be upgraded before using the same data directory; unknown future versions are rejected without rewriting the file.
|
|
359
227
|
|
|
360
|
-
`portzilla`
|
|
228
|
+
`portzilla run` starts one server command and waits for it, but Portzilla does not stop, restart, or supervise arbitrary servers. It does not enforce a firewall/sandbox or coordinate across machines.
|
|
361
229
|
|
|
362
230
|
## Roadmap
|
|
363
231
|
|
|
364
|
-
v0.1
|
|
232
|
+
v0.1: `claim`/`ls`/`who`/`release`/`prune` + JSON + locked state. v0.1.x: MCP server. v0.2: kill guard + harness adapters + `portzilla guard`. v0.3: `portzilla run` + installable agent skill. The optional foreground `watch` command is implemented; an active daemon remains future work. Full plan → [`docs/ROADMAP.md`](docs/ROADMAP.md). Release procedure → [`docs/RELEASING.md`](docs/RELEASING.md).
|
|
365
233
|
|
|
366
234
|
## License
|
|
367
235
|
|
|
368
|
-
MIT
|
|
236
|
+
MIT — see [`LICENSE`](LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "portzilla",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Port and process lease coordinator for parallel AI coding-agent sessions",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://github.com/011010/portzilla",
|
|
@@ -20,6 +20,7 @@
|
|
|
20
20
|
"files": [
|
|
21
21
|
"npm/bin.js",
|
|
22
22
|
"npm/install.js",
|
|
23
|
+
"skills/portzilla/SKILL.md",
|
|
23
24
|
"README.md",
|
|
24
25
|
"LICENSE"
|
|
25
26
|
],
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: portzilla
|
|
3
|
+
description: Coordinate local dev-server ports across parallel agent sessions. Use when starting, stopping, checking, or resolving a local dev-server port.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Portzilla — dev-server port coordination
|
|
7
|
+
|
|
8
|
+
Use this skill when starting, stopping, checking, or resolving a local dev-server port.
|
|
9
|
+
|
|
10
|
+
## Prerequisites
|
|
11
|
+
|
|
12
|
+
- `portzilla` must be on PATH. Verify with `portzilla --version` before doing anything else.
|
|
13
|
+
|
|
14
|
+
## Starting a dev server
|
|
15
|
+
|
|
16
|
+
1. Inspect the project (its manifest, README, and existing scripts) to choose the right dev-server command for this project.
|
|
17
|
+
2. The chosen command must consume the assigned port from the `PORTZILLA_PORT` environment variable.
|
|
18
|
+
3. When a non-empty agent session variable is available, pass it explicitly. Never pass `--session ""`: when the variable is unset or empty, omit `--session` entirely. Use a shell array so empty never becomes an argument: `SESSION_ARGS=(); if [ -n "${PORTZILLA_SESSION:-}" ]; then SESSION_ARGS=(--session "$PORTZILLA_SESSION"); fi` in OpenCode, or `SESSION_ARGS=(); if [ -n "${CLAUDE_CODE_SESSION_ID:-}" ]; then SESSION_ARGS=(--session "$CLAUDE_CODE_SESSION_ID"); fi` in Claude Code.
|
|
19
|
+
4. Launch it in one step with `portzilla run <port> --tag "<what it is>" "${SESSION_ARGS[@]}" -- <command>`. Do not claim the port first — `run` claims it and holds the lease for the server process.
|
|
20
|
+
5. If the requested port is busy, `run` reassigns to the next free port and reports it on stderr. Always report the actual assigned port (`PORTZILLA_PORT`) to the user, especially when it differs from the requested one.
|
|
21
|
+
|
|
22
|
+
## Inspecting and stopping
|
|
23
|
+
|
|
24
|
+
- Check a single port with `portzilla who <port>`; list everything with `portzilla ls`.
|
|
25
|
+
- Release a port only when you explicitly know it is yours to release (the user named it, or your own session claimed it): confirm ownership with `who` first, then `portzilla release <port>`.
|
|
26
|
+
|
|
27
|
+
## Kill-guard setup
|
|
28
|
+
|
|
29
|
+
This skill does not set up kill protection. If explicitly asked for kill-guard or hook setup, direct that request to `portzilla init opencode` instead.
|