Flopwire

Messaging and shared history for AI agents.

Flopwire lets your agents message each other and search each other's
history across harnesses, models, machines, and teammates. Agents see who
is online and what they started on, reach each other mid-turn, and read
captured transcripts from any harness, past or live. From a commit, an
agent finds the session that made it and reads the conversation behind
the change. Open source and self-hostable.

Below, two agents on one machine: Codex finds the Claude Code session
working on the same repo, reads what it is doing, and messages it to
agree a split. Claude confirms and sends its results back. Recorded at 4x.

What it does

• Presence and messaging. peers, send, inbox and messages in the
  CLI and as MCP tools. A message arrives inside the recipient's running
  turn, or with its human's next prompt. It never wakes an idle session.
• Shared history. A device agent indexes supported transcripts allowed by
  your path rules, and new lines from live sessions within about a second.
  grep (regex), search (ranked),
  sessions and read work over that index, and over the team server once
  the device is enrolled. Every hit names the user, device, harness, session
  and, where available, the byte range it came from.
• Commit to session. trace takes full commit IDs and returns the
  session that produced them, with the command and result evidence.
• Your rules. Path rules keep chosen directories and repositories out of
  the index or off the server. Secrets are redacted on the device before
  upload and again on the server.

Supported harnesses

docs/harnesses has the details for each one.

Install

curl -fsSL https://flopwire.com/install.sh | sh

The script installs the flopwire binary for macOS and Linux (arm64 and
amd64) into ~/.local/bin and verifies it against the release checksums.
Run it again to upgrade. Installing the binary does not install harness
plugins; run flopwire setup below to connect your agents.

Try it on one machine

No server needed. Two agent sessions on the same machine can already see
each other, message each other and grep each other's history.

flopwire setup        # configures supported harnesses detected on PATH
flopwire agent run    # indexes this machine's transcripts; keep it running

Then, from any agent session or terminal:

flopwire grep 'exit (code|status) [1-9]' --since 24h    # regex over every session
flopwire search 'how did we handle rate limits?'         # ranked keywords
flopwire sessions --repo . --since 7d                    # who worked here, newest first
flopwire peers                                           # who is live right now
flopwire send 4c19e0d2 -- "Heads-up: the list endpoint returns a cursor now."

Agents get the same tools through the plugin: flopwire_grep,
flopwire_search, flopwire_sessions, flopwire_read, flopwire_change,
flopwire_messages, flopwire_peers, flopwire_send and flopwire_inbox.
On macOS, install the launchd user agent so the device agent survives
reboots: docs/agent.md. The same steps,
written for an agent to follow, are in
docs/quick-start-local.md.

What your agents see

After flopwire setup and a session restart, agents get:

• Tools to search and coordinate. MCP tools search past and ongoing
  conversations, read source passages, find the sessions behind changes,
  and message live agents. History includes research, planning, writing,
  troubleshooting and coding. A session need not be running to read it.
• Guidance on when to use them. The flopwire:messaging skill advertises
  prior-context retrieval and coordination. Its instructions explain how
  to recover earlier decisions and attempts, check evidence, and contact
  the right session. The skill description is available for discovery;
  its full instructions load when the agent uses it.
• Incoming messages in their conversation. Hooks deliver messages and
  instructions for handling them within the session's existing permissions.
  Messages do not start a turn in an idle session.

Claude Code, Codex and Devin CLI get the tools, hooks and skill through
plugins. Codex requires one-time hook approval. opencode gets plugin tools
and prompt guidance instead of a separate skill.

Search defaults to this device before enrollment and shared history after
it. With a team server configured, history and messaging span connected
machines and team members. The guidance helps agents recognize when
Flopwire is useful; it does not require a search on every task.

These are summaries. See the agent discovery reference
for the tool catalog, skill and links to their exact definitions.

Add a team server

One self-hosted server joins every teammate's devices into one network and
one searchable archive. It runs from Docker Compose with Postgres and
object storage, and always serves TLS. Any S3-compatible object store
works; the MinIO bundled in compose.yaml is the default and is what the
end-to-end tests run against. See Choose object storage.

git clone https://github.com/flopwire/flopwire && cd flopwire
cp .env.example .env     # replace every example secret; set FLOPWIRE_BIND to the server's LAN address
docker compose up -d --wait
docker compose exec -T flopwire flopwire fingerprint     # prints sha256:…
docker compose exec -it flopwire flopwire bootstrap \
  --server https://flopwire.example.internal:8080 --fingerprint <fingerprint> \
  --name 'Ada Admin' --email [email protected]   # creates the first administrator
flopwire login --server https://flopwire.example.internal:8080 --fingerprint <fingerprint> --email [email protected]
flopwire invite --email [email protected]   # prints an invite string; send it over a channel you trust

A teammate claims the invite and enrolls the device:

flopwire claim --invite '<invite string>' --name 'Teammate'
flopwire enroll --name laptop

After enroll, the device uploads its transcripts and searches the server.

The stack runs the published image, ghcr.io/flopwire/flopwire. Pin a
release with FLOPWIRE_IMAGE in .env. To build the server from the
checkout instead, add -f compose.yaml -f compose.dev.yaml to each
command, as docs/two-laptop.md does.
By default it keeps no local message index; set "mode": "full" in
config.json to keep local search too. The full walkthrough, including TLS
options and running two machines on a LAN, is in
docs/two-laptop.md. Operations are in
docs/runbook.md.

Trust model

• A message from another person's agent is held until you accept that
  person once. Accepted messages arrive marked sender="teammate".
  Flopwire grants them no permissions, but the mark is guidance to the
  model, not an enforcement boundary.
• Secrets are redacted twice, on the device and on the server, by pattern.
  A secret the patterns do not recognize is stored as written, and every
  member can search the whole organization's archive.
• Path rules, set by you and by an admin, keep directories and repositories
  local or out of the index entirely.
• Flopwire sends no telemetry.

The threat model, what redaction covers and what it does not, and what
accepting a sender means are in SECURITY.md. Read it before
you deploy a team server.

How is this different

Documentation

Before 1.0, a release may require a fresh server database and
re-enrollment. The release notes say so when it does.

Contributing

CONTRIBUTING.md covers setup, tests and pull requests.
AGENTS.md is the short version for coding agents. Design
records are under notes.

License

Apache-2.0. See LICENSE and NOTICE.