Parallel coding tasks. Shared context. Reviewed integration.
A local-first workspace for coordinating coding agents across isolated Git worktrees.
Quick start · Documentation · Report a bug · Request a feature
Murmur helps you assign independent tasks, share decisions, spot overlapping changes, and integrate reviewed commits while keeping your original checkout intact. Use its local dashboard and CLI to coordinate work, with opt-in launchers for Claude Code, Codex, and the CLI-only OpenCode V2 fallback.
0.6 development alpha, not a published release: human-reviewed groups, scoped MCP, automatic approved-session context, installation lifecycle, and state maintenance are implemented. Claude Code 2.1.247 and Codex CLI 0.154.0 have version-scoped existing-chat flows requiring explicit native activation and human approval. Native fixture evidence is not real-model acceptance. The historical Codex fixture bypassed hook trust and pretrusted its disposable project; normal interactive activation remains unverified. Direct hot attachment, structured existing-chat publication, OpenCode/Cursor attachment and the full four-tool release remain gated. Managed launchers are separate modes. See the support matrix and roadmap.
Parallel agents can work in separate branches and still duplicate an API, disagree on a contract, or build against an outdated decision. Murmur gives those tasks a shared place to declare intent and surface coordination problems before integration.
- One task, one workspace. Create or adopt Git worktrees for independent work.
- Project-focused groups. Link separate responsibilities without merging chats, taking task ownership, or moving an existing workspace. Human approval controls scoped access; native existing-chat command gates stay explicit.
- Shared intent and decisions. Record expected reads, writes, contracts, and dependencies; explicitly review and accept shared decisions.
- Evidence-backed alerts. See duplicate producers, conflicting declared values, stale consumers, and overlapping paths.
- Managed agent launches. Start fresh Claude Code, Codex, or OpenCode V2 tasks with workspace preparation, startup context, and scoped coordination commands.
- Reviewable Git integration. Submit immutable commits, inspect candidates, run trusted checks, and approve an integration branch before bringing it into yours.
- Local-first by default. A local service, SQLite state, and a browser dashboard. The coordinator requires no model account or telemetry. Source builds use pinned SDK/schema dependencies; launched coding tools use their normal providers and billing.
Register a project → Create tasks + workspaces → Work in parallel
↓
Share decisions + review alerts
↓
Your working branch ← Approved integration ← Submit + validate commits
The dashboard brings together Tasks, Alerts, Decisions, Workspaces, Integration, Connections, Operations, and Adapters. Murmur observes Git changes every 10 seconds; reservations are advisory and do not replace separate workspaces or code review.
- Node.js 24+ and Git.
- A local Git project with at least one commit for workspace isolation and integration. Ordinary folders support coordination records only.
- For managed launches, an installed and authenticated Claude Code, Codex, or OpenCode V2 CLI. OpenCode uses a private standalone server and CLI bridge.
The recorded local verification environment is macOS with Node 26.4.0 and Git 2.54.0. The runtime workflow targets Node 24 and 26 on macOS and Linux; see the verification record for the scope of testing.
git clone https://github.com/boyeesu/murmur.gitcd murmurnpm ci --ignore-scriptsnpm run checkInstallation is from source. An npm release has not been published; npx murmur
and npm install -g murmur are not installation commands for this project.
For a supplied local .tgz artifact, see the
local-package instructions.
In terminal 1, from the Murmur folder:
npm run murmur -- daemon startLeave it running. In terminal 2, from the same folder:
npm run murmur -- dashboardOpen the printed URL within one minute. Select Register project and enter the path to the project you want to coordinate. The browser session lasts 30 minutes; after a reload or expiry, run the dashboard command again for a fresh URL.
In a new terminal, from the Murmur folder:
npm run murmur -- run claude --project PROJECT_ID --title "Implement password reset"In another terminal, start an independent task:
npm run murmur -- run codex --project PROJECT_ID --title "Build account settings"Replace PROJECT_ID with the ID shown in the dashboard or returned by init.
Each command creates a new task and isolated worktree, then launches the selected
tool using its normal account and permissions. Keep the tool's terminal open.
These launches start new sessions; the scoped CLI bridge remains the default. To opt into the official MCP tools and Claude advisory context hooks:
npm run murmur -- run claude --project PROJECT_ID --title "Implement password reset" --bridge mcp --context-hooksFor Codex, use --bridge mcp without --context-hooks. Automatic Codex hook
configuration is gated until installed merge/trust behavior is established.
OpenCode V2 currently supports --bridge cli only and uses --standalone.
Native policy still applies. Hook generation is not proof of model compliance, and PreToolUse feedback does not guarantee replanning an already-selected call. See native integration limits, managed launches, and MCP tools.
To produce a local archive with its verified runtime dependency closure:
npm run packTo stop the service, press Ctrl-C in terminal 1 or run:
npm run murmur -- daemon stopThe manual dashboard/CLI workflow supports any coding tool that can open a local folder:
- Register your project and create a task with a manual owner record.
- Declare expected changes, contracts, and dependencies.
- Create or adopt a separate workspace and open that folder in your coding tool.
- Copy the task briefing into the agent's conversation; refresh it as decisions change.
- Commit work, submit it, and validate an integration candidate.
- Review and approve the integration branch, then bring it into your working branch.
Attaching a workspace updates Murmur's records; it does not move an already running agent. The user guide walks through the full workflow, including a small example that triggers an overlap alert.
In Connections, create a project group and add an existing manual or active managed task owner. Review each responsibility and shared handoff. Manual membership is bookkeeping, not native attachment; managed membership keeps its existing task and lifetime.
Human-reviewed external grants are bound to one task and current workspace, expire in 8 hours by default (24 hours maximum), and never renew from activity. Invitations are hashed, single-use approval requests—not access credentials. Fresh reconnect is an explicit, reviewed choice for the same eligible session and still-owned task. Leaving or expiring access neither finishes the task nor stops the native chat.
For Claude Code 2.1.247 only, use a human terminal in the original project. Ensure the daemon is running and the project is registered, then export a new plugin directory:
murmur connect setup --tool claude --out /absolute/new/plugin-dirSetup checks the actual executable/version, public connection.json, and private
helper state; it does not install native configuration or connect a chat. For source-only
use, see the absolute-CLI instructions.
Pause/exit the original CLI first to avoid duplicate writers, then run the returned
absolute resumeCommand in the original project and select the original conversation.
It loads the bundle with --plugin-dir and opens Claude's --resume picker. Pass
--plugin-dir again on later resumes. Native history is preserved by Claude, not
scanned or imported into Murmur.
In the resumed conversation, use /murmur:connect start GROUP TITLE | RESPONSIBILITY
or /murmur:connect join INVITE_CODE | RESPONSIBILITY (a 43-character base64url code).
Review and approve the exact request and shared handoff in the authenticated Murmur UI,
then run /murmur:connect refresh. status, leave, and help are also supported.
Explicit refresh activates the approved connection. Subsequent ordinary prompts refresh
already-active context without enrollment, approval polling or grant renewal. Tool-boundary
advisory hooks are implemented but native post-tool delivery remains unverified.
There is no automatic intent publication or proof of model obedience.
Processes already carrying a managed/external Murmur scope must use their existing
scoped commands; the hook refuses to create a second connection. There is no universal
/murmur / @murmur alias.
0.5 native checkpoint (2026-10-14): the exported production plugin passed headless start/approval, resumed scope, separate owners for two same-cwd chats, disconnected fork/clear, explicit original resume, and own-grant leave with tasks preserved. Tests used native-authored disposable history, empty HOME/config, a dummy key, and an owned static loopback API responder with no actual LLM inference. This is not a real-user chat/model trial or direct hot-attachment/reload verification. The earlier denied nested OS sandbox remains historical evidence; the later runs do not prove stronger OS isolation or absence of Keychain access.
For Codex CLI 0.154.0, export reviewed hook setup from a human terminal:
murmur connect setup --tool codex --out /absolute/new/codex-exportFollow the exported SETUP.md: preserve existing hooks when adding the fixed
UserPromptSubmit entry, pause/exit the original process, resume its original
conversation, and review native hook trust using /hooks. Setup does not install
or connect anything automatically. In that chat, enter ordinary messages such as
murmur-connect start GROUP TITLE | RESPONSIBILITY or
murmur-connect join INVITE_CODE | RESPONSIBILITY. After human approval, enter
murmur-connect refresh to activate the connection. Later ordinary prompts fetch
fresh scoped context automatically. status, leave, and help are also available.
The actual CLI and generated hook passed isolated start/approval, exact-thread resume, fresh decision delivery into developer-role input, independent same-cwd chats, real fork isolation, and leave checks against an owned static responder. No real model inference occurred. Interactive hook trust, desktop/web attachment, and hot loading into an already-open process remain unverified. See the Codex existing-chat guide.
OpenCode, Cursor, and untested native versions remain gated. Use manual groups or export a reviewed handoff for a separately launched new managed task instead. Handoffs retain reported files already changed and a separate remaining-work checklist; neither is filesystem proof or automatic completion. See groups and approved connections and the dated native evidence.
| Tool | Managed launch | MCP / native context |
|---|---|---|
| Claude Code | Alpha | Opt-in managed MCP/hooks; 2.1.247-only existing-chat plugin + resume connector; real-model use unverified |
| Codex | Alpha | Opt-in managed MCP; 0.154.0 existing-chat reviewed hooks + resume with automatic context refresh; managed automatic hook configuration remains gated |
| OpenCode V2 | CLI-only alpha, private standalone server | MCP/plugin configuration gated |
| Cursor | Not implemented; CLI unavailable in current verification environment | Gated |
| Other folder-capable tools | Manual workspace workflow | Not integrated |
Managed launch tests exercise simulated native processes and real Murmur services. Official SDK roundtrips and generated hook contracts are tested. Real model-driven acceptance, arbitrary existing-session discovery, and universal native/per-turn behavior are not verified capabilities. See the support matrix.
| Guide | What you'll find |
|---|---|
| User guide | Installation, first run, and the daily workflow |
| Operations | Reviewed integration install, update, removal, rollback, and recovery |
| Data lifecycle | Credentials, retention, consistent private backup, and offline restore |
| Groups and session connections | Manual groups, human review, fixed-scope grants, reconnect, and replacement handoffs |
| Codex existing chats | Reviewed hook setup, same-thread resume and automatic context refresh |
| Managed launches | Claude Code/Codex setup and lifecycle |
| Agent bridge | Scoped agent commands and credentials |
| MCP | Official SDK server, tools and transport limits |
| Native configuration | Launch-local configuration and verification gates |
| Context hooks | Advisory refresh behavior and privacy |
| OpenCode V2 | Standalone CLI fallback and current limitations |
| Coordination | Intent, decisions, dependencies, and task lifecycle |
| Workspaces and integration | Git isolation, validation, and promotion |
| HTTP protocol | Local service API |
| Verification | Tested behavior and remaining limitations |
| Changelog | Changes by version |
State lives in ~/Library/Application Support/Murmur on macOS, or
$XDG_STATE_HOME/murmur / ~/.local/state/murmur on Linux. MURMUR_HOME can select
a dedicated private directory outside the source repository; use the same value
in every terminal.
Murmur retains source work rather than auto-stashing or auto-committing it. Validation commands run with your local-user privileges. Human, managed-agent, and external-grant credentials have separate authority; see SECURITY.md. Before upgrading an older build, stop its daemon and privately back up its complete state directory. This increment advances SQLite compatibility to v4; older binaries must refuse that database. The new maintenance command makes consistent private database backups, but those do not include source workspaces or the installer registry. Restore is offline, into a new private directory only, and invalidates copied credentials. See data lifecycle. No downgrade, source cleanup, or destructive repair is automatic.
- Local task board, shared decisions, and coordination alerts.
- Git worktrees, immutable submissions, validation, and reviewed integration.
- Opt-in Claude Code/Codex/OpenCode V2 CLI launchers with scoped agent commands.
- Official SDK MCP transport, strict schemas and scoped authorization.
- Advisory context-hook commands and launch-local Claude configuration.
- Project groups, human-reviewed scoped grants, and reviewed handoff exports.
- Version-scoped Claude and Codex existing-chat flows with separate native evidence limits.
- Automatic context refresh for explicitly activated, human-approved participants.
- Reviewed integration lifecycle, credential management, retention, and private backup/restore.
- Direct hot attachment/reload, cross-host existing-chat contracts, and automatic background publication.
- Strict TypeScript checking and dependency-complete local package tests.
- Real model-driven, multi-tool acceptance testing.
- Remaining native-host hook/MCP configuration verification.
- Managed Cursor launcher and OpenCode MCP/plugin integration.
- Restricted managed resume and broader platform verification.
- Published versioned packages and smoother first-run onboarding.
See the release checklist for detailed completion gates. Suggestions and focused proposals are welcome in Issues.
Contributions are welcome: report reproducible bugs, improve the docs, or help build the next integration. Read CONTRIBUTING.md before opening a PR.
npm ci --ignore-scriptsnpm run checkThe test suite uses disposable repositories, local HTTP clients, temporary state,
and simulated agent processes. npm run check requires strict TypeScript checking
and runtime tests. The build step alone still strips types; it is not a type checker.
For vulnerability reports, use the private reporting process in SECURITY.md.
Distributed under the MIT License. See LICENSE for details.