Orchestrate your AI coding agents. Stop losing context.
The open-source orchestration layer for AI coding tools. Spawn teams of agents, coordinate their work, and never lose context — with a full GUI dashboard.
npm i -g groove-dev
groove startThe GUI opens at http://localhost:31415. On a VPS? groove detects it and tells you exactly what to do.
AI coding agents waste your money and lose their way:
- Cold starts — every new agent spends thousands of tokens re-learning your codebase
- Context degradation — long sessions lead to hallucinations, circular refactors, lost direction
- No coordination — multiple agents edit the same files, create conflicts, duplicate work
- Blind spending — no visibility into token usage, no way to optimize costs
groove sits between you and your AI coding agents. It doesn't replace them — it makes them work together.
A background AI continuously watches all agent activity and synthesizes it into a living project map. When any agent spawns or restarts, it reads one file and knows everything. No re-explaining your codebase. No wasted tokens on orientation.
Instead of letting agents fill their context window until they degrade, groove detects quality decline — error spikes, circular refactors, file churn — and automatically rotates: kill the session, spawn fresh, feed it the Journalist's context. The agent picks up exactly where it left off with a clean window. No compaction. No drift. Works at any codebase scale.
Agents in Auto mode knock on the PM before risky operations (creating files, deleting, modifying config). The PM reviews against the project plan and scope rules, then approves or rejects with reasoning. Full audit trail in the GUI.
Spawn a planner, describe your project. The planner writes a detailed plan and recommends a team. Click Launch Team — all agents spawn with proper roles, scopes, and prompts. One click from idea to a full team building your app.
groove auto-detects monorepo workspaces (npm, pnpm, lerna) and lets you spawn each agent in its own subdirectory. A frontend agent only sees packages/frontend/. A backend agent only sees packages/backend/. No wasted context on irrelevant code.
- Codebase indexer — scans project structure on start, gives every agent instant orientation
- Architecture injection — auto-detects
ARCHITECTURE.mdand injects it into every agent's context - Per-workspace journalist — synthesis and handoff briefs scoped to each agent's directory
- Quick-pick — detected workspaces appear as buttons in the spawn panel
- Introduction protocol — every agent knows its teammates, their files, and their work
- Scope ownership — agents stay in their lane (backend touches
src/api/**, frontend ownssrc/components/**) - Task negotiation — duplicate roles get assigned non-overlapping work
- Knock protocol — agents signal before shared/destructive actions
Run groove on a VPS and manage your agents from anywhere. No ports exposed to the internet. No tokens. No custom auth code. Zero attack surface.
groove never opens ports to the public internet. Instead, it uses battle-tested transport layers — SSH tunnels and WireGuard (Tailscale) — to keep your daemon private.
Your laptop Your VPS
┌──────────┐ SSH tunnel ┌──────────────────┐
│ Browser │ ◄────────────────► │ groove daemon │
│ localhost│ encrypted │ 127.0.0.1:31415 │
└──────────┘ └──────────────────┘
Zero open ports
The daemon always binds to 127.0.0.1. Nothing reaches it from the public internet. Your SSH keys handle auth. Your browser connects to localhost on your machine, and the tunnel forwards traffic securely to the VPS.
On your VPS:
npm i -g groove-dev # install
groove start # start the daemonOn your laptop:
npm i -g groove-dev # install (one-time)
groove connect user@your-server-ip # open the GUI
groove disconnect # close when doneThat's it. The GUI opens in your browser automatically.
groove auto-detects your environment — VS Code Remote, plain SSH, or local — and tells you exactly what to do. SSH config aliases work too: groove connect my-vps.
For multi-device access (phone, tablet, other machines on your network):
groove start --host tailscale # auto-detects your Tailscale IP
groove start --host 192.168.1.5 # explicit IPOpen http://<ip>:31415 from any device on the same network. Tailscale handles auth via WireGuard.
groove will reject any attempt to expose the daemon directly to the internet:
groove start --host 0.0.0.0 # REJECTED — not allowedThis is by design. Direct exposure requires custom auth, rate limiting, TLS management — attack surface we refuse to create. SSH and WireGuard solve this better than we ever could.
Pair groove daemons across machines with Ed25519 key exchange. The security layer is built — cross-server agent coordination (typed contracts, federated registry) is coming soon.
groove federation pair 100.64.1.5 # pair two daemons
groove federation list # see paired peers
groove federation status # show keypair + peersEvery cross-server message is signed with Ed25519 keys generated during a pairing ceremony. The receiving daemon verifies the signature before accepting any contract. Replay attacks are rejected (5-minute timestamp window). Tampered payloads are rejected. Unknown senders are rejected.
Server A Server B
┌──────────────┐ signed contract ┌──────────────┐
│ groove daemon│ ◄────────────────►│ groove daemon│
│ Ed25519 key │ verify + audit │ Ed25519 key │
└──────────────┘ └──────────────┘
Contracts are typed data (method, path, input/output schema) — not freeform text. No surface for prompt injection. Full audit trail on both sides.
Every state-changing operation is logged to .groove/audit.log:
groove audit # view recent entries
groove audit -n 50 # last 50 entries2:14:32 PM agent.spawn id=a1 role=backend provider=claude-code
2:14:35 PM agent.spawn id=a2 role=frontend provider=claude-code
2:33:12 PM agent.rotate oldId=a1 newId=a3 role=backend
2:45:00 PM federation.pair peerId=f63dc52b14b9 peerHost=100.64.1.5
Append-only, 0600 permissions, auto-rotates at 5MB. When team auth is added, every entry will include who performed the action.
| Threat | Defense |
|---|---|
| Remote attackers | Zero open ports. Daemon binds to private interface only. |
| Network eavesdroppers | SSH (tunnel) or WireGuard (Tailscale) encryption. |
| Spoofed federation contracts | Ed25519 signature verification on every message. |
| Replay attacks | 5-minute timestamp window. Reject old/future contracts. |
| Malformed peer data | Public key validation at pairing time. Peer IDs restricted to hex. |
| Path traversal | Peer IDs sanitized. No filesystem access across servers. |
| Privilege escalation | No auth code to exploit. Transport layer handles all access control. |
What we explicitly don't defend against: Compromised SSH keys, root access to VPS, malicious AI provider responses (out of scope — we're a process manager).
The principle: "There's nothing to attack" is better than "we have a security system and here's why it's good." groove has zero auth code. The transport layer does all the work.
| Provider | Auth | Models |
|---|---|---|
| Claude Code | Subscription | Opus 4.6, Sonnet 4.6, Haiku 4.5 |
| Codex | API Key | o3, o4-mini, GPT-4.1, GPT-4.1 Mini, GPT-4.1 Nano |
| Gemini CLI | API Key | 3.1 Pro, 3 Flash, 3.1 Flash Lite, 2.5 Pro, 2.5 Flash |
| Ollama | Local | Any |
groove is a process manager — it spawns actual AI tool binaries. It never proxies API calls, never touches OAuth tokens, never impersonates any client. Your AI tools talk directly to their servers.
Works in any terminal, any IDE, any OS. Technical and non-technical users alike.
Open the dashboard after starting the daemon (local or remote):
- Agent Tree — visual node graph with Bezier spline connections, role badges, live status
- File Editor — CodeMirror 6 with syntax highlighting, file tree, tabs, media viewer, and embedded terminal
- Chat — instruct agents, query without disrupting, continue completed agents, streaming text
- Command Center — gauge charts, live telemetry, token savings, model routing, adaptive thresholds
- Quick Launch — planner recommends team, one-click to spawn all
- Skills Store — app-store marketplace for agent skills with ratings and verification
- PM Review Log — full audit trail of AI Project Manager decisions
- Team Management — save, load, export, import agent configurations
groove routes tasks to the cheapest model that can handle them. Planners get Opus (deep reasoning). Backends get Sonnet (balanced). Docs get Haiku (fast and cheap). The classifier learns from agent activity and adjusts over time.
| Tier | Cost | Used For |
|---|---|---|
| Heavy (Opus) | $0.045/1K | Planning, architecture, complex refactors |
| Medium (Sonnet) | $0.009/1K | Backend, frontend, testing |
| Light (Haiku) | $0.002/1K | Docs, synthesis, simple queries |
┌──────────────────────────────────────────────┐
│ groove DAEMON (:31415) │
│ │
│ Registry · Introducer · Lock Manager │
│ Journalist · Rotator · Adaptive · Indexer │
│ Classifier · Router · PM · Teams │
│ │
│ REST API · WebSocket · GUI Server │
└──────────────────────┬───────────────────────┘
│
┌──────────────────────▼───────────────────────┐
│ Claude Code · Codex · Gemini CLI · Ollama │
└──────────────────────────────────────────────┘
- Website: groovedev.ai
- Documentation: docs.groovedev.ai
- Changelog: docs.groovedev.ai/changelog
- GitHub: github.com/grooveai-dev/groove
- npm: npmjs.com/package/groove-dev
- License: FSL-1.1-Apache-2.0 — source-available, converts to Apache 2.0 after 2 years