Rebuild: strip the agent harness, pivot to a tmux plugin - #22
Closed
apriendeau wants to merge 3 commits into
Closed
apriendeau wants to merge 3 commits into
apriendeau wants to merge 3 commits into
Conversation
Replaces the RPC/provider agent harness with the design for a tmux plugin
that spawns isolated coding-agent instances in a polyglot monorepo.
Removed:
- src/{commands,http,otel,plugin,providers,remote,rpc,sdk,session,shared,
store,tools,tui,config}, src/crash.rs — superseded
- examples/plugins and the cargo workspace around them
- beads: .beads/, bd hooks in .claude/settings.json, bd-init recipe,
gitignore entries, and the tracker sections of CLAUDE.md / AGENTS.md.
Work is tracked in Jira and Linear; the repo carries no local tracker.
- DESIGN.md and SPAWN_AGENT_SPEC.md, both superseded by the new DESIGN.md
Kept:
- src/worktree.rs and its tests — create/remove/list/diff/merge, standalone
and directly reusable by the new design
Added:
- DESIGN.md: full design, collision matrix, open questions, sequencing
- src/main.rs: clap skeleton for menu-spec/new/done/discard, all unimplemented
Cargo.toml drops ratatui, crossterm, reqwest, syntect and the rest of the
harness dependencies. just check passes.
- drop the Miri job: no unsafe remains, libc is gone, and Miri cannot spawn the git subprocesses worktree_tests depends on - drop the crates.io publish job: TPM is the distribution channel now, and it called the deleted 'just publish' recipe - drop the Windows release target: tmux is unix-only - run CI on macOS as well as Linux; clonefile behaviour is macOS-specific and the primary target - configure a git identity in CI so worktree_tests can commit - release notes now document TPM install instead of cargo install Release asset names are the contract with phx.tmux, which downloads the matching binary on first load. Noted inline.
Tested against bun 1.3.14 on APFS with a two-package workspace. Bun 1.3 uses the isolated linker, not hoisting: a content-addressed node_modules/.bun store plus per-package node_modules of relative symlinks. Two findings that change the design: - every symlink bun writes is relative, so cp -Rc into a worktree is safe -- verified that a worktree resolves @acme/core to its own packages/core while the primary still resolves to its own, and that no symlink under the worktree escapes it - deps live in per-package node_modules, not just the root, so the clone list must cover packages/*/node_modules or the worktree resolves nothing Also downgrades open question 1: bun install against an already-correct tree took 7ms, so reconciling unconditionally after clone is close to free and beats hashing lockfiles. Still open for Rust and codegen. Flags what is still unverified: the toy case has a handful of symlinks where a real workspace has tens of thousands, and cp -Rc recreates each one individually. Needs measuring against the real monorepo.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Throws out the RPC/provider agent harness and repoints the repo at a much smaller tool: a
tmux plugin that spawns isolated coding-agent instances in a polyglot monorepo.
41,319 deletions, 647 insertions. Rust goes from ~34k lines to 538.
Why
The harness was solving model orchestration. The actual problem is running several agent
CLIs (Claude Code, Codex, Grok, whatever) in parallel against one monorepo without them
colliding — and the parts of that worth building are worktree lifecycle and environment
materialization, not panes or provider APIs.
tmux already owns panes, input, resize, scrollback, and detach/reattach.
opensessions already owns the sidebar and
agent-state display. Neither materializes a usable instance of a monorepo, and that gap is
the whole product.
Design
Full write-up in
DESIGN.md. Two properties are load-bearing:with a lifecycle.
@phx_worktree,@phx_branch, …) and the window id is the primary key. No registry file, nothing to desync.Shape is a
phx.tmuxshim binding four keys (new,done,discard,rename) plus asmall binary those bindings invoke. Arguments arrive via tmux format substitutions; there is
no human-facing CLI.
The core is materialization — APFS
clonefilefornode_modulesandtarget, copied.envand MCP config, and per-instance env for ports,COMPOSE_PROJECT_NAME, andsccache.Without copy-on-write cloning, worktree-per-agent isn't viable on a real monorepo.
Removed
src/modules pluscrash.rsDESIGN.mdandSPAWN_AGENT_SPEC.md(superseded), plugin/rpc/miri justfile recipes.beads/, thebd primeSessionStart and PreCompact hooks, thebd-initrecipe, gitignore entries, and the tracker sections ofCLAUDE.md/AGENTS.md.Work is tracked in Jira and Linear; the repo carries no local tracker. This also removes
the old mandatory-push session protocol.
Kept
src/worktree.rsand its tests — create/remove/list/diff/merge, zero internal dependencies,all six tests still green. It maps directly onto the new design.
CI
unsaferemains, and Miri can't spawn thegitsubprocesses thetests need
clonefileis macOS-specificphx-<target>.tar.gzname — that's the contract withphx.tmux,which downloads a binary on first load
Not in this PR
src/main.rsis a clap skeleton; every subcommand returns "not implemented". PerDESIGN.md§11 the next step ismaterializestandalone, proven against a real monorepo —that's where all the risk sits. Four open questions are tracked in §9, the sharpest being
clone freshness when lockfiles drift.