This is the full developer documentation for Weaver # Weaver > Shared situational awareness for multiple coding agents working in the same repo. Shared awareness for coding agents working in the same repo — who’s active, what’s claimed, what’s been learned. Claude Code, Codex, OpenCode, Pi: one small CLI over a local SQLite store, and they stop clobbering each other. ``` $ weaver status 3 other active sessions claude-code refactor the auth module 12s ago codex add a Google OAuth provider just now opencode backfill auth unit tests 2m ago ⚠ src/auth/** claimed by claude-code — coordinate or work elsewhere ``` ```sh curl -fsSL https://raw.githubusercontent.com/sean35mm/weaver/main/install.sh | sh ``` One self-contained binary for macOS and Linux — no Node, no server, no cloud account. Everything stays on your machine: a local SQLite file per repo, no telemetry, nothing about you or your code ever sent over the network. [Get started](/weaver/getting-started/install/) · [How it works](/weaver/concepts/how-it-works/) · [GitHub](https://github.com/sean35mm/weaver) # Changelog > Release history for Weaver, generated from the project changelog. All notable changes to this project are documented here. This project adheres to [Semantic Versioning](https://semver.org/) and the format is based on [Keep a Changelog](https://keepachangelog.com/). During `0.x`, minor versions may include breaking changes. This file is maintained automatically by release-please. ## [0.10.1](https://github.com/sean35mm/weaver/compare/v0.10.0...v0.10.1) (2026-06-11) [Section titled “0.10.1 (2026-06-11)”](#0101-2026-06-11) ### Bug Fixes [Section titled “Bug Fixes”](#bug-fixes) * resolve harness labels via ancestry and render explicit session names ([0903c34](https://github.com/sean35mm/weaver/commit/0903c34d6eaf805753a2dc35930edc9c5a2c9476)) ## [0.10.0](https://github.com/sean35mm/weaver/compare/v0.9.0...v0.10.0) (2026-06-09) [Section titled “0.10.0 (2026-06-09)”](#0100-2026-06-09) ### Features [Section titled “Features”](#features) * add claude code hooks for structural, advisory coordination ([b314b94](https://github.com/sean35mm/weaver/commit/b314b9461ea78dac55dc55b35a18b1ffcb81891a)) * add weaver forget for agent-driven note curation ([dc74274](https://github.com/sean35mm/weaver/commit/dc7427435f8ba90d607b4f2e7e040848fcad4d28)) * clarify init scopes and automatic store creation ([04a976d](https://github.com/sean35mm/weaver/commit/04a976dae4ab2e9f7a36c6bf95a33f7a5d26d299)) * complete note lifecycle with ids and superseded filtering ([a1ad1a2](https://github.com/sean35mm/weaver/commit/a1ad1a241db3c31710054d1987ec2decd4346736)) ### Bug Fixes [Section titled “Bug Fixes”](#bug-fixes-1) * preserve user hooks in shared matcher groups, reject conflicting init hook flags ([933010f](https://github.com/sean35mm/weaver/commit/933010fbc2374d6ba7ba39375ee4cc83ac499287)) * rate-limit repeated pre-edit advisories ([1aaaffc](https://github.com/sean35mm/weaver/commit/1aaaffc32014ea08225f90e94cd14acc22a8e20c)) * surface unpinned notes in quiet repos, honor tuned ttl in doctor, stop junk store creation ([0102fbd](https://github.com/sean35mm/weaver/commit/0102fbdf8242a0d7a210512ac9bccf4d5044cd82)) ## [0.9.0](https://github.com/sean35mm/weaver/compare/v0.8.0...v0.9.0) (2026-06-08) [Section titled “0.9.0 (2026-06-08)”](#090-2026-06-08) ### Features [Section titled “Features”](#features-1) * add global init instruction scope ([0b7312b](https://github.com/sean35mm/weaver/commit/0b7312bb536912b7975f31d59aed86b6a27acbd1)) ## [0.8.0](https://github.com/sean35mm/weaver/compare/v0.7.0...v0.8.0) (2026-06-05) [Section titled “0.8.0 (2026-06-05)”](#080-2026-06-05) ### Features [Section titled “Features”](#features-2) * improve terminal output layout ([a96ef65](https://github.com/sean35mm/weaver/commit/a96ef654fae7bf63a89e95296af0ad8297a892a9)) ## [0.7.0](https://github.com/sean35mm/weaver/compare/v0.6.0...v0.7.0) (2026-06-05) [Section titled “0.7.0 (2026-06-05)”](#070-2026-06-05) ### Features [Section titled “Features”](#features-3) * add soft terminal colors ([e9c4e03](https://github.com/sean35mm/weaver/commit/e9c4e03d56a6da0d0425324caf2f69257bab4442)) ## [0.6.0](https://github.com/sean35mm/weaver/compare/v0.5.1...v0.6.0) (2026-06-05) [Section titled “0.6.0 (2026-06-05)”](#060-2026-06-05) ### Features [Section titled “Features”](#features-4) * add bounded preflight checks ([c03ccfc](https://github.com/sean35mm/weaver/commit/c03ccfc3035522538f3ff46cbcb578441a22ef52)) ## [0.5.1](https://github.com/sean35mm/weaver/compare/v0.5.0...v0.5.1) (2026-06-02) [Section titled “0.5.1 (2026-06-02)”](#051-2026-06-02) ### Bug Fixes [Section titled “Bug Fixes”](#bug-fixes-2) * harden release and coordination flows ([f6cfd1f](https://github.com/sean35mm/weaver/commit/f6cfd1f3b0fc8a741c34b6a4f56814478f246f61)) ## [0.5.0](https://github.com/sean35mm/weaver/compare/v0.4.0...v0.5.0) (2026-06-01) [Section titled “0.5.0 (2026-06-01)”](#050-2026-06-01) ### Features [Section titled “Features”](#features-5) * **docs:** add roadmap page, split hero, and font system ([50bed26](https://github.com/sean35mm/weaver/commit/50bed266f5afa9fe37965662753a287360840bee)) ## [0.4.0](https://github.com/sean35mm/weaver/compare/v0.3.0...v0.4.0) (2026-06-01) [Section titled “0.4.0 (2026-06-01)”](#040-2026-06-01) ### Features [Section titled “Features”](#features-6) * 15-minute default session TTL and heartbeat refresh on check ([b99aeb9](https://github.com/sean35mm/weaver/commit/b99aeb9995e7995a7fd08335518f6b48cc7c440a)) ## [0.3.0](https://github.com/sean35mm/weaver/compare/v0.2.0...v0.3.0) (2026-06-01) [Section titled “0.3.0 (2026-06-01)”](#030-2026-06-01) ### Features [Section titled “Features”](#features-7) * add ‘weaver uninstall’ command ([268f15c](https://github.com/sean35mm/weaver/commit/268f15c49ae7be8928bb0813c3e5cbf64df3276c)) ## [0.2.0](https://github.com/sean35mm/weaver/compare/v0.1.0...v0.2.0) (2026-06-01) [Section titled “0.2.0 (2026-06-01)”](#020-2026-06-01) ### Features [Section titled “Features”](#features-8) * add ‘weaver upgrade’ (self-updating binary) and make curl the primary install ([8b6d37d](https://github.com/sean35mm/weaver/commit/8b6d37d8cf6935bad27d310448b7778a990fc21c)) ## 0.1.0 (2026-06-01) [Section titled “0.1.0 (2026-06-01)”](#010-2026-06-01) Initial release — CLI-first coordination layer for multiple coding agents: store + identity ladder, the full verb set, three-tier conflict detection, lifecycle commands (`init`/`disable`/`enable`/`deinit`), tunable config, and the `dashboard`/`watch` viewers. # The conflict model > How Weaver detects and surfaces conflicts — three tiers, advisory claims, and a resolution playbook. **Weaver never blocks an edit. It surfaces; the agent decides.** Enforcement would fight the agent, so coordination happens through visibility. ## Three tiers [Section titled “Three tiers”](#three-tiers) When an agent runs `weaver check ` (or `weaver claim `), Weaver compares the target against the live store and reports the highest matching tier. Globs match by intersection/containment, so `src/auth/login.ts` matches a `src/auth/**` claim. | Tier | Condition | Meaning | | --------- | -------------------------------------------------------------------- | ------------------- | | **Hard** | path matches an **active claim** held by a different, *live* session | ⚠️ coordinate first | | **Soft** | no claim, but a live session’s **recent activity** touched the area | 👀 heads-up | | **Stale** | a claim exists but its holder is past TTL / expired | ℹ️ treat as free | | **Clear** | nothing matches (or it’s your own session) | ✅ proceed | Crucially, claims held by sessions that have gone stale (e.g. a crashed agent) are **not** shown as active — they downgrade to `stale` and the area is free. ## What `check` returns [Section titled “What check returns”](#what-check-returns) A non-zero exit code plus the *context* needed to decide — the other session’s intent, claim reason, recent activity, and relevant notes — not just “denied”: ```plaintext ⚠ CONFLICT (active claim) on this area: • claude-code#alice — refactor the auth module to use AuthService claim: src/auth/** — rewriting token refresh (12s ago) active 12s ago → coordinate, work elsewhere, or ask the user how to split. Don't silently overwrite. ``` `weaver claim` behaves the same on overlap: it still records your (co-)claim, but prints the conflict and exits non-zero so you stop and coordinate. For commit, push, and PR workflows, use `weaver preflight` instead of polling `status`. Preflight runs once, checks only relevant paths, and never waits for another session to run `done`. A soft/hard result means the agent should ask the user whether to continue, wait briefly, or coordinate first. ## The resolution playbook [Section titled “The resolution playbook”](#the-resolution-playbook) This is what agents are instructed to do on a conflict: ```plaintext 1. READ the context (intent + reason + recent activity + notes). 2. Can I do OTHER useful work that doesn't overlap? → reroute, re-check later. (default) 3. Is the overlap benign (different files)? → proceed, but `weaver log` it. 4. Blocked & need it? → `weaver note` your intent, then ASK THE USER how to split. 5. NEVER silently stomp. Always record activity. 6. NEVER silently wait/poll during commit/push/PR; ask the user for a decision. ``` ## Advisory co-claims [Section titled “Advisory co-claims”](#advisory-co-claims) Overlapping claims are **allowed** and surfaced; agents resolve socially with the human as the arbiter. There’s no exclusive locking — it avoids deadlocks and claim races, and keeps Weaver from asserting false authority. # How it works > The mental model behind Weaver — a shared whiteboard for agents, built on four primitives. ## The mental model: a shared whiteboard [Section titled “The mental model: a shared whiteboard”](#the-mental-model-a-shared-whiteboard) Think of Weaver as a **whiteboard in a team room**, not a chat protocol. Agents glance at the board when they start, post what they’re working on, and check it before grabbing a file. This is **stigmergy** — coordination *through a shared environment* rather than direct messaging — which is why a passive local store (no server, no daemon) is enough. Everything reduces to **four primitives**: | Primitive | What it is | Example | | ------------ | ------------------------------------- | ----------------------------------------------------- | | **Presence** | who’s active now, and their intent | `claude-code · "refactor auth"`, 10s ago | | **Claims** | soft, advisory locks on file areas | `claude-code claims src/auth/** — "rewriting tokens"` | | **Notes** | durable learnings, scoped to the repo | `"integration tests need docker pg on :5433"` | | **Activity** | a time-ordered log of what happened | `codex edited src/api/users.ts — "added pagination"` | Every command an agent runs is one of: *announce presence*, *claim/release an area*, *leave a note*, *log activity*, or *read the current picture*. ## A participant is a session, not a tool [Section titled “A participant is a session, not a tool”](#a-participant-is-a-session-not-a-tool) The unit of coordination is a **session**, not a harness. Two Claude Code windows + three Codex sessions on one repo are **five participants**, and each sees the other four. Harness brand (`claude-code`, `codex`, …) is just a label. See [Coordinating many agents](/weaver/guides/multiple-agents/) for how identity is resolved. ## Where the data lives [Section titled “Where the data lives”](#where-the-data-lives) A single local SQLite database, keyed by the repo’s identity (its git remote, falling back to the root-commit hash), stored under `~/.weaver/`. Because it’s keyed by the *repo* — not the directory — every window **and** every git worktree of the same repo share one commons. There’s no background process. Liveness is computed lazily: each command updates the caller’s heartbeat (and `weaver check` refreshes it too), and reads treat anything past a TTL (\~15 min) as stale. The store is self-healing — a crashed agent simply ages out. ## Everything stays on your machine [Section titled “Everything stays on your machine”](#everything-stays-on-your-machine) Weaver is local by design, and that’s a guarantee, not an optimization: * **All data is local.** Sessions, claims, notes, activity — everything lives in plain SQLite files under `~/.weaver/` on your machine. You can open them, back them up, or delete them. * **Nothing goes over the network.** Weaver sends no telemetry, requires no account, and never transmits anything about you, your repo, or your agents’ activity. The *only* network call it ever makes is `weaver upgrade` (and the install script) **downloading** its own binary from GitHub releases — an ordinary fetch that carries no user data. * **The dashboard is loopback-only.** `weaver dashboard` binds `127.0.0.1` and is read-only; it’s a window for you, not a service for the internet. Your agents’ coordination chatter — intents, claim reasons, repo learnings — can be sensitive. It never leaves the machine it was written on. ## Advisory, never blocking [Section titled “Advisory, never blocking”](#advisory-never-blocking) Weaver **never blocks an edit**. Claims are advisory: it surfaces “someone’s here” and the agent decides. Enforcement would fight the agent and break the fast, CLI-first flow. Git remains the source of truth for actual file contents — Weaver is the coordination layer *on top*. See the [conflict model](/weaver/concepts/conflicts/) for how conflicts are surfaced and resolved. # Why a CLI, not an MCP server? > Why Weaver uses shell commands and a local store instead of making coordination depend on an MCP server. Weaver is a CLI on purpose. It needs to work across Claude Code, Codex, OpenCode, Pi, human terminals, and any future agent harness that can run a shell command. A CLI is the shared interface they already have. An MCP server can be useful for tool integrations, but it is the wrong source of truth for Weaver’s core coordination path. ## The coordination path must be universal [Section titled “The coordination path must be universal”](#the-coordination-path-must-be-universal) Weaver’s job is to answer simple repo-local questions: * Who else is active? * What are they working on? * Which areas are claimed? * What has been learned about this repo? Every agent can ask those questions with commands like `weaver status`, `weaver claim`, and `weaver check`. That matters because multi-agent work is usually mixed-tool work. If coordination requires an MCP client, an MCP server, or per-harness configuration, the agents that are missing that setup become invisible. A shell command is the lowest common denominator, but not in a weak sense. It is scriptable, observable, works in sandboxes, works from CI, works for humans, and is easy for agents to quote exactly in their instructions. See [Using Weaver from an agent](/weaver/guides/using-from-an-agent/) for the protocol agents follow. ## No daemon in the critical path [Section titled “No daemon in the critical path”](#no-daemon-in-the-critical-path) Weaver stores coordination state in a local SQLite database under `~/.weaver/`. Each command opens the store, reads or writes a tiny amount of state, and exits. There is no long-running coordination process to install, start, restart, authenticate, expose on a port, or keep compatible with every agent runtime. That keeps the failure model small: * If an agent crashes, its heartbeat ages out. * If a command fails, the next command can still read the store. * If no agents are running, there is no server to keep alive. * If a harness cannot run MCP tools, it can still run `weaver`. The dashboard is the exception by design: `weaver dashboard` starts a tiny local server for humans to watch the commons live. Agents do not coordinate through it, so the core system remains serverless. See the [architecture reference](/weaver/reference/architecture/) for the data model and runtime details. ## MCP would add a second coordination surface [Section titled “MCP would add a second coordination surface”](#mcp-would-add-a-second-coordination-surface) If Weaver were primarily an MCP server, every harness would need to agree on the same server configuration before coordination could start. In practice, that creates split-brain risk: * One agent talks to the MCP server. * Another agent only has shell access. * A third agent is in a sandbox that hides the configured MCP tools. * A human checks the repo from a terminal. The CLI avoids that split. Everyone reads and writes the same local store through the same commands, and git remains the source of truth for file contents. Weaver only surfaces coordination signals; it never blocks edits or replaces version control. See [the conflict model](/weaver/concepts/conflicts/) for how claims stay advisory. ## Could Weaver have MCP support later? [Section titled “Could Weaver have MCP support later?”](#could-weaver-have-mcp-support-later) Yes, but as a wrapper around the CLI and store, not as the authority. An MCP integration could make Weaver nicer inside a specific client, while `weaver status`, `weaver check`, and `weaver claim` remain the universal contract. The rule is simple: integrations can improve ergonomics, but the CLI is the coordination layer. # Contributing > How to set up, test, and contribute to Weaver. Weaver is open source (MIT) and contributions are welcome. The full guide lives in the repo: [`CONTRIBUTING.md`](https://github.com/sean35mm/weaver/blob/main/CONTRIBUTING.md). ## Quick start [Section titled “Quick start”](#quick-start) ```sh git clone https://github.com/sean35mm/weaver cd weaver npm install # dev deps + picomatch; SQLite is built into Node/Bun node src/cli.ts --help # run directly — no build needed ``` ## The bar [Section titled “The bar”](#the-bar) * Tests must pass on **both Node and Bun**: `npm test` and `npm run test:bun`. * `npm run typecheck` must be clean. * Use **Conventional Commits** (`feat:`, `fix:`, `chore:`, …) — they drive versioning and the changelog. * Keep the core **zero-runtime-dependency** where practical (`picomatch` is the only one). * Validation stays lenient at the CLI boundary — never throw a stack trace at an agent, and `check` must never crash a tool call. * The CLI is the **universal engine** — don’t add a hard dependency on any single harness. See [`AGENTS.md`](https://github.com/sean35mm/weaver/blob/main/AGENTS.md) for an orientation aimed at agents working on the repo, and [Releasing](/weaver/releasing/) for how releases are cut. # For LLMs & agents > Machine-readable entry points to the Weaver docs. These docs are built to be consumed by language models and agents, not just humans. ## Machine-readable docs [Section titled “Machine-readable docs”](#machine-readable-docs) * **[`/weaver/llms.txt`](/weaver/llms.txt)** — a concise, curated index of the documentation in the [llms.txt](https://llmstxt.org/) format: a short description plus links to every page. * **[`/weaver/llms-full.txt`](/weaver/llms-full.txt)** — the **entire documentation concatenated into one markdown file**, ideal for dropping into a model’s context or a retrieval pipeline. Every page also has clean markdown source in the repo under [`docs/src/content/docs/`](https://github.com/sean35mm/weaver/tree/main/docs/src/content/docs). ## If you’re an agent using Weaver [Section titled “If you’re an agent using Weaver”](#if-youre-an-agent-using-weaver) Read **[Using Weaver from an agent](/weaver/guides/using-from-an-agent/)** — it’s the exact protocol: the per-task loop, conflict handling, and the `--json` output shapes. The [CLI reference](/weaver/reference/commands/) lists every command with copy-paste examples. ## Design principle [Section titled “Design principle”](#design-principle) Weaver is a CLI rather than an MCP server precisely so that *any* agent can use it by running a shell command — no protocol, no server, no setup. The documentation follows the same principle: plain, structured, copy-paste-exact. # Install > Install the Weaver CLI — a single standalone binary, no Node or npm required. Weaver ships as a **single self-contained binary**. No Node, npm, or other runtime is needed to run it. ## Install [Section titled “Install”](#install) ```sh curl -fsSL https://raw.githubusercontent.com/sean35mm/weaver/main/install.sh | sh ``` This downloads the right binary for your OS/arch (macOS and Linux, arm64 and x64) into `~/.local/bin/weaver`. If that directory isn’t on your `PATH`, the installer tells you the line to add. ## Supported platforms [Section titled “Supported platforms”](#supported-platforms) * **macOS** — arm64 (Apple Silicon) and x64 * **Linux** — arm64 and x64 (glibc) * **Windows** — via **WSL2**: install inside your WSL distro and the linux binary works as-is. Native Windows isn’t supported today; it may come later if there’s demand. Verify it: ```sh weaver --version weaver --help ``` ## Upgrade [Section titled “Upgrade”](#upgrade) Weaver updates itself — no reinstall: ```sh weaver upgrade # download + replace with the latest release weaver upgrade --check # just check whether a newer version exists ``` ## Uninstall [Section titled “Uninstall”](#uninstall) ```sh weaver uninstall # removes the binary and ~/.weaver (prompts first) weaver uninstall --keep-data # remove the binary but keep your stores weaver uninstall --yes # skip the confirmation prompt ``` Any `weaver` blocks left in project or global instruction files are self-disabling; run `weaver deinit` or `weaver deinit --global` first if you want them removed. ## Running from source (contributors) [Section titled “Running from source (contributors)”](#running-from-source-contributors) If you’re hacking on Weaver itself, you can run it without installing — see [Contributing](/weaver/contributing/): ```sh node src/cli.ts --help # or: bun src/cli.ts --help ``` # Quickstart > Enable Weaver in a repo and watch two agents coordinate in about five minutes. This gets you from zero to “two agents coordinating” in a few minutes. ## 1. Install the agent instructions [Section titled “1. Install the agent instructions”](#1-install-the-agent-instructions) From the root of any git repo: ```sh weaver init ``` `init` asks where to append a short instruction block: * **Project files** (`./CLAUDE.md`, `./AGENTS.md`) — covers this repo only. Run `weaver init` again in each repo you want covered. This is the first/default choice. * **Global files** (`~/.claude/CLAUDE.md`, `~/.config/opencode/AGENTS.md`, `~/.codex/AGENTS.md`) — one-time setup that covers every repo on this machine. You never run `init` again. If you use Claude Code, `init` also offers to install [hooks](/weaver/guides/claude-code-hooks/) (default yes): Claude is then warned automatically — never blocked — before editing an area another agent is working in, and its presence refreshes on every edit. For scripts, use `weaver init --project` or `weaver init --global`, plus `--hooks` or `--no-hooks` to decide about Claude Code hooks non-interactively. There is no per-repo database setup either way: each repo’s store is created automatically the first time an agent runs a weaver command there. That’s the whole setup — **you don’t run anything else by hand.** ## 2. Use your agents normally [Section titled “2. Use your agents normally”](#2-use-your-agents-normally) Open your agents (Claude Code, Codex, OpenCode, Pi, …) in the repo as you always do. Because their instruction files now describe Weaver, they’ll run the commands themselves as they work: announce their task, claim the areas they touch, and leave notes. Try it yourself You can play any agent by hand. In two terminals: ```sh # terminal 1 — "alice" WEAVER_SESSION=alice weaver task "refactor the auth module" WEAVER_SESSION=alice weaver claim 'src/auth/**' --reason "rewriting token refresh" # terminal 2 — "bob" WEAVER_SESSION=bob weaver status # sees alice + her claim WEAVER_SESSION=bob weaver check src/auth/login.ts # ⚠ conflict, exit 1 ``` Who types what `weaver init` (step 1) is the only thing you run by hand. Your agents run `task`, `claim`, `note`, and `check` themselves. Day to day, you just run `status`, `watch`, or `dashboard` to see what they’re doing. ## 3. Watch the commons live [Section titled “3. Watch the commons live”](#3-watch-the-commons-live) ```sh weaver status # snapshot: who's active, claims, recent activity, notes weaver watch # live terminal view weaver dashboard # live web view (opens your browser) ``` ## 4. See it with sample data [Section titled “4. See it with sample data”](#4-see-it-with-sample-data) Want a populated demo without wiring up real agents? From a checkout of the repo: ```sh node scripts/demo.ts # seeds a throwaway store and prints how to view it ``` ## Turning it off [Section titled “Turning it off”](#turning-it-off) ```sh weaver disable # pause agent writes for this repo weaver enable # resume weaver deinit # remove the project instruction block (add --purge to delete the store) weaver deinit --global # remove the global instruction block ``` Next: learn [how it works](/weaver/concepts/how-it-works/) or jump to the [command reference](/weaver/reference/commands/). # Claude Code hooks > Make coordination structural — warn agents before they edit a claimed area, and keep busy agents visibly live, without anyone remembering to run a command. The instruction block asks agents to run `weaver status` and `weaver check` at the right moments — and they usually do. Hooks remove the “usually”: Claude Code itself calls Weaver around every file edit, so conflict detection and presence no longer depend on the agent remembering anything. Two hooks are installed, both **advisory** — Weaver never blocks an edit: * **PreToolUse → `weaver hook pre-edit`** — before Edit/Write/MultiEdit/NotebookEdit runs, Weaver checks the target path against other live sessions’ claims and recent activity. On an overlap it *allows* the edit but injects a warning the model sees, with the other session’s intent and claim reason — the same picture `weaver check` prints. Warnings are rate-limited: an agent deliberately working in a contested area is warned once, not on every edit — the same picture repeats at most every \~5 minutes, but a *changed* picture (a new agent, a new claim, a soft overlap turning into an active claim) warns immediately. * **PostToolUse → `weaver hook post-edit`** — after the edit, Weaver records an `edit` activity event and refreshes the session’s heartbeat. This fixes the classic gap where an agent edits heads-down for 20 minutes without running a weaver command and goes “stale” while it’s the most active session in the repo. ## Install [Section titled “Install”](#install) ```sh weaver init # interactive: prompts "Install Claude Code hooks?" (default yes) weaver init --hooks # non-interactive: install hooks explicitly weaver init --no-hooks # skip them ``` Hooks are always **project-scoped**: they’re merged into `.claude/settings.json` in the repo (regardless of whether the instruction block went to project or global files). The merge is idempotent and preserves everything else in the file — your own hooks, permissions, and any unknown keys. If the file isn’t valid JSON, Weaver refuses to touch it and tells you. The registered command is guarded: ```sh command -v weaver >/dev/null 2>&1 && weaver hook pre-edit || true ``` so the settings file is safe to commit — collaborators without Weaver installed get a silent no-op, never an error. ## Remove [Section titled “Remove”](#remove) ```sh weaver deinit # removes the instruction block AND the hook entries ``` Only Weaver’s own entries are removed; the rest of `.claude/settings.json` is untouched. ## How it stays safe [Section titled “How it stays safe”](#how-it-stays-safe) * **Never blocks**: the PreToolUse response is always `permissionDecision: "allow"`; the warning rides along as context for the model to act on. * **Never breaks the agent**: any problem — unparseable payload, missing store, path outside the repo — exits `0` silently. A hook must not be the reason an edit fails. * **Never tracks repos that didn’t opt in**: `weaver hook` opens an existing store but will not create one, and it goes quiet when the project is `weaver disable`d. * **One identity**: the hook derives the same session identity (from the payload’s `session_id`) that the agent’s own `weaver task`/`claim` commands resolve, so hook events and CLI events belong to one session — no phantom twins. ## Other harnesses [Section titled “Other harnesses”](#other-harnesses) Codex, OpenCode, and friends have different (or no) hook systems, so they coordinate through the instruction block alone for now. The CLI stays the universal engine; hooks are a Claude-Code-native accelerator on top. # Configuration > Tune Weaver's TTLs and inspect settings with the config command. Weaver works with sensible defaults; a few timing knobs are tunable per repo. ## Tunable settings [Section titled “Tunable settings”](#tunable-settings) | Key | Default | What it controls | | ------------------------- | --------------- | ------------------------------------------------------------------------------------- | | `session_ttl_seconds` | `900` (15 min) | How long after its last command (or `weaver check`) a session is considered live. | | `claim_ttl_seconds` | `1800` (30 min) | Default lifetime of a claim (refreshed on activity; override per claim with `--ttl`). | | `recent_activity_seconds` | `1200` (20 min) | The window for “recent activity” used by `status` and soft-conflict detection. | ## View and set [Section titled “View and set”](#view-and-set) ```sh weaver config # list all settings weaver config session_ttl_seconds # show one weaver config session_ttl_seconds 120 # set it (in seconds) ``` Settings are stored per repo in the local store, so different projects can have different TTLs. ## Per-claim TTL [Section titled “Per-claim TTL”](#per-claim-ttl) Override the claim lifetime for a single claim without changing the default: ```sh weaver claim 'src/auth/**' --reason "big refactor" --ttl 2h ``` `--ttl` accepts values like `90s`, `30m`, `2h`, `1d` (bounded between 1 minute and 24 hours). ## Diagnostics [Section titled “Diagnostics”](#diagnostics) `weaver doctor` prints the resolved identity, repo id, store path, runtime/binding, and enabled state — the first thing to check when something looks off. See [Troubleshooting](/weaver/reference/troubleshooting/). # Dashboard & watch > Watch the commons live — a local web dashboard or a terminal view. Two ways to watch what your agents are doing in real time. ## `weaver dashboard` — live web view [Section titled “weaver dashboard — live web view”](#weaver-dashboard--live-web-view) ```sh weaver dashboard # opens your browser; Ctrl-C to stop weaver dashboard --port 8080 weaver dashboard --no-open # don't auto-open the browser ``` It spins up a tiny local server on `127.0.0.1`, opens your browser, and renders a live view: a card per active session (harness, intent, heartbeat), the claim map, a streaming activity timeline, and the notes panel. It updates \~once a second. It’s read-only and loopback-only The dashboard server is purely a **human viewer** — agents never talk to it; they only touch the local SQLite file. It binds to `127.0.0.1` only, and it never writes. The coordination layer stays serverless. ## `weaver watch` — live terminal view [Section titled “weaver watch — live terminal view”](#weaver-watch--live-terminal-view) For the no-browser crowd, the same picture, redrawn in your terminal: ```sh weaver watch # Ctrl-C to stop ``` ```text 🧵 weaver watch — 9b649acdba00f6dd (Ctrl-C to stop) 3 other active sessions claude-code#alice refactor the auth module to use AuthService 3s ago codex#bob add a Google OAuth provider 3s ago opencode#cleo backfill auth unit tests 2m ago claims: src/auth/** claude-code#alice — rewriting token refresh tests/auth/** opencode#cleo — coverage only, won't touch src ``` ## Snapshots [Section titled “Snapshots”](#snapshots) For a one-off (and for agents), `weaver status` prints the same picture once and exits; `weaver status --json` gives structured output. # Coordinating many agents > How Weaver keeps N sessions across different harnesses aware of each other — and how identity is resolved. Weaver’s reason to exist: you can run **many agents on one repo at once** — across different tools and multiple windows — and they all stay aware of each other. ## The scenario [Section titled “The scenario”](#the-scenario) Say you have 2× Claude Code + 2× OpenCode + 3× Codex sessions, all in the same repo. That’s **seven participants**, and each must see the other six. Weaver treats every session as a distinct participant, regardless of harness or window. This works because the CLI is the **universal substrate** — every harness can run a shell command, so they all read and write the same local commons without any per-tool integration. ## How a session is identified [Section titled “How a session is identified”](#how-a-session-is-identified) Weaver resolves a stable per-session key in this order: 1. **Explicit override** — `--session ` or the `WEAVER_SESSION` env var. Always wins; useful for tests, headless runs, and any harness where the below don’t work. 2. **Harness-native session id** — a stable per-session environment variable. Known: `CLAUDE_CODE_SESSION_ID` (Claude Code), `CODEX_THREAD_ID` (Codex), and for OpenCode `OPENCODE_SESSION_ID` or `OPENCODE_RUN_ID` (set by OpenCode ≤1.16.x; v1.17.0 removed it, so newer OpenCode sessions resolve via the terminal instead). These are per-session UUIDs, so three Codex sessions get three distinct keys. 3. **Controlling terminal** — the session’s TTY, found by walking the process tree (used when there’s no session env var, e.g. Pi, or for a human running `weaver` directly). The *displayed* harness name resolves separately: environment signals first, then known harness executables found while walking the process ancestry — so a harness that exposes no env vars to subprocesses (e.g. OpenCode ≥1.17) is still labeled correctly. If none resolve, there’s **no anonymous fallback**: observer reads still work, but session-mutating commands fail with a concise hint to set `WEAVER_SESSION`. ## Supported harnesses [Section titled “Supported harnesses”](#supported-harnesses) Anything that can run a shell command works. First-class, tested targets: **Claude Code, OpenCode, Codex, Pi**. `weaver init` can write the instruction block to project files (`CLAUDE.md`, `AGENTS.md`) or global files for Claude Code, OpenCode, and Codex. Sandboxed harnesses Codex runs tool commands in a sandbox with no visible TTY or process ancestry — which is exactly why the harness-native session id (`CODEX_THREAD_ID`) is the primary signal, not the terminal. The ladder above handles this automatically. ## Worktrees [Section titled “Worktrees”](#worktrees) Because the store is keyed by repo identity (not directory), multiple **git worktrees** of the same repo share one commons — so agents in different worktrees still coordinate. # Using Weaver from an agent > The exact protocol a coding agent should follow to coordinate through Weaver. This page is written for **coding agents** (and the people configuring them). If you’re an agent reading this: follow it directly. Weaver is a local CLI. You interact with it by running shell commands. `weaver init` injects a short version of this protocol into project or global agent instruction files; this page is the full version. ## The per-task loop [Section titled “The per-task loop”](#the-per-task-loop) Run these as you work. They’re cheap and fast. ```sh # 1. At the start of a task — see who else is here. weaver status # For read-only / plan-only work, stop there. # 2. Once implementation or other writes are approved, state your intent. weaver task "refactor the auth module to use AuthService" # 3. Claim the area you'll work in (once). Advisory; surfaces overlaps. weaver claim 'src/auth/**' --reason "rewriting token refresh" # 4. Record durable learnings about this repo as you discover them. weaver note "AuthService is the new entry point — don't call jwt.* directly" # 4b. Keep the record honest: if an existing note is outdated, replace it; if it's # wrong or noise, retire it (soft, audited, reversible — a reason is required). weaver note "AuthService moved to src/core/auth" --update 12 weaver forget 17 "we no longer use docker for tests" # 5. When finished, release your claims. weaver done ``` Optional, when useful: ```sh weaver check src/auth/login.ts # is anyone else on this file? weaver log edit src/auth/login.ts "extracted refreshToken into AuthService" ``` ## Before commit, push, or PR [Section titled “Before commit, push, or PR”](#before-commit-push-or-pr) Use a bounded preflight check when available: ```sh weaver preflight --staged --operation commit weaver preflight --upstream --operation push weaver preflight --base main --operation pr ``` `preflight` checks only relevant paths, does not refresh heartbeats, and never waits. If it reports a relevant soft/hard overlap, pause and ask the user whether to continue, wait briefly, or coordinate first. Do not silently poll for another session to run `weaver done` unless the user explicitly asks you to wait. ## On a conflict [Section titled “On a conflict”](#on-a-conflict) A non-zero exit from `claim` means your claim **was recorded** and a conflict was surfaced — don’t re-run the command; coordinate instead. If `status`, `check`, or `claim` shows another **live** session in your area, read their intent * reason + recent activity, then: 1. **Prefer to work elsewhere** and re-check later (the default). 2. If the overlap is harmless (different files), proceed — and `weaver log` it. 3. If you’re blocked, `weaver note` your intent and **ask the user how to split the work**. **Never silently edit over another agent’s active area.** See the [conflict model](/weaver/concepts/conflicts/) for the tiers. ## Reading the picture as a machine [Section titled “Reading the picture as a machine”](#reading-the-picture-as-a-machine) Use `--json` for structured output you can parse: ```sh weaver status --json weaver activity --json weaver preflight --staged --json ``` `status --json` returns active sessions (`shortId`, harness, intent), active claims (pattern, reason, holder), recent activity, and notes. JSON mode always emits structured arrays; the human `status` output is the one that stays terse when nothing is relevant. Both are safe to run at the top of every task without bloating your context. ## Identity & sessions [Section titled “Identity & sessions”](#identity--sessions) Each session gets a stable key, resolved as: an explicit `WEAVER_SESSION` / `--session` override → a harness-native session id (e.g. `CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`) → the controlling terminal. If none can be resolved, observer commands (`status`, `check`, …) still work, but mutating commands fail with a hint to set `WEAVER_SESSION`. Details: [Coordinating many agents](/weaver/guides/multiple-agents/). ## Keep it tight [Section titled “Keep it tight”](#keep-it-tight) Keep reasons and notes short, specific, and **free of secrets** — other agents read them to coordinate, and the store is plaintext. # Architecture > How Weaver is built — serverless SQLite, the identity ladder, and the data model. ## Overview [Section titled “Overview”](#overview) ```plaintext agents (any harness, any session) ── weaver … ──▶ ~/.weaver/.db (SQLite, WAL) ▲ │ read-only weaver dashboard / watch (human viewer) ``` Weaver is a single CLI over a local SQLite file. Each invocation opens the file, does a tiny amount of work, and exits. **No daemon, no server, no MCP.** ## Storage [Section titled “Storage”](#storage) * **SQLite in WAL mode**, so many short-lived agent processes can write concurrently with no contention. * **Runtime-aware binding**: `bun:sqlite` under Bun, `node:sqlite` under Node — both built in, so there’s **no native dependency**. (Released binaries bundle the Bun runtime.) * Keyed by **repo identity**: the normalized git remote URL → root-commit hash → directory hash. So every window and worktree of one repo shares a store. * **Lazy liveness & retention**: no background process. Reads compute staleness from heartbeats; the activity log is pruned on write. A crashed agent ages out automatically. ## Identity ladder [Section titled “Identity ladder”](#identity-ladder) A session’s stable key is resolved as: **explicit** (`--session` / `WEAVER_SESSION`) → **harness-native session id** (`CLAUDE_CODE_SESSION_ID`, `OPENCODE_SESSION_ID` / `OPENCODE_RUN_ID`, `CODEX_THREAD_ID`) → **controlling TTY** (self or nearest ancestor). No anonymous fallback. See [Coordinating many agents](/weaver/guides/multiple-agents/). ## Data model [Section titled “Data model”](#data-model) Four tables plus a small meta table: * `sessions` — one row per participant (id, harness, intent, heartbeat, …). * `claims` — advisory, TTL’d locks on file globs (with a free-text reason). * `notes` — durable, repo-scoped learnings. * `activity` — an append-only, pruned event stream (kind, target, summary). The descriptive fields (intent, claim reason, activity summary, notes) are natural-language and agent-written — that’s what makes the picture genuinely useful for coordination rather than just collision-avoidance. ## What Weaver is not [Section titled “What Weaver is not”](#what-weaver-is-not) * **Not a VCS / merge tool.** It prevents and warns *before* an edit; git owns file contents. * **Not an MCP server.** It’s a CLI — the universal interface every harness already speaks. * **Not a daemon or cloud service.** v1 is fully local. ## Distribution [Section titled “Distribution”](#distribution) A standalone binary built with `bun build --compile` for macOS/Linux × arm64/x64, attached to each GitHub release and served by `install.sh` and `weaver upgrade`. Versioning is automated with release-please; see [Releasing](/weaver/releasing/). # CLI reference > Every Weaver command, its flags, and examples. Run `weaver --help` for a summary, or `weaver --help` where available. Commands fall into three groups: **agent** commands (register your presence), **observer** commands (read only — they never make you appear as a participant), and **lifecycle/maintenance**. ## Agent commands [Section titled “Agent commands”](#agent-commands) Run automatically *by your agents* — the `weaver init` block tells them how. You’ll rarely type these yourself, except to simulate an agent. ### `weaver task ""` [Section titled “weaver task "\"”](#weaver-task-intent) Announce what you’re working on. Sets your session’s intent. ```sh weaver task "refactor the auth module to use AuthService" ``` ### `weaver claim '' [--reason ""] [--ttl ]` [Section titled “weaver claim '\' \[--reason "\"\] \[--ttl \\]”](#weaver-claim-glob---reason-why---ttl-dur) Stake out an area you’ll work in. Advisory and TTL’d. Exits `0` when the area is clear. Exit `1` means the claim **was still recorded** but it overlaps another live session — the conflict is printed so the agent stops and coordinates. Don’t re-run the claim on exit `1`; it succeeded. ```sh weaver claim 'src/auth/**' --reason "rewriting token refresh" --ttl 2h ``` ### `weaver release ''` [Section titled “weaver release '\'”](#weaver-release-glob) Free an area you previously claimed. ### `weaver note "" [--pin] [--path

] [--tag ] [--update ]` [Section titled “weaver note "\" \[--pin\] \[--path \

\] \[--tag \\] \[--update \\]”](#weaver-note-text---pin---path-p---tag-t---update-id) Record a durable, repo-scoped learning. `--pin` surfaces it prominently in `status`. `--update ` replaces an existing note: the old note disappears from all listings and the new one takes its place (ids are shown by `weaver notes`). A pinned note stays pinned across updates unless you say otherwise. ```sh weaver note "integration tests need docker pg on :5433" --tag testing weaver note "integration tests need docker pg on :5434 since #42" --update 17 ``` ### `weaver log "

"` [Section titled “weaver log \ \ "\"”](#weaver-log-kind-path-summary) Record an activity event. `kind` is one of `edit`, `create`, `delete`, `run`, etc. (an unknown kind is recorded as `run` with a warning). ```sh weaver log edit src/auth/login.ts "extracted refreshToken into AuthService" ``` ### `weaver done` [Section titled “weaver done”](#weaver-done) End your session and release its claims. ## Observer commands [Section titled “Observer commands”](#observer-commands) The commands **you** run as a human. Read-only — they never register you as a participant. ### `weaver status [--json] [--full]` [Section titled “weaver status \[--json\] \[--full\]”](#weaver-status---json---full) The current picture: other live sessions, active claims, recent activity, and notes. **Silent when nothing is relevant.** `--json` for machine consumption; `--full` removes the caps. ### `weaver check ` [Section titled “weaver check \”](#weaver-check-path) Is anyone else working on this path/area? Exits `0` if clear, `1` on a conflict, and prints the conflicting session’s context. Observer-safe — works even without a resolved session. By default it refreshes the caller’s heartbeat if the caller already has a live session; use `--no-touch` for strict read-only checks. ### `weaver preflight [paths…|--staged|--upstream|--base ]` [Section titled “weaver preflight \[paths…|--staged|--upstream|--base \\]”](#weaver-preflight-paths--staged--upstream--base-ref) A bounded commit/push/PR risk check. It checks only the supplied or inferred paths, never polls, never waits for another session to run `done`, and never refreshes heartbeats. Relevant soft/hard overlaps are a pause signal for the agent to ask the user what to do. ```sh weaver preflight --staged --operation commit weaver preflight --upstream --operation push weaver preflight --base main --operation pr --json ``` Exit policy defaults to `--fail-on soft`: exit `1` for relevant soft or hard overlaps, `0` for clear/stale/unrelated sessions, and `2` for tooling/input errors. Use `--fail-on hard` to pause only on active claims, or `--fail-on never` for report-only automation. Human and JSON output are capped by default; `--json` includes `counts` and `truncated` metadata. Use `--full` to include every checked path and overlap. ### `weaver forget "" [--undo]` [Section titled “weaver forget \ "\" \[--undo\]”](#weaver-forget-id-why---undo) Retire a note that turned out to be wrong or has become noise. Removal is **soft, audited, and reversible**: the note disappears from `status`/`notes`/dashboard, a `forget` event (with your reason) lands in the activity feed, the reason is kept on the note itself, and `weaver forget --undo ` brings it back. A reason is required — curation always leaves a why. For learnings that are *outdated* rather than wrong, prefer `weaver note --update ` with the correction. ```sh weaver forget 12 "npm distribution was removed; this no longer applies" weaver forget --undo 12 ``` ### `weaver notes [--full] [--all]` [Section titled “weaver notes \[--full\] \[--all\]”](#weaver-notes---full---all) List durable notes with their ids (pinned first, newest first). Superseded and retired notes are hidden — only the current picture appears. `--all` shows the full curation history, marking retired notes (with their reason) and superseded ones. ### `weaver activity [--json] [--full]` [Section titled “weaver activity \[--json\] \[--full\]”](#weaver-activity---json---full) The recent activity feed across sessions. ### `weaver doctor` [Section titled “weaver doctor”](#weaver-doctor) Diagnostics: resolved session key + source, repo id, store path, runtime/binding, enabled state, active session count. ## Lifecycle & maintenance [Section titled “Lifecycle & maintenance”](#lifecycle--maintenance) ### `weaver init [--project|--global] [--hooks|--no-hooks]` [Section titled “weaver init \[--project|--global\] \[--hooks|--no-hooks\]”](#weaver-init---project--global---hooks--no-hooks) Install the agent instruction block into either project files (`./CLAUDE.md`, `./AGENTS.md`) or global files (`~/.claude/CLAUDE.md`, `~/.config/opencode/AGENTS.md`, `~/.codex/AGENTS.md`). On a TTY, `init` prompts with project files as the first/default choice. Non-interactive runs default to project files. `--project` and `--global` are mutually exclusive. `init` can also install [Claude Code hooks](/weaver/guides/claude-code-hooks/) into the repo’s `.claude/settings.json` (always project-scoped). On a TTY it asks (default yes); non-interactive runs install them only with an explicit `--hooks`. Project scope covers the current checkout only — run `init` in each repo you want covered. Global scope is a one-time setup that covers every repo where your agents read their global instruction files — no per-repo `init` is needed afterwards. In both cases there is no per-repo database setup: a repo’s store is created automatically the first time an agent runs a weaver command there. ### `weaver disable` / `weaver enable` [Section titled “weaver disable / weaver enable”](#weaver-disable--weaver-enable) Pause / resume agent writes for this repo. While disabled, mutating commands no-op quietly (reads and `done` still work). ### `weaver deinit [--project|--global] [--purge]` [Section titled “weaver deinit \[--project|--global\] \[--purge\]”](#weaver-deinit---project--global---purge) Remove the instruction block from project files by default, or from global files with `--global`. Project-scope deinit also removes Weaver’s Claude Code hook entries from `.claude/settings.json`. `--purge` also deletes the current repo’s store. ### `weaver hook ` [Section titled “weaver hook \”](#weaver-hook-pre-editpost-edit) The Claude Code hook endpoint — registered by `weaver init`, not meant to be run by hand. Reads the hook payload JSON on stdin. `pre-edit` emits an advisory warning (never a block) when the target file overlaps another live session; `post-edit` records the edit and refreshes the session’s heartbeat. Always exits `0`; problems are silently ignored so a hook can never break an agent. See [Claude Code hooks](/weaver/guides/claude-code-hooks/). ### `weaver config [ []]` [Section titled “weaver config \[\ \[\\]\]”](#weaver-config-key-seconds) View or set tunable TTLs. See [Configuration](/weaver/guides/configuration/). ### `weaver upgrade [--check]` [Section titled “weaver upgrade \[--check\]”](#weaver-upgrade---check) Update the installed binary to the latest release (`--check` only checks). See [Install](/weaver/getting-started/install/). ## Common flags [Section titled “Common flags”](#common-flags) | Flag | Applies to | Meaning | | ------------------------ | ------------------------------------------ | -------------------------------------------------------- | | `--json` | `status`, `activity`, `preflight` | machine-readable output | | `--full` | `status`, `notes`, `activity`, `preflight` | remove output caps | | `--color` | supported human output | force ANSI colors (`--color=always`, `auto`, or `never`) | | `--no-color` | supported human output | disable ANSI colors | | `--staged` | `preflight` | check staged paths | | `--upstream` | `preflight` | check `@{upstream}...HEAD` paths | | `--base` | `preflight` | check `...HEAD` paths | | `--fail-on` | `preflight` | exit threshold: `soft`, `hard`, or `never` | | `--project` | `init`, `deinit` | use project instruction files | | `--global` | `init`, `deinit` | use global instruction files | | `--hooks` / `--no-hooks` | `init` | install / skip Claude Code hooks | | `--update` | `note` | supersede an existing note by id | | `--all` | `notes` | include retired and superseded notes | | `--undo` | `forget` | restore a retired note | | `--no-touch` | `check` | do not refresh heartbeat | | `--reason` | `claim` | why you’re claiming the area | | `--ttl` | `claim` | claim lifetime (`90s`, `30m`, `2h`, `1d`) | | `--pin` | `note` | surface the note prominently | | `--session` | any | explicit session id (overrides auto-detection) | # Troubleshooting & FAQ > Common issues and how to diagnose them with weaver doctor. ## Start with `weaver doctor` [Section titled “Start with weaver doctor”](#start-with-weaver-doctor) ```sh weaver doctor ``` It prints the resolved session key + source, repo id, store path, runtime/binding, and enabled state — the fastest way to see what Weaver thinks is going on. ## Common issues [Section titled “Common issues”](#common-issues) ### ”no session identity” when running an agent command [Section titled “”no session identity” when running an agent command”](#no-session-identity-when-running-an-agent-command) The mutating commands (`task`, `claim`, …) need a stable session identity. If your harness doesn’t expose one and there’s no TTY, set it explicitly: ```sh export WEAVER_SESSION=my-session ``` Observer commands (`status`, `check`) work without identity. ### Agents aren’t coordinating [Section titled “Agents aren’t coordinating”](#agents-arent-coordinating) * Did you run `weaver init` in the repo? Check that the block exists in the project or global instruction files you selected. * Is it disabled? `weaver doctor` shows `enabled`. Re-enable with `weaver enable`. * Are the agents actually in the **same repo**? `weaver doctor` shows the `repo` id — it should match across sessions. * For Claude Code, install [hooks](/weaver/guides/claude-code-hooks/) (`weaver init --hooks`) — coordination then happens around every edit automatically instead of relying on the agent remembering to run weaver commands. Hooks need a weaver binary new enough to have the `hook` command (`weaver upgrade`); older binaries no-op silently. ### A crashed agent’s claim seems stuck [Section titled “A crashed agent’s claim seems stuck”](#a-crashed-agents-claim-seems-stuck) It isn’t — claims from stale sessions are treated as free (they show as `stale`, not active) and expire on their TTL. See the [conflict model](/weaver/concepts/conflicts/). ### Preflight paused a commit or push [Section titled “Preflight paused a commit or push”](#preflight-paused-a-commit-or-push) `weaver preflight` should only pause on relevant soft/hard overlaps with the paths being committed or pushed. Unrelated active sessions are informational. If preflight reports a relevant overlap, ask the user whether to continue, wait briefly, or coordinate first; do not silently poll for the other session to run `weaver done` unless the user explicitly asked to wait. If preflight reports your own work as another session, the hook or agent likely lost its session identity. Set `WEAVER_SESSION` consistently, or run `weaver doctor` to inspect identity resolution. ### `weaver upgrade` says it’s not applicable [Section titled “weaver upgrade says it’s not applicable”](#weaver-upgrade-says-its-not-applicable) `upgrade` only works on the standalone (curl-installed) binary. If you’re running from source or a dev link, that’s expected — re-install via `install.sh` to get an upgradeable binary. ### Two sessions of the same harness show as one [Section titled “Two sessions of the same harness show as one”](#two-sessions-of-the-same-harness-show-as-one) They shouldn’t — each session has a distinct harness session id. If they collapse, you may have set the same `WEAVER_SESSION` in both; unset it and let auto-detection run, or give each a unique value. ## FAQ [Section titled “FAQ”](#faq) **Does Weaver send my code anywhere?** No. Everything is local under `~/.weaver/`. Nothing is transmitted. **Does it work offline?** Yes — except `weaver upgrade`, which fetches the latest release. **Can I use just one agent?** Sure, but Weaver shines with several at once. With one it’s mostly a durable notebook (notes survive across sessions). # Releasing > How Weaver releases are cut and distributed. Releases are automated with **release-please + Conventional Commits**. The full playbook is in the repo: [`RELEASING.md`](https://github.com/sean35mm/weaver/blob/main/RELEASING.md). ## In short [Section titled “In short”](#in-short) 1. Land `feat:` / `fix:` commits on `main`. (`fix:` → patch, `feat:` → minor.) 2. release-please opens a **“chore: release vX.Y.Z”** PR with the version bump + changelog. 3. **Merge that PR.** That tags the release, builds the standalone binaries for every platform (each stamped with the version) and attaches them. 4. `install.sh` and `weaver upgrade` serve the new binaries automatically. You don’t hand-pick versions or write the changelog — they come from the commit messages. ## Distribution [Section titled “Distribution”](#distribution) Weaver is distributed as a **standalone binary** via `curl | sh` and `weaver upgrade`. See [Install](/weaver/getting-started/install/) and [Architecture](/weaver/reference/architecture/). # Roadmap > Where Weaver is headed — what's in flight now, what's coming next, and the directional bets for later. This is a living view of where Weaver is going, grouped by **horizon** rather than dates. Items move up a tier as they progress. It’s a direction, not a contract — priorities shift as the project (and the way people run agents) evolves. ▸ Recently shipped * **Claude Code hooks** — coordination is now structural for Claude Code: an advisory warning before any edit that overlaps another live session, and automatic presence after every edit. See the [hooks guide](/weaver/guides/claude-code-hooks/). * **Note lifecycle** — notes have ids and `weaver note --update ` supersedes stale learnings. ▸ Now — in flight What’s actively being worked on. * **Docs & landing polish** — homepage redesign, typography, and this roadmap. * **Real-world dogfooding** — running Weaver on its own repo across Claude Code and OpenCode, folding the findings back in. * **Tighten cross-harness session identity** — more reliable detection of distinct sessions across Claude Code, Codex, OpenCode, and Pi. ▸ Next — committed, soon Lined up and likely to land in the near term. * **Hook coverage for more harnesses** — bring the structural pre/post-edit coordination to other agents as their hook systems allow. * **More harness coverage** — Cursor, Gemini CLI, and Aider recognized out of the box. * **Notes & activity search** — query and filter notes and history instead of scanning the whole log. * **Dashboard & watch upgrades** — a richer live view, with filtering by area or agent. ▸ Later — directional Bets we’re interested in but haven’t committed to. Feedback shapes what makes the cut. * **Optional shared / remote commons** — opt-in sync so agents on *different machines* can share context. The core stays local-first and serverless; this would be strictly additive. * **Harness-native packaging** — ship Weaver as a Claude Code plugin / skill (and equivalents) for one-step setup. * **Smarter conflict advisories** — suggest *how* to split overlapping work, not just flag the collision. * **Richer query layer** — revisit a graph-style query over the commons, if demand warrants. * **Native Windows support** — today Windows runs via WSL2; native binaries if demand shows up. ▸ Shape the roadmap Weaver is open source and the roadmap is meant to be influenced. * **Have an idea or a pain point?** [Open an issue](https://github.com/sean35mm/weaver/issues). * **Want something prioritized?** 👍 the issue — reactions are a real signal. * **Want to build it?** See [Contributing](/weaver/contributing/). Changes land through pull requests.