flopwire

The Problem

When multiple AI agents run on different harnesses (Claude, Codex, Devin, opencode, etc.) they cannot see each other’s state, messages, or the recent history of conversations that led to a commit. This isolation hinders coordination, debugging, and auditability in teams that rely on continuous integration pipelines.

What This Does

Flopwire supplies a CLI (cmd/flopwire/main.go) and a set of MCP‑style plugins that give agents:

Presence & Messaging – peers, send, inbox (see cmd/flopwire/peers.go‑style commands in accept.go and admin.go).
Shared History – a local agent (cmd/flopwire/agent.go) indexes transcript files (see cmd/flopwire/messages.go) and exposes grep, search, sessions, and read.
Commit‑to‑Session Mapping – trace (cmd/flopwire/retrieve.go) returns the session that produced a given commit.
Rule‑Based Security – path rules in cmd/flopwire/credsource.go and redaction logic in cmd/flopwire/redact.go.

The CLI is cross‑platform; the installer (install.sh) downloads a prebuilt binary from the releases page. For local development, go build ./cmd/flopwire or make suffices.

How It Is Wired

Component	Key File(s)	Responsibility
CLI entry	`cmd/flopwire/main.go`	Parses flags, registers cobra commands (`accept.go`, `admin.go`, `agent.go`).
Command dispatch	`accept.go`, `admin.go`, `agent.go`	Each file implements a top‑level command, delegating to internal packages.
Message bus	`cmd/flopwire/bus.go`	Central routing of messages between agents and the server.
Agent runtime	`cmd/flopwire/agent.go` + `cmd/flopwire/mcp_runtime.go`	Starts the agent loop, watches the filesystem, and pushes events to the bus.
Persistence	`migrations/` + `cmd/flopwire/repo_metadata.go`	SQLite schema (migration SQL) and CRUD functions.
Networking	`cmd/flopwire/servetls.go`	TLS‑enabled HTTP server that serves the shared history and peer list.
Testing harness	`cmd/flopwire/*_test.go`	End‑to‑end and unit tests that hit the same paths used by production.

A typical run starts with flopwire agent run. main.go hands the agent subcommand to agent.go, which creates a MCPRuntime instance. The runtime registers with the local bus (bus.go), spawns a file watcher (implemented in agent_diagnostics.go), and begins serving over the TLS server (servetls.go). All message traffic flows through the bus, which writes to the SQLite database (migrations/*.sql). The CLI commands for grep or send call the same bus and database layers, keeping the code path minimal and testable.

How To Use It

# 1. Install the binary
curl -fsSL https://flopwire.com/install.sh | sh

# 2. Configure environment (example)
cp .env.example .env
# edit .env to set FLOPWIRE_DB_PATH=/var/lib/flopwire/flopwire.db

# 3. Detect harnesses and start an agent
flopwire setup          # auto‑detects paths in $PATH
flopwire agent run       # keeps the local index alive

# 4. Use the tools
flopwire grep 'exit (code|status) [1-9]' --since 24h
flopwire search 'how did we handle rate limits?'
flopwire peers
flopwire send 4c19e0d2 -- "Heads‑up: the list endpoint returns a cursor now."

For development:

# Build locally
make build

# Run tests
make test

Docker images are built via docker build -t flopwire . (Dockerfile) or docker build -f Dockerfile.release -t flopwire:release ..

Real‑World Use

In a CI pipeline, a Codex job can call flopwire trace <commit> to find the session that produced the commit, then flopwire read <session> to pull the conversation that led to the change. A developer can run flopwire grep locally to see how a recent build failure was discussed. The plugin architecture allows adding new harnesses without touching the core in cmd/flopwire/.

Code Health & Issues

Tests: 673 test files; CI workflows in .github/workflows/*.yml.
Static analysis: No automated analysis report in the repo; all tests pass locally.
Licensing: Apache‑2.0 (LICENSE).
Secrets: None committed; .env.example provides placeholders.
Documentation: 56 Markdown files, including docs/harnesses/README.md.

No critical issues were identified in the available data. The code follows Go conventions and has a clear separation between CLI, bus, and persistence layers.

The Bottom Line

Flopwire offers a pragmatic, self‑hostable bridge between heterogeneous AI agents. Its Go core is well‑tested, the CLI is straightforward, and the plugin ecosystem makes it extensible. Teams that already use Claude, Codex, or Devin can integrate Flopwire with minimal effort, but the codebase expects a Go environment and some familiarity with Unix tooling.