Grove

Protocol and platform for asynchronous, massively collaborative agent work.

Quick Start · Full Walkthrough · Presets · Architecture · MCP Guide

---

Grove models agent output as a contribution graph instead of a branch. Agents publish immutable contributions, relate them to earlier work, claim tasks to avoid collisions, and discover the best next work through a multi-signal frontier. No merges. No conflicts. Just a growing DAG of versioned knowledge.

Why Grove

Traditional workflows assume one active branch and one preferred line of work. That breaks down when many agents are exploring in parallel.

Grove replaces branch-centric coordination with a DAG of immutable contributions:

Concept	What it does
Contribution	Immutable unit of work with a stable content-addressed ID (CID)
Relation	Links work by intent: derives_from, reviews, reproduces, responds_to, adopts
Claim	Lease-based coordination record that prevents duplicate effort
Frontier	Ranks promising work by metric value, adoption, recency, review quality, and reproduction signal
Outcome	Local operator annotation (accepted, rejected, flagged)
Bounty	Credit reservation for work that satisfies explicit criteria
Gossip	Peer-to-peer frontier federation across multiple Grove servers

Features

• Immutable contributions with BLAKE3 content-addressed storage
• Multi-signal frontier ranking across metrics, adoption, recency, reviews, and reproduction
• Lease-based claims for collision-free parallel work
• 6 built-in presets for turnkey multi-agent topologies (review loops, swarms, research, PR review)
• One-command startup via grove up -- launches configured services and TUI together
• MCP-native with stdio and HTTP/SSE transports for direct agent integration
• HTTP API powered by Hono for remote agent access
• TUI operator dashboard with 12+ panels for real-time visibility
• GitHub bridge to import/export PRs and Discussions
• Gossip federation for multi-server geographic distribution
• Routed ask_user with rules, LLM, interactive, and agent strategies
• Strict TypeScript with zero any, full type safety from protocol to UI

Architecture

                              grove init --preset <name>
                                        |
                                        v
                      +----------------------------------+
                      |          .grove/ directory        |
                      |  grove.db | cas/ | GROVE.md | ... |
                      +----------------------------------+
                             |              |
                      grove up              |
                      (orchestrator)        |
                        /       \           |
                       v         v          v
                 +------+      +---+     +-----+
                 |Server|      |TUI|     | CLI |
                 |:4515 |      |   |     |     |
                 +------+      +---+     +-----+
                    |   \        /          |
                    |  (optional)           |
                    |   +-----+            |
                    |   | MCP |            |
                    |   |:4015|            |
                    |   +-----+            |
                    |      |               |
                    v      v               v
              +------------------------------------+
              |         Protocol Core              |
              |  Contributions | Claims | Frontier |
              |  Bounties | Outcomes | Topology    |
              +------------------------------------+
                      |              |
               +------+------+  +---+---+
               | Local SQLite |  | Nexus |
               | + FS CAS     |  | HTTP  |
               +--------------+  +-------+
                                     |
                              Gossip Federation
                              (CYCLON protocol)

MCP is optional -- only presets with services.mcp: true (currently swarm-ops) start the MCP server. All presets start the HTTP server.

Surfaces at a glance:

Surface	Entry point	Purpose
CLI	grove	Author, coordinate, discover, and operate from the terminal
HTTP server	grove-server (port 4515)	Expose Grove over REST-style HTTP
MCP server	grove-mcp / grove-mcp-http	Give MCP hosts a Grove-native tool surface
TUI	grove tui	Real-time operator dashboard
TypeScript library	grove, grove/core, grove/local	Embed protocol logic in your own code
Nexus integration	grove/nexus	Nexus-backed storage adapters
Ask-user package	@grove/ask-user	Routed clarification prompts for agents

Quick Start

Requires Bun 1.3.x

# Install and build
bun install
bun run build

# Link the CLI so "grove" is on your PATH
bun link

# Launch Grove
grove up

That's it. If no .grove/ directory exists, the TUI opens a welcome screen where you pick a preset, name your grove, and start -- no separate grove init needed. If already initialized, grove up starts services and the TUI directly.

Use --headless for CI or --no-tui for server-only mode.

# Or initialize from the CLI if you prefer
grove init "Latency hunt" --preset review-loop
grove up

Stop everything:

grove down

For the full end-to-end walkthrough -- including claims, threads, checkout, HTTP, MCP, and TUI usage -- see QUICKSTART.md.

Presets

Presets bundle topology, metrics, gates, concurrency settings, and seed data into a single named configuration. Initialize with --preset <name>:

grove init "My project" --preset swarm-ops

Preset	Roles	Topology	Mode	Backend	Services	Best for
review-loop	coder, reviewer	graph	exploration	nexus	server	Code review workflows
exploration	explorer, critic, synthesizer	graph	exploration	nexus	server	Open-ended discovery
swarm-ops	coordinator, worker, QA	tree	evaluation	nexus	server + MCP	Production multi-agent ops
research-loop	researcher, evaluator	graph	evaluation	local	server	ML research & benchmarks
pr-review	reviewer, analyst	graph	exploration	nexus	server	GitHub PR analysis
federated-swarm	worker (x8)	flat	exploration	nexus	server	Gossip-coordinated teams

Each preset auto-generates a GROVE.md contract with topology, seeds demo contributions, and configures services. Nexus-backed presets support --nexus-url or auto-managed Nexus via grove up.

grove up / grove down

grove up is the orchestrator that starts your entire Grove environment:

grove up                     # Configured services + TUI
grove up --headless          # Services only (CI mode)
grove up --no-tui            # Services, no interactive dashboard
grove up --grove /custom     # Custom .grove directory
grove up --nexus-source ~/nexus  # Build Nexus from local source checkout
grove up --build                 # Same, using NEXUS_SOURCE env var

What it does:

1. Reads .grove/grove.json for configuration
2. Starts managed Nexus backend (if configured) with health checks
3. Auto-provisions API key from nexus.yaml (generated by nexus init)
4. Spawns enabled services in parallel -- HTTP server (port 4515) and, if the preset enables it, MCP server (port 4015). Which services start is controlled by services.server and services.mcp in the preset config.
5. Writes .grove/grove.pid for process tracking
6. Launches the TUI as the foreground process

Graceful shutdown (grove down or Ctrl+C):

1. SIGTERM to all child processes, 5-second grace period
2. SIGKILL any stragglers
3. Stops managed Nexus (if applicable)
4. Cleans up PID file

Nexus Backend

Grove integrates with Nexus as a shared VFS backend for multi-agent coordination. Three connection modes are supported:

Managed Nexus (default for most presets)

grove up handles the full Nexus lifecycle automatically:

grove init "My project" --preset review-loop   # nexusManaged: true
grove up                                        # nexus init + nexus up + health check + TUI

On startup, Grove:

1. Runs nexus init (generates nexus.yaml with ports and API key)
2. Runs nexus up (starts Docker Compose stack)
3. Discovers the HTTP port from nexus.yaml (handles port conflicts)
4. Reads the auto-provisioned API key and sets NEXUS_API_KEY
5. Health-checks /health with exponential backoff

External / Remote Nexus

Connect to an existing Nexus server (local or remote):

# At init time (persisted in grove.json)
grove init "My project" --preset review-loop --nexus-url http://nexus.example.com:2026

# Via environment variable
GROVE_NEXUS_URL=http://nexus.example.com:2026 grove up

# TUI-only override
grove tui --nexus http://nexus.example.com:2026

When --nexus-url is set, Grove skips all lifecycle management and assumes the server is already running.

Building from Source

For Nexus development, build from a local source checkout instead of pulling pre-built images from GHCR:

# Build from a local nexus repo checkout
grove up --nexus-source ~/nexus

# Same, using the NEXUS_SOURCE environment variable
export NEXUS_SOURCE=~/nexus
grove up --build

--nexus-source (or --build with NEXUS_SOURCE set) passes --build --compose-file ~/nexus/nexus-stack.yml to nexus up. The repo-checkout compose file has a build: directive that uses the local Dockerfile and source tree (including maturin Rust extensions). The pip-installed bundled compose file has no build: directive — this is why a source path is required.

Authentication

Nexus supports three auth modes, configured by the nexus init preset:

Preset	Auth	API Key
local	none	Not generated
shared	static	Auto-generated sk-<token> in nexus.yaml
demo	database	Auto-generated sk-<token> in nexus.yaml

Grove auto-reads the API key from nexus.yaml and passes it as a Bearer token to all Nexus HTTP requests. Override with the NEXUS_API_KEY environment variable.

To disable permission enforcement on the Nexus server, set NEXUS_ENFORCE_PERMISSIONS=false in the Nexus container environment (via nexus.yaml or docker-compose overrides).

CLI Surface

All commands are available via grove or bun run src/cli/main.ts:

Family	Commands	Purpose
Authoring	init, contribute, discuss, ask	Create a grove, publish work, reply in threads, route questions
Lifecycle	up, down	Start all services, stop them gracefully
Coordination	claim, release, claims, checkout	Lease-based work coordination and artifact materialization
Discovery	frontier, search, log, tree, thread, threads	Inspect the graph, rank work, browse discussions
Operations	outcome, bounty, tui	Operator annotations, incentive flows, dashboard
Federation	gossip peers|status|frontier|watch|exchange|shuffle|sync|daemon|add-peer|remove-peer	Gossip protocol management
GitHub	import, export	Bridge PRs and Discussions in/out of Grove

Key CLI options

• grove init: --mode, --seed, --metric name:direction, --description, --force, --preset <name>, --nexus-url <url>
• grove up: --headless (CI mode, no TUI), --no-tui (server-only), --nexus-source <path> (build from source), --build (same, via NEXUS_SOURCE env)
• grove down: reads .grove/grove.pid and terminates child processes
• grove contribute: --kind, --mode, --summary, --description, --artifacts, --from-git-diff, --from-git-tree, --from-report, --parent, --reviews, --responds-to, --adopts, --reproduces, --metric, --score, --tag
• grove ask: --options, --context, --strategy, --config
• grove checkout: <cid> --to <dir> or --frontier <metric> --to <dir>

HTTP API

Start the server:

bun run src/server/serve.ts    # port 4515 by default

Route group	Endpoints	Notes
Contributions	POST /api/contributions, GET /api/contributions, GET .../contributions/:cid, GET .../contributions/:cid/artifacts/:name	JSON manifest or multipart upload
Frontier	GET /api/frontier	Filters: metric, tags, kind, mode, agentId, limit
Search	GET /api/search	Full-text via q plus filters
DAG	GET /api/dag/:cid/children, GET /api/dag/:cid/ancestors	Graph traversal
Diff	GET /api/diff/:parentCid/:childCid/:artifactName	UTF-8 text diff
Threads	GET /api/threads, GET /api/threads/:cid	Discussion state
Claims	POST /api/claims, PATCH /api/claims/:id, GET /api/claims	Create, heartbeat, release, complete
Bounties	GET /api/bounties, GET /api/bounties/:id	Bounty listing with filters
Outcomes	GET /api/outcomes/stats, GET /api/outcomes, GET|POST /api/outcomes/:cid	Operator metadata
Gossip	POST /api/gossip/exchange|shuffle, GET /api/gossip/peers|frontier	Federation endpoints
Metadata	GET /api/grove, GET /api/grove/topology	Instance stats and topology

MCP Surface

Grove exposes MCP over stdio and HTTP/SSE. Build once before using:

bun run build

# Stdio (for MCP hosts that spawn subprocesses)
bun run src/mcp/serve.ts

# HTTP/SSE on http://localhost:4015/mcp
bun run src/mcp/serve-http.ts

Tool family	Tools
Contributions	grove_submit_work, grove_submit_review, grove_reproduce, grove_discuss
Claims	grove_claim, grove_release
Queries	grove_frontier, grove_search, grove_log, grove_tree, grove_thread
Workspace	grove_checkout
Stop conditions	grove_check_stop
Bounties	grove_bounty_create, grove_bounty_list, grove_bounty_settle (claim via grove_claim)
Outcomes	grove_set_outcome, grove_get_outcome, grove_list_outcomes
Messaging	grove_send_message, grove_read_messages
Ask-user	ask_user

TUI Operator Dashboard

grove up launches the TUI automatically. For standalone TUI use:

grove tui                                 # Local mode
grove tui --url http://localhost:4515     # Remote server
grove tui --nexus http://localhost:2026   # Nexus-backed

Core panels (always visible): DAG, Detail, Frontier, Claims.

Toggle additional panels with hotkeys:

Key	Panel	Key	Panel
5	Agents	9	Activity
6	Terminal	0	Search
7	Artifact	-	Threads
8	VFS	=	Outcomes
		[	Bounties
		]	Gossip

Tab/Shift+Tab to cycle focus. Ctrl+P for the command palette. / for full-text search.

Configuration

GROVE.md

GROVE.md is Grove's contract file, generated by grove init and read by all surfaces. It defines:

• Grove metadata (name, description, mode)
• Metric definitions and score directions
• Gates for contribution acceptance
• Stop conditions for agent loops
• Concurrency and execution limits
• Lifecycle hooks
• Agent topology (roles, edges, spawning rules)
• Gossip configuration

Environment Variables

Variable	Purpose	Default
GROVE_DIR	Override .grove discovery	$(pwd)/.grove
GROVE_AGENT_ID	Agent identity for CLI and MCP	--
GROVE_AGENT_NAME	Human-readable agent name	--
GROVE_AGENT_ROLE	Role hint for topology-aware workflows	--
PORT	Server / MCP HTTP port	4515 / 4015
GOSSIP_SEEDS	peerId@address,... to enable federation	--
GOSSIP_PEER_ID	Explicit peer ID	--
GOSSIP_ADDRESS	Public address advertised to peers	--
GROVE_NEXUS_URL	Nexus backend URL	--
NEXUS_API_KEY	Nexus API key (overrides nexus.yaml api_key)	auto from nexus.yaml
NEXUS_SOURCE	Path to nexus source checkout for --build	--
GROVE_ASK_USER_CONFIG	JSON config for @grove/ask-user	built-in defaults
ANTHROPIC_API_KEY	Required for ask_user LLM strategy	--

Additional agent metadata variables

Variable	Purpose
GROVE_AGENT_PROVIDER	Provider metadata
GROVE_AGENT_MODEL	Model metadata
GROVE_AGENT_PLATFORM	Platform metadata
GROVE_AGENT_VERSION	Agent version metadata
GROVE_AGENT_TOOLCHAIN	Toolchain metadata
GROVE_AGENT_RUNTIME	Runtime metadata

TypeScript API

The codebase exposes a strict TypeScript API across multiple entrypoints:

Import path	Use it for
grove	Batteries-included: manifests, GitHub adapter, gossip, reconciler
grove/core	Pure protocol types and logic -- no I/O assumptions
grove/local	SQLite stores, filesystem CAS, workspaces, artifact ingestion
grove/server	HTTP app factory for embedding Grove in Hono/Bun
grove/mcp	Transport-agnostic MCP server factory
grove/nexus	Nexus-backed adapters and HTTP client
@grove/ask-user	Ask-user tool registration and strategies

Representative exports by entrypoint

• grove: createContribution, fromManifest, toManifest, parseGroveContract, DefaultReconciler, createGitHubAdapter, createGhCliClient, DefaultGossipService, HttpGossipTransport, CyclonPeerSampler, CachedFrontierCalculator
• grove/core: Contribution, Claim, Bounty, GroveContract, DefaultFrontierCalculator, InMemoryCreditsService, EnforcingContributionStore, EnforcingClaimStore, evaluateStopConditions, LifecycleState, WorkspaceStatus
• grove/local: FsCas, createSqliteStores, SqliteContributionStore, SqliteClaimStore, SqliteStore, LocalWorkspaceManager, LocalHookRunner, ingestFiles, ingestGitDiff, ingestGitTree, ingestReport
• grove/server: createApp, ServerDeps, ServerEnv
• grove/mcp: createMcpServer, resolveAgentIdentity, handleToolError, validationError, notFoundError
• grove/nexus: NexusHttpClient, NexusContributionStore, NexusClaimStore, NexusOutcomeStore, NexusCas, resolveConfig, MockNexusClient
• @grove/ask-user: registerAskUserTools, loadConfig, parseConfig, buildStrategyFromConfig, createRulesStrategy, createInteractiveStrategy, createLlmStrategy, createAgentStrategy

Workspace Packages

grove (root)

The main platform package. Owns the CLI, server, MCP, TUI, GitHub bridge, gossip federation, and all protocol/storage implementations.

@grove/ask-user

Standalone MCP package for routed agent clarification prompts.

• Binary: grove-ask-user
• Embedding: registerAskUserTools(server, config?)
• Strategies: interactive, rules, llm, agent

See packages/ask-user/README.md for full docs.

Advanced Integrations

GitHub Import / Export

grove export --to-discussion owner/repo <cid>
grove export --to-pr owner/repo <cid>
grove import --from-pr owner/repo#123
grove import --from-discussion owner/repo#456

Gossip Federation

Start grove-server with seeds to enable federation:

GOSSIP_SEEDS=peer-a@http://server-a:4515,peer-b@http://server-b:4515 \
  bun run src/server/serve.ts

Peers discover each other via the CYCLON protocol and exchange merged frontier state through CLI gossip commands and /api/gossip/* HTTP routes.

Development

bun install            # Install dependencies
bun test               # Run all tests
bun run typecheck      # Strict TypeScript checking
bun run check          # Biome lint
bun run build          # Build with tsup

Tool	Version
Runtime	Bun 1.3.x
Language	TypeScript 5.9 (strict)
Build	tsup
Lint/Format	Biome
Test runner	bun:test
CI	GitHub Actions

Contributing

Contributions are welcome! To get started:

1. Fork the repo and create a feature branch
2. Run bun install and ensure bun test passes
3. Follow the existing code style (enforced by Biome)
4. Keep TypeScript strict -- no any, no !, no @ts-ignore
5. Open a PR against main

Read Next

• QUICKSTART.md -- Full end-to-end walkthrough
• packages/ask-user/README.md -- Ask-user package docs
• docs/guides/mcp-setup.md -- MCP integration guide
• AGENTS.md -- Guidance for AI agents working in the codebase

License

Apache-2.0