portzilla 0.4.0 → 0.6.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 +96 -12
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
<h1 align="center">portzilla</h1>
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
|
-
<strong>
|
|
8
|
+
<strong>Coordination layer for parallel AI agent sessions — ports, files, and worktree environments.</strong>
|
|
9
9
|
</p>
|
|
10
10
|
|
|
11
11
|
<p align="center">
|
|
@@ -13,13 +13,19 @@
|
|
|
13
13
|
<a href="https://crates.io/crates/portzilla"><img src="https://img.shields.io/crates/v/portzilla" alt="crates.io"></a>
|
|
14
14
|
<a href="https://www.npmjs.com/package/portzilla"><img src="https://img.shields.io/npm/v/portzilla" alt="npm"></a>
|
|
15
15
|
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
|
|
16
|
+
[](https://m8ven.ai/mcp/011010-portzilla-qdocjc?s=readme)
|
|
16
17
|
</p>
|
|
17
18
|
|
|
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**.
|
|
19
|
+
> AI coding agents (Claude Code, Cursor, etc.) run parallel sessions in git worktrees — each starting its own dev server, editing the same files, and pointing at the same database. Today they coordinate by killing whatever is on a port. `portzilla` is the layer that **prevents the conflict**.
|
|
19
20
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
21
|
+
| What collides | What portzilla gives you | Start here |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| A port both sessions want | A lease with owner PID and purpose tag. Conflicts get the next free port instead of a kill | `portzilla claim 3000 --tag next-dev` |
|
|
24
|
+
| A port another agent wants to kill | A guard that intercepts `kill`, `lsof \| xargs kill`, `fuser -k`, `kill-port` and blocks kills against another session's live lease | `portzilla init <harness>` |
|
|
25
|
+
| A file both sessions edit | A file intent. A proven conflict is denied; a clean merge is allowed with a warning; hooks do it automatically on OpenCode and Claude Code | `portzilla intent claim src/auth.ts` |
|
|
26
|
+
| A database and a `target/` directory both sessions share | An environment slot: its own ports, cache directories, `.env.portzilla`, and a database provisioned by your own commands | `portzilla slot up auth` |
|
|
27
|
+
|
|
28
|
+
Every layer speaks JSON and is exposed over MCP, so an agent calls it as a tool instead of parsing text. Everything is a single daemon-less binary.
|
|
23
29
|
|
|
24
30
|
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
31
|
|
|
@@ -34,7 +40,10 @@ Port allocators and proxies such as [Portless](https://portless.sh) solve addres
|
|
|
34
40
|
- [Agent skill](#agent-skill)
|
|
35
41
|
- [Watch mode](#watch-mode)
|
|
36
42
|
- [MCP server](#mcp-server)
|
|
43
|
+
- [Audit history](#audit-history)
|
|
37
44
|
- [Kill guard](#kill-guard)
|
|
45
|
+
- [File intents](#file-intents)
|
|
46
|
+
- [Environment slots](#environment-slots)
|
|
38
47
|
- [Data file & config](#data-file--config)
|
|
39
48
|
- [Limitations](#limitations)
|
|
40
49
|
|
|
@@ -104,7 +113,7 @@ $ cargo install --path .
|
|
|
104
113
|
```console
|
|
105
114
|
$ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | sh
|
|
106
115
|
# specific version / directory:
|
|
107
|
-
$ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | PORTZILLA_VERSION=0.
|
|
116
|
+
$ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | PORTZILLA_VERSION=0.6.0 PORTZILLA_INSTALL_DIR=/usr/local/bin sh
|
|
108
117
|
```
|
|
109
118
|
|
|
110
119
|
**npm** (same native binary):
|
|
@@ -125,8 +134,14 @@ Binaries for Linux x86_64/ARM64, macOS Intel/Apple Silicon, Windows x86_64/ARM64
|
|
|
125
134
|
| `portzilla prune` | Remove all leases whose PID is dead |
|
|
126
135
|
| `portzilla run <PORT> --tag <TAG> [--session <S>] -- <cmd...>` | Claim a port and run a server with it; the lease follows the child PID |
|
|
127
136
|
| `portzilla watch [--interval <SECONDS>]` | Repeatedly prune leases whose recorded PID is dead |
|
|
137
|
+
| `portzilla guard -- <cmd...>` | Run a command with the kill guard applied, for harnesses without hooks |
|
|
138
|
+
| `portzilla init <harness>` | Print the hook/plugin snippet to install; prose on stderr, snippet on stdout |
|
|
139
|
+
| `portzilla serve --mcp` | Run the MCP server on stdio |
|
|
140
|
+
| `portzilla intent claim\|who\|ls\|release\|history` | File intents: claim a path, inspect the holder, release early, read the journal |
|
|
141
|
+
| `portzilla slot up\|env\|run\|ls\|show\|down\|prune` | Environment slots: ports, cache dirs, `.env.portzilla`, database |
|
|
142
|
+
| `portzilla history [--json]` | Bounded lease and guard event journal |
|
|
128
143
|
|
|
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)**.
|
|
144
|
+
Data-producing commands are file-locked and support `--json`. Full flags, conflict semantics, exit codes and JSON shapes → **[docs/CLI.md](docs/CLI.md)**. Slots have their own reference: **[docs/SLOTS.md](docs/SLOTS.md)**.
|
|
130
145
|
|
|
131
146
|
## Agent skill
|
|
132
147
|
|
|
@@ -188,7 +203,9 @@ For agents with MCP access (Claude Code, etc.) — typed JSON in/out instead of
|
|
|
188
203
|
$ claude mcp add portzilla -- portzilla serve --mcp
|
|
189
204
|
```
|
|
190
205
|
|
|
191
|
-
Exposes `claim`, `who`, `ls`, `release`, `prune`,
|
|
206
|
+
Exposes `claim`, `who`, `ls`, `release`, `prune`, read-only `history`, and the four file-intent tools `intent_claim`, `intent_who`, `intent_ls`, `intent_release`, plus read-only `intent_history`, with the same JSON shapes as `--json`. See **[docs/CLI.md#mcp-server](docs/CLI.md#mcp-server)**.
|
|
207
|
+
|
|
208
|
+
The intent tools are the only file protection available on harnesses without an edit hook (Cursor, Gemini CLI, Codex, Windsurf): the agent calls `intent_claim` before editing and `intent_release` when it is done. They are cooperative, so they complement rather than replace the OpenCode and Claude Code hooks. **Pass a session string identical to the one your harness gives the hooks**, otherwise your own claims look foreign to the guard.
|
|
192
209
|
|
|
193
210
|
## Audit history
|
|
194
211
|
|
|
@@ -202,6 +219,8 @@ $ portzilla history clear
|
|
|
202
219
|
|
|
203
220
|
History is newest-first and supports `--session`, `--port`, `--event`, `--before`, and `--limit`. Hook and guard event writes are best-effort: a journal failure never changes an allow/deny decision. The MCP server exposes the same read-only history query; clearing history is CLI-only. See **[docs/CLI.md#history](docs/CLI.md#history)**.
|
|
204
221
|
|
|
222
|
+
File intents keep their own journal of the same size in `intents.json`, recording `claim_created`, `claim_refreshed`, `claim_taken_over` and `released` events next to the claims they describe. Query it with `portzilla intent history --session … --event … --limit …`, or read-only over MCP with `intent_history`. Expired records reaped by a new claim are housekeeping and are not logged.
|
|
223
|
+
|
|
205
224
|
## Kill guard
|
|
206
225
|
|
|
207
226
|
Makes *checking ownership the default* — blocks `kill` commands that would kill another session's live leased process.
|
|
@@ -210,22 +229,87 @@ Recognizes `kill <pid>`, `pkill`/`killall`, `lsof -ti:<port> | xargs kill`, `fus
|
|
|
210
229
|
|
|
211
230
|
| Harness | Hook | Deny reaches model? | Own-lease? |
|
|
212
231
|
|---------|------|---------------------|------------|
|
|
213
|
-
| **Claude Code** | `PreToolUse` — `portzilla hook claude-code` | Yes (`permissionDecisionReason`) | **Yes** (`$CLAUDE_CODE_SESSION_ID`) |
|
|
232
|
+
| **Claude Code** | `PreToolUse` + `PostToolUse` — `portzilla hook claude-code` | Yes (`permissionDecisionReason`; clean-merge context via `PostToolUse`) | **Yes** (`$CLAUDE_CODE_SESSION_ID`) |
|
|
214
233
|
| **Cursor** | `beforeShellExecution` — `portzilla hook cursor` | Likely (`agent_message`) | No |
|
|
215
234
|
| **Gemini CLI** | `BeforeTool` — `portzilla hook gemini` | Yes (Deny), no Warn channel | No |
|
|
216
235
|
| **Codex CLI** | `PreToolUse` — `portzilla hook codex` | Yes (Deny + Warn via `additionalContext`) | No |
|
|
217
236
|
| **Kimi CLI** | `PreToolUse` — `portzilla hook kimi` | Yes (stderr on exit 2) | No |
|
|
218
|
-
| **OpenCode** | Plugin shim — `portzilla init opencode` | Yes (Deny
|
|
237
|
+
| **OpenCode** | Plugin shim, V2 API — `portzilla init opencode` | Yes (Deny) | No (V2 gives no session id to shell commands) |
|
|
219
238
|
| **Windsurf** | `pre_run_command` — `portzilla hook windsurf` | Yes (stderr) | No |
|
|
220
239
|
| **Anything else** | `portzilla guard -- <cmd>` | N/A (exit 2) | **Yes** (`--session` / `$PORTZILLA_SESSION`) |
|
|
221
240
|
|
|
222
|
-
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.
|
|
241
|
+
Setup: `portzilla init <harness>` prints the snippet to add — never writes files for you. The snippet goes to stdout and the instructions to stderr, so a redirect such as `portzilla init opencode > .opencode/plugin/portzilla.js` saves exactly the file. Guard fails open by default; `PORTZILLA_FAIL_CLOSED=1` opts into fail-closed.
|
|
223
242
|
|
|
224
243
|
Full harness setup, `sh -c` unwrapping rules, and fail-open/closed semantics → **[docs/GUARD.md](docs/GUARD.md)**.
|
|
225
244
|
|
|
245
|
+
### File intents
|
|
246
|
+
|
|
247
|
+
Agents in parallel worktrees also collide on *files*: two sessions editing `src/auth.rs` produce a merge conflict that only surfaces at review time. File intents are the same lease idea applied to a path.
|
|
248
|
+
|
|
249
|
+
Three delivery paths, same store and same verdicts:
|
|
250
|
+
|
|
251
|
+
| Harness | How the check happens |
|
|
252
|
+
|---|---|
|
|
253
|
+
| OpenCode | Plugin shim asks on every `write`/`edit` and sends the pending edit |
|
|
254
|
+
| Claude Code | `PreToolUse` on `Write`/`Edit`; `PostToolUse` delivers the clean-merge warning |
|
|
255
|
+
| Everything with MCP | `intent_claim` / `intent_who` / `intent_ls` / `intent_release` — cooperative, the agent decides to call them |
|
|
256
|
+
|
|
257
|
+
What the guard does with the pending edit:
|
|
258
|
+
|
|
259
|
+
- The first session to edit a file claims it for 30 minutes (`PORTZILLA_INTENT_TTL_SECS` overrides the window).
|
|
260
|
+
- A session that edits it again refreshes its own claim.
|
|
261
|
+
- A *different* live session triggers a conflict check against the holder's working copy. A real conflict is denied, and the reason says the edit conflicts. An edit that merges cleanly is allowed, the holder keeps its claim, and the model reads a warning on the tool result that names the holder.
|
|
262
|
+
- Anything the check cannot prove — a v1 record with no recorded location, a git failure, an incomplete edit payload — is denied exactly as before. The check is fail-safe: the softer verdict applies only when cleanliness has been proven.
|
|
263
|
+
- A denied attempt claims nothing, so a blocked session cannot take the file by retrying.
|
|
264
|
+
|
|
265
|
+
The key is `<git-common-dir>:<repo-relative-path>`. The same relative file in two worktrees of one repository is one key; the same absolute path in a different repository is not. Outside a repository the key is the canonical absolute path.
|
|
266
|
+
|
|
267
|
+
Humans can inspect and clear claims without waiting for the TTL:
|
|
268
|
+
|
|
269
|
+
```console
|
|
270
|
+
$ portzilla intent claim src/auth.rs --session "$CLAUDE_CODE_SESSION_ID"
|
|
271
|
+
claimed /repo/src/auth.rs for session ... (expires in 1800s)
|
|
272
|
+
|
|
273
|
+
$ portzilla intent who src/auth.rs
|
|
274
|
+
/repo/src/auth.rs is held by session ... (age 12s, expires in 1788s)
|
|
275
|
+
|
|
276
|
+
$ portzilla intent ls
|
|
277
|
+
KEY SESSION AGE EXPIRES
|
|
278
|
+
...
|
|
279
|
+
|
|
280
|
+
$ portzilla intent release src/auth.rs --session "$CLAUDE_CODE_SESSION_ID"
|
|
281
|
+
released /repo/src/auth.rs for session ...
|
|
282
|
+
|
|
283
|
+
$ portzilla intent history --session "$CLAUDE_CODE_SESSION_ID"
|
|
284
|
+
SEQ AT EVENT SESSION KEY
|
|
285
|
+
...
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
`claim` records where the caller's working copy lives, so a claim made by hand is conflict-checkable by the OpenCode guard too. The intent file is at schema v3: it also holds a bounded journal of claim and release events. v1 and v2 files are read and upgraded on the next write (their journal starts at sequence 1), but an older portzilla binary cannot read a v3 file and must be upgraded before sharing a data directory. Invalid TTLs (outside 1–86400 seconds) are refused. Full flags, exit codes and JSON shapes → **[docs/CLI.md](docs/CLI.md#file-intents)**.
|
|
289
|
+
|
|
290
|
+
Limits, stated plainly: OpenCode and Claude Code enforce automatically; every other harness depends on the agent calling the MCP tools. The conflict proof runs `git merge-file`, so it needs git and both working copies on the same machine.
|
|
291
|
+
|
|
292
|
+
One consequence worth knowing: ownership is per *session*, and every `opencode run` invocation is a new session. In the TUI a conversation keeps its session for its whole life, but scripted runs block each other on the same file until the TTL lapses. `portzilla intent ls` shows the holder and `portzilla intent release <path> --session <id>` frees it immediately.
|
|
293
|
+
|
|
294
|
+
## Environment slots
|
|
295
|
+
|
|
296
|
+
Ports and files are not the only shared resources: two worktrees of one project also collide on the database they both point at and on the `target/` directory Cargo serialises behind its lock.
|
|
297
|
+
|
|
298
|
+
A **slot** gives one worktree its own ports, cache directories, `.env.portzilla`, and — through commands you configure — its own database:
|
|
299
|
+
|
|
300
|
+
```console
|
|
301
|
+
$ portzilla slot up auth
|
|
302
|
+
$ portzilla slot run auth -- npm test
|
|
303
|
+
$ portzilla slot down auth
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
Configured in `portzilla.toml` at the worktree root; `up` is transactional and rolls back completely on failure; `down` is retryable and refuses to destroy a database it could not deprovision. No daemon, no containers, and your credentials never pass through Portzilla.
|
|
307
|
+
|
|
308
|
+
Full reference, including SQLite and Postgres recipes → **[docs/SLOTS.md](docs/SLOTS.md)**.
|
|
309
|
+
|
|
226
310
|
## Data file & config
|
|
227
311
|
|
|
228
|
-
Resolution order: `PORTZILLA_DATA_DIR` → `$XDG_DATA_HOME/portzilla` → `~/.local/share/portzilla`.
|
|
312
|
+
Resolution order: `PORTZILLA_DATA_DIR` → `$XDG_DATA_HOME/portzilla` → `~/.local/share/portzilla`. Three independent stores, each written atomically behind its own lock: `leases.json` (leases plus the port/guard journal), `intents.json` (file claims plus their journal), and `slots.json` (environment slots). No store is shared with another, so a corrupt or locked file never takes the others down with it.
|
|
229
313
|
|
|
230
314
|
`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)**.
|
|
231
315
|
|