portzilla 0.5.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 +62 -14
- 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">
|
|
@@ -16,11 +16,16 @@
|
|
|
16
16
|
[](https://m8ven.ai/mcp/011010-portzilla-qdocjc?s=readme)
|
|
17
17
|
</p>
|
|
18
18
|
|
|
19
|
-
> 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**.
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
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.
|
|
24
29
|
|
|
25
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.
|
|
26
31
|
|
|
@@ -35,7 +40,10 @@ Port allocators and proxies such as [Portless](https://portless.sh) solve addres
|
|
|
35
40
|
- [Agent skill](#agent-skill)
|
|
36
41
|
- [Watch mode](#watch-mode)
|
|
37
42
|
- [MCP server](#mcp-server)
|
|
43
|
+
- [Audit history](#audit-history)
|
|
38
44
|
- [Kill guard](#kill-guard)
|
|
45
|
+
- [File intents](#file-intents)
|
|
46
|
+
- [Environment slots](#environment-slots)
|
|
39
47
|
- [Data file & config](#data-file--config)
|
|
40
48
|
- [Limitations](#limitations)
|
|
41
49
|
|
|
@@ -105,7 +113,7 @@ $ cargo install --path .
|
|
|
105
113
|
```console
|
|
106
114
|
$ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | sh
|
|
107
115
|
# specific version / directory:
|
|
108
|
-
$ 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
|
|
109
117
|
```
|
|
110
118
|
|
|
111
119
|
**npm** (same native binary):
|
|
@@ -126,8 +134,14 @@ Binaries for Linux x86_64/ARM64, macOS Intel/Apple Silicon, Windows x86_64/ARM64
|
|
|
126
134
|
| `portzilla prune` | Remove all leases whose PID is dead |
|
|
127
135
|
| `portzilla run <PORT> --tag <TAG> [--session <S>] -- <cmd...>` | Claim a port and run a server with it; the lease follows the child PID |
|
|
128
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 |
|
|
129
143
|
|
|
130
|
-
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)**.
|
|
131
145
|
|
|
132
146
|
## Agent skill
|
|
133
147
|
|
|
@@ -189,7 +203,9 @@ For agents with MCP access (Claude Code, etc.) — typed JSON in/out instead of
|
|
|
189
203
|
$ claude mcp add portzilla -- portzilla serve --mcp
|
|
190
204
|
```
|
|
191
205
|
|
|
192
|
-
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.
|
|
193
209
|
|
|
194
210
|
## Audit history
|
|
195
211
|
|
|
@@ -203,6 +219,8 @@ $ portzilla history clear
|
|
|
203
219
|
|
|
204
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)**.
|
|
205
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
|
+
|
|
206
224
|
## Kill guard
|
|
207
225
|
|
|
208
226
|
Makes *checking ownership the default* — blocks `kill` commands that would kill another session's live leased process.
|
|
@@ -211,7 +229,7 @@ Recognizes `kill <pid>`, `pkill`/`killall`, `lsof -ti:<port> | xargs kill`, `fus
|
|
|
211
229
|
|
|
212
230
|
| Harness | Hook | Deny reaches model? | Own-lease? |
|
|
213
231
|
|---------|------|---------------------|------------|
|
|
214
|
-
| **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`) |
|
|
215
233
|
| **Cursor** | `beforeShellExecution` — `portzilla hook cursor` | Likely (`agent_message`) | No |
|
|
216
234
|
| **Gemini CLI** | `BeforeTool` — `portzilla hook gemini` | Yes (Deny), no Warn channel | No |
|
|
217
235
|
| **Codex CLI** | `PreToolUse` — `portzilla hook codex` | Yes (Deny + Warn via `additionalContext`) | No |
|
|
@@ -224,11 +242,19 @@ Setup: `portzilla init <harness>` prints the snippet to add — never writes fil
|
|
|
224
242
|
|
|
225
243
|
Full harness setup, `sh -c` unwrapping rules, and fail-open/closed semantics → **[docs/GUARD.md](docs/GUARD.md)**.
|
|
226
244
|
|
|
227
|
-
### File intents
|
|
245
|
+
### File intents
|
|
228
246
|
|
|
229
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.
|
|
230
248
|
|
|
231
|
-
|
|
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:
|
|
232
258
|
|
|
233
259
|
- The first session to edit a file claims it for 30 minutes (`PORTZILLA_INTENT_TTL_SECS` overrides the window).
|
|
234
260
|
- A session that edits it again refreshes its own claim.
|
|
@@ -253,15 +279,37 @@ KEY SESSION AGE EXPIRES
|
|
|
253
279
|
|
|
254
280
|
$ portzilla intent release src/auth.rs --session "$CLAUDE_CODE_SESSION_ID"
|
|
255
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
|
|
256
304
|
```
|
|
257
305
|
|
|
258
|
-
`
|
|
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.
|
|
259
307
|
|
|
260
|
-
|
|
308
|
+
Full reference, including SQLite and Postgres recipes → **[docs/SLOTS.md](docs/SLOTS.md)**.
|
|
261
309
|
|
|
262
310
|
## Data file & config
|
|
263
311
|
|
|
264
|
-
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.
|
|
265
313
|
|
|
266
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)**.
|
|
267
315
|
|