Documentation snapshot for v0.3.0

This page reproduces the project README from the v0.3.0 release. It is in English.

crossweave

Your agents run as parallel warp threads. crossweave is the weft — the cross-thread that binds them so the fabric holds together.

crossweave is a local-first tool that makes running many AI coding agents on one repository safe and mergeable. It is not a coding agent — it's the layer that sits above Claude Code, Cursor Agent, and any ACP-compatible agent, running each one in its own git worktree while a background daemon:

isolates runtime, not just files — separate ports, DB, Docker, cache per session, not just separate working directories;
warns at write time — the Collision Radar flags two sessions editing the same file/symbol before it becomes a merge conflict;
closes the loop — the Convergence Engine trial-merges sessions against each other in the background, so cw land tells you what's safe to merge and in what order, instead of "create a staging branch by hand and pray";
makes disk and cost visible — a live TUI dashboard, budget/burn tracking, and desktop notifications for collisions, blocked writes, land results, and convergence state changes.

See docs/superpowers/specs/2026-08-09-crossweave-design.md for the full design and the milestone-by-milestone rollout.

Status

Core loop (workspace/session management, worktree isolation, Collision Radar, Convergence Engine, Safe Mode enforcement, budget tracking, push notifications, distribution/self-update, live TUI dashboard) is built, tested, and released — v0.1.0 is the current published version.

[!NOTE] Interactive TTY testing of the TUI (cw tui) has been reviewed but not yet manually exercised end-to-end by a human. Known gaps are tracked in docs/superpowers/specs/2026-08-14-known-limitations-digest.md (the short version — start here) and per-milestone in docs/superpowers/specs/*-known-limitations.md — worth a skim before you lean on crossweave for anything you'd be upset to lose.

Requirements


Runtime	Bun 1.3.13+ (earlier 1.3.x has a unix-socket bug that lets a second daemon steal a live one's socket; 1.3.12 itself truncates the code signature on `bun build --compile` macOS output, which gets the binary SIGKILLed on launch)
OS	macOS or Linux (Bun's pty support is POSIX-only; Windows is not a V1 target)
VCS	git
Optional	ripgrep (`rg`) — Collision Radar's symbol-reference check degrades silently without it

Install

curl -fsSL https://raw.githubusercontent.com/NMHx2005/crossweave/main/install.sh | sh

Installs cw/cwd to ~/.local/bin for macOS (arm64/x64) and Linux (x64) — see install.sh at the repo root for exactly what it does (checksum-verified download, no sudo, no shell rc file edits).

cw checks for a newer version in the background (cached, at most once a day) and tells you to run cw update when one exists — never installs anything without you running that command. Turn it off with cw config update-check off.

From source (for crossweave's own development)

git clone https://github.com/NMHx2005/crossweave crossweave
cd crossweave
bun install
bun run scripts/build.ts   # produces dist/cw and dist/cwd

Quickstart

cd your-project        # any git repo
cw init                # create/attach this repo's crossweave workspace

cw session new --name alice --agent claude   # creates the session (its worktree and branch)
cw session new --name bob   --agent claude

cw session attach alice     # starts the agent if needed; Ctrl-] to detach, agent keeps running
cw session start alice      # start the agent without attaching
cw session stop alice       # stop the agent, keep the session resumable

[!TIP] Run cw tui in a separate terminal to watch both sessions live — session list, convergence matrix, and a real-time collision/notification feed in one dashboard.

Agents

`--agent`	Safe Mode tier	How it runs
`claude` (default)	T2 — blocks before the write	Claude Code, through its `PreToolUse` hook
`cursor`	T1 — blocks before the write	ACP. Current `cursor-agent` builds (2026.08+) dropped ACP, so this kind fails fast with a clear error instead of hanging — it no longer runs at all
`cursor-print`	T3 — advisory only	`cursor-agent --print --output-format stream-json`; no permission interception

A session is always reported at its real tier — cw session list, the desktop rail, and the session banner never present an advisory session as enforced.

While both sessions work, crossweave's daemon is already:

indexing every file+symbol each session touches (Collision Radar) and warning both sessions the moment they edit the same symbol;
trial-merging their branches against each other in the background (Convergence Engine).

Check what's safe to merge:

cw converge status      # pairwise conflict matrix + recommended merge order
cw land all             # land every conflict-free session, in that order

Other everyday commands:

Command	What it does
`cw tui`	Live dashboard — sessions, convergence, radar feed
`cw session list`	What's running, budget spent, status
`cw blame <path>:<line>`	Which session committed this line
`cw gc`	Reclaim worktrees/branches from ended sessions
`cw config notify off`	Mute desktop notifications (or `--event <kind>`)
`cw config trust`	Trust `converge.testCommand` for this workspace

Full command tree: cw --help, and cw <command> --help for any subcommand.

Cockpit (desktop)

For daily use, crossweave Cockpit is an Electron thin client over cwd — real xterm panes, an attention rail (working / needs-you / blocked / landability), and land selected / land all from the UI. Same daemon and evidence gate as the CLI; the app never spawns agents itself.


v1 platform	macOS arm64 only (`macOS-only-v1`)
Windows / Linux cockpit	Deferred until `cwd` is portable on those OSes
Design	`docs/superpowers/specs/2026-09-17-cockpit-design-system.md` — one token layer (`apps/cockpit/src/ui/tokens.ts`) shared by the chrome and the panes
Dev	`cd apps/cockpit && bun install && bun run dev`
Package	`cd apps/cockpit && bun run dist:mac` — see `apps/cockpit/README.md`
Design	`docs/superpowers/specs/2026-09-16-cockpit-electron-design.md`

Configuration

Per-repo settings live in crossweave.config.json at the repo root (created by cw init) — Safe Mode tier, budget defaults, notification preferences, and converge.testCommand (must be explicitly trusted via cw config trust before crossweave will run it — it's arbitrary shell).

OS-level session sandbox

Safe Mode intercepts what an agent reports about its tool calls, so a write made through a shell or a subprocess slips past every tier. The sandbox closes that by confining the session process itself:

{
  "sandbox": {
    "enabled": true,   // default; runs each session under an OS boundary
    "network": false   // default; opt in when the session needs the network
  }
}

On macOS each session spawns under sandbox-exec with a generated seatbelt profile: it may write inside its own worktree and its private temp dir, and nowhere else — not the main checkout, not another session's worktree, not $HOME, not .git/config or hooks. Commits still work, because the profile grants exactly the object/ref/log shapes git commit writes in the shared .git a linked worktree commits through. Network is denied unless sandbox.network is true.

Where no provider exists the session runs unconfined and says so: the daemon logs runs WITHOUT an OS sandbox (<reason>) and the CLI keeps printing the tier with its real coverage. Linux (bubblewrap) is specified but not yet built — see docs/superpowers/specs/2026-09-18-os-sandbox-design.md.

Contributing / development

bun test           # full suite
bun run typecheck  # tsc --noEmit
bun run build      # dist/cw, dist/cwd

See docs/superpowers/plans/ and docs/superpowers/specs/ for how each milestone was designed and implemented.

License

MIT