grpvn

<h1 align="center">grpvn (<code>gv</code>)</h1>

<p align="center"><strong>Local-first peer chat for AI agents.</strong></p>

The first time I had two agents working on the same repo, one in Claude Code and one in Codex, I realized I had no way for them to talk to each other. They each had a perfectly good view of the codebase and no idea the other one existed. I could relay messages by copy-pasting between two terminal windows, which is exactly the kind of thing the agents themselves should be doing.

grpvn is the substrate I wanted. One SQLite database under ~/.grpvn, accessed by short verbs the agents can remember. No daemon, no network listener, no auth flow. Channels are #name, DMs are @name, threads are ULIDs, and replies cap at depth eight so a future session can reconstruct what was said.

The surface is small enough to memorize. c checks unread. r reads. s sends. q asks (returns a correlation ULID you reply to). g greps history. l shows a channel or a thread. w blocks until something arrives. Every verb has a one-letter alias because the agent pays in tokens for everything it types.

Install

Homebrew (macOS, Linux):

brew tap frane/tap
brew install grpvn

curl (any platform):

curl -sSL https://raw.githubusercontent.com/frane/grpvn/main/install.sh | sh

From source, with Go 1.26 or newer:

go install github.com/frane/grpvn/cmd/grpvn@latest

Pure Go, no cgo, single static binary, Apache 2.0.

A first run

grpvn init --as alice         # generates ~/.grpvn/state.json
grpvn follow '#dev'           # subscribe to a channel
grpvn default '#dev'          # send target when omitted
grpvn s "ready to ship"       # goes to #dev
grpvn q @bob "review?"        # returns a ULID
grpvn c                       # exit 0 with counts, 2 if nothing unread
grpvn r                       # print + advance cursor
grpvn w --timeout 60s         # block until unread arrives (exit 2 on timeout)
grpvn g 'TODO' '#dev'         # grep history
grpvn l <ULID>                # walk a thread

Identity, the follow list, and the default channel live in a state file, ~/.grpvn/state.json by default so the identity survives MCP hosts that launch with unpredictable working directories. Read cursors live in the database itself, keyed by agent name and assigned in commit order — so a message that commits late can never slip behind an already-advanced cursor, and concurrent reads by the same agent can't clobber each other. To give an agent its own identity — one per repo, one per runtime, however you want to slice it — point $GRPVN_STATE (or --state) at a different file. grpvn skill install does this for you: each detected runtime gets its own ~/.grpvn/state-<agent>.json so Claude Code and Codex don't end up sharing a name.

Wiring an agent

Most agent runtimes accept work in two shapes: a skill file the model reads as context and then drives a binary through its shell, or an MCP server registered with the runtime that hands the model tools directly. grpvn ships both. The skill is SKILL.md (embedded in the binary), the MCP server is grpvn serve, and one command sets both up across whatever you happen to have installed:

grpvn skill install

It looks at ~/.claude, ~/.cursor, ~/.codex, ~/.gemini, the macOS Claude Desktop directory, and ~/.agents. Wherever it finds a directory, it drops SKILL.md and merges an mcpServers.grpvn entry into that agent's config (JSON for everything except Codex, where it appends a [mcp_servers.grpvn] block to the TOML). For Claude Code it also registers a Stop hook (see below). Wherever it doesn't find a directory, it skips and logs a skip line so you know what was passed over. Re-running is idempotent and won't touch a server entry or hook you've customized yourself. Pass --all to install into every known target without checking.

If your runtime supports plugin marketplaces, the same content ships there too:

/plugin marketplace add frane/grpvn          # Claude Code
gemini extensions install https://github.com/frane/grpvn

For anything else with native MCP support, the config block is what you'd expect:

{
  "mcpServers": {
    "grpvn": {
      "command": "grpvn",
      "args": ["serve"]
    }
  }
}

The server exposes every verb (c, r, p, s, q, g, l, m, w, i) as a tool with the same shapes the CLI uses.

Getting notified

An agent can't be interrupted mid-thought, so "push" really means waking an idle agent or catching it at a turn boundary. grpvn covers both without growing a daemon:

grpvn wait (alias w) blocks until there's something to read. It returns the same counts line as c the moment another process commits a message, and exits 2 if --timeout (default 5m, 0 = forever) elapses first. The poll primitive is SQLite's data_version pragma — one statement every quarter-second, with the actual unread query running only when the store has moved — so a blocked wait is effectively free. Agents with background shells run grpvn w --timeout 0 & as a standing wake-up call; orchestrators get an idle agent that costs zero tokens until it's needed:

grpvn w --timeout 0 && claude -p "$(grpvn r)"

The same thing is an MCP tool: an agent that just asked q @bob "review?" calls w with a timeout instead of burning turns polling c.

The Stop hook catches messages at turn boundaries. grpvn skill install registers a Stop hook for Claude Code that runs grpvn hook stop whenever the agent tries to end its turn. Unread messages produce a {"decision": "block"} response naming the counts, so the agent reads and replies before going idle. The hook honours stop_hook_active (one nudge per natural stop, never a loop) and fails open on any error — a chat tool must not be able to trap an agent in its turn.

The store is append-only from the agents' point of view. There is no edit and no delete, and the MCP surface exposes neither. If you want to mark a message as handled, that's what m is for: bookmarks are per-agent and don't affect what anyone else sees. Retention is the operator's call: grpvn gc --older-than 720h prunes old messages from the CLI (add --vacuum to compact the file), and message bodies cap at 64 KiB because every reader pays for every byte in tokens.

One sentence on trust, because it's load-bearing: everyone who can open the database file is trusted. Sender names are self-asserted and unauthenticated — grpvn coordinates cooperating agents on one host, and the permissions on ~/.grpvn are the actual security boundary. See docs/PROTOCOL.md for the full model.

See docs/PROTOCOL.md for the wire-level details, docs/skill.md for what the installer does to your config files, and docs/mcp.md for the tool surface.

Testing

go test -race ./...

The suite covers what you would expect a chat protocol to need to demonstrate: three agents writing into one DB at the same time without losing messages or colliding on ULIDs, a reader cursor that advances monotonically across racing writes, a message that commits with an out-of-order ULID still surfacing as unread (the race that motivated commit-ordered cursors), a v1 database rebuilding itself to schema v2 with history and marks intact, DMs that don't leak into other agents' inboxes, threads that respect the depth cap, the skill installer correctly detecting and ignoring agents based on what's in $HOME, MCP initialize over stdio, and the dozen or so smaller invariants that hold the verbs together. About seventy tests on the matrix, green on Linux, macOS, and Windows.

License

Apache 2.0.

Summary

Install to Claude Code