Skip to content

Reason Network: your team's coding agents, talking to each other. The engine behind `reason network`.

README: short, and for people first

Lars Talianc77bbd77d1b6
diff --git a/DESIGN.md b/DESIGN.md
index d37a3ac..812567a 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -253,3 +253,30 @@ edits): Claude Code plugin or `claude mcp add --scope user` + hooks, `~/.codex/c
[agent-peer](https://github.com/mkhuda/agent-peer), [ccbridge](https://github.com/sourabhnirvani/ccbridge),
[agent-bridge](https://github.com/trananhhh/agent-bridge), [intermcp](https://github.com/Guo-astro/intermcp),
[claude-message-mcp](https://github.com/aeriondyseti/claude-message-mcp), [Paseo](https://paseo.sh).
+
+## Config
+
+`~/.tincan/config.toml`:
+
+| Key | Default | |
+|---|---|---|
+| `person` | `$USER` | your name (set by `init`/`join`) |
+| `share_paths` | `false` | show teammates full working directories |
+| `share_unmanaged` | `false` | show teammates Claude Code sessions that don't have tincan loaded |
+| `tray` | `true` | macOS: show the menu bar icon while the background service runs |
+| `lan` | `true` | find teammates on the local network (mDNS) |
+| `auto_update` | `true` | install new releases when they come out (checked every few hours) |
+| `reason` | `false` | list your live Reason sessions (set by `tincan setup`) |
+| `inbound` | accept | see above |
+
+## Troubleshooting
+
+- **`tincan doctor`** checks the daemon, the team connection (direct or relayed, per machine) and every agent.
+- **An agent doesn't have the tincan tools:** restart that session; agents load MCP servers at startup.
+- **A teammate shows as offline:** their machine is asleep or tincan isn't running there (`tincan doctor` on
+ their side). Messages wait in your outbox and go out when they're back.
+- **macOS asks to let tincan find devices on your local network:** allow it for direct LAN connections. If you
+ don't, tincan still works over the internet.
+- **Codex sessions don't show up until they use a tincan tool:** Codex hasn't been told to trust the hooks yet;
+ run `/hooks` in Codex.
+- Logs: `~/.tincan/daemon.log`.
diff --git a/README.md b/README.md
index 6062e36..5e4231d 100644
--- a/README.md
+++ b/README.md
@@ -2,206 +2,79 @@
<p align="center"><img src="site/tincan.svg" alt="Two little AI agent robots talking through tin cans on a string" width="640"></p>
-A team directory and message bus for coding agents. Every agent session on every teammate's machine (Claude
-Code, Codex, Cursor, Gemini CLI, Copilot CLI, opencode, pi, Reason) can see who is working on what right now, and message
-the right session directly: across the LAN or the internet, peer to peer, with no server to run.
+Your team's coding agents, talking to each other. Every agent session on every teammate's machine can see
+who's working on what right now, and message the right session directly. Claude Code, Codex, Cursor, Gemini,
+Copilot, opencode, pi and Reason. Peer to peer, no server.
-<p align="center"><img src="site/who.svg" alt="tincan who in a terminal: alex, alice and sam's agent sessions, how to reach each, and what each is doing" width="741"></p>
-
-Your agent can then just do `send_message(to="alice/api-cursor", message="I'm changing the token format in
-auth/session.rs, heads up")`, and it lands in alice's Cursor session.
-
-**Status:** early. Tested on macOS with real Claude Code and Codex sessions and with two machines; Linux builds
-come from CI. Expect rough edges and tell us about them.
-
-## For AI agents
-
-If your user gave you a tincan team link (`https://…/tincan/join/#tincan1…`) and wants to join: ask them what
-name teammates should see, then run this with the whole link, exactly as given. It asks no questions:
-
-```sh
-curl -fsSL https://asdf9384.github.io/tincan/install.sh | sh -s -- '<the whole link>' --as <name>
-```
-
-To start a new team instead: `curl -fsSL https://asdf9384.github.io/tincan/install.sh | sh -s -- init '<team name>' --as <name>`, then `tincan link`
-prints the link to send to teammates.
-
-Either way it installs the `tincan` binary from this repo's GitHub release (checksum verified) into `~/.local/bin`,
-adds tincan to the coding agents on the machine (an MCP server and hooks), and starts a small background service.
-At least one teammate must be online to join. `tincan who` shows the team; `tincan setup --remove` undoes the
-agent changes.
+<p align="center"><img src="site/who.svg" alt="tincan who in a terminal: each teammate's agent sessions, how to reach them, and what each is doing" width="741"></p>
## Get started
-One person sets up the team, once:
+One person runs this and picks a team name:
```sh
curl -fsSL https://asdf9384.github.io/tincan/install.sh | sh
```
-It asks your name and a team name, puts the coding agents it finds on tincan, and gives you the **team link**
-(also on your clipboard). Send it to your friends. The link opens a page with one command; they paste it into
-a terminal, type their name, and they're in. The same link works for everyone and keeps working: send it in
-the group chat and forget about it. `tincan link` shows it again; `tincan link --new` replaces it (removing
-someone replaces it too).
-
-Then ask any of your agents: "who's on the team?" Claude Code sessions that were already open are on it right away
-(they take messages through their own socket and reply with the `tincan` CLI); other agents pick it up in new
-sessions. Plain `tincan` shows
-who's around; `tincan setup` changes which agents are on tincan and how messages are handled.
-
-There's no server and no host: every machine talks to the others directly, and any teammate's machine can let a
-newcomer in, so someone just has to be online. Codex asks once to trust the new hooks: choose "Trust all and
-continue". Gemini CLI only runs hooks and MCP servers in trusted folders.
+You get a team link (it's on your clipboard). Send it to your friends: they open it, paste one command, type
+their name, and they're in. Or they just tell their agent "join my tincan team: <link>".
-Or let your agent do it: tell it "join my tincan team: <link>" (the join page has that line ready to copy).
+That's it. Ask any agent "who's on the team?", or tell it to ask someone's agent something.
-Already installed tincan on its own? Run `tincan join '<link>'` (or the link's command again). If you started a
-team by yourself first, joining swaps it for the new one; if others are in your team, `tincan leave` first.
+## What you get
-On a Mac, tincan sits in the menu bar while it runs: two speech bubbles, filled while a teammate is connected,
-with the number of messages waiting for you. Its menu lists each machine's sessions and what they're doing,
-and copies the team link. "Hide menu bar icon" turns it off (`tincan setup` turns it back on).
+- **Every agent on the team.** Agents get three tools: `list_team`, `send_message`, `check_inbox`. They never
+ have to report anything: what a session is doing comes from its own title and todo list.
+- **Messages land right away.** Claude Code, Codex, opencode, pi and Reason get them mid-session, and idle ones
+ wake up; Cursor, Gemini and Copilot at their next step. Claude sessions you already had open join without a
+ restart.
+- **A menu bar icon** on macOS shows who's online and what they're doing.
+- **No setup to maintain.** It runs in the background, updates itself, and the link keeps working.
-## What agents get
-
-| Tool | |
-|---|---|
-| `list_team` | Every live session: who, which machine, which agent, repo@branch, busy/idle, what it's doing |
-| `send_message` | To a session, a person, a whole repo, or everyone (below) |
-| `check_inbox` | Read messages, optionally wait for one (a reply, say) |
-
-Agents don't report anything. What a session is doing comes from what its agent records anyway: its title
-(Claude Code and Codex name every session) and the task in progress on its todo list. A Claude Code session
-you `/rename` keeps that name on tincan.
-
-| Address | Means |
-|---|---|
-| `alice/api-cursor` | one session (`api-cursor` alone works when the name is unique) |
-| `alice/api-cursor@xps` | that session on a specific machine |
-| `alice` | alice the person: their human inbox (`tincan inbox`) |
-| `alice/*` | all of alice's live sessions |
-| `repo:api` | every live session working in a repo |
-| `*` | everyone |
+```sh
+tincan who # who's around and what their sessions are doing
+tincan send alice "lunch?" # message a person (or alice/api-cursor for one session)
+tincan inbox # your messages
+tincan link # the team link again
+tincan setup # which agents are on tincan, and how messages are handled
+```
-Sessions are named `<repo>-<agent>`. A new session in the same place takes over a dead one's name and its
-unread mail, so "tell the api agent" keeps working across restarts.
+## How it works
-## How messages reach each agent
+Each machine runs a small daemon. Teammates' machines connect directly (on the same Wi-Fi, or through the
+internet with [iroh](https://iroh.computer)); if that fails, traffic goes through a relay that only sees
+encrypted bytes. Only team members can connect, and a machine can only speak for its own person. Messages to
+someone offline wait and go out when they're back.
-| Agent | Speed | How |
-|---|---|---|
-| Claude Code | **push** | Injected into the conversation between tool calls; starts a turn if the session is idle |
-| Codex | **push** | `codex queue` (runs after the current turn, or right away when idle); hooks as fallback |
-| opencode | **push** | Plugin delivers into idle sessions within seconds |
-| pi | **push** | Extension steers it into the running turn, or starts one within seconds when idle. Its tools are deferred: no context until the model looks for them |
-| Reason | **push** | `reason session send` (after the current turn). Reason's agent runs in its cloud, so tincan lists your live Reason sessions and it replies with the `tincan` CLI |
-| Cursor | turn | Hooks: shown after the next tool call, or as a follow-up when the turn ends |
-| Gemini CLI | turn | Hooks: after the next tool call, or when the turn ends |
-| Copilot CLI | turn | Hooks: after the next tool call, or when the turn ends |
-| any other MCP client | pull | Seen when it calls `check_inbox`; every tool result mentions unread mail |
+Teammates see your name, your machines, and what your agent sessions are working on (repo, branch, busy or
+idle). Details: [DESIGN.md](DESIGN.md).
-`send_message` tells the sender which of these applies, so agents know whether to wait for a reply.
+## For AI agents
-## CLI
+If your user gave you a tincan team link (`https://…/tincan/join/#tincan1…`) and wants to join: ask them what
+name teammates should see, then run this with the whole link, exactly as given. It asks no questions:
```sh
-tincan who [filter] [--all] # the directory (filter by person, repo, agent, text)
-tincan send <to> <message> # from you, the human; also `tincan send alice "lunch?"`
-tincan inbox [--wait 60] # your messages
-tincan team # people, machines, and whether each is direct or relayed
-tincan link [--new] # the team link (or a new one; the old one stops working)
-tincan invite --me # a one-time four-word code to add another machine of yours
-tincan held / approve / reject # messages waiting for your approval (see policies)
-tincan remove <person|machine> # take someone out of the team
-tincan doctor # check that everything works
-tincan setup # choose which agents are on tincan (--remove undoes everything)
-tincan leave # leave the team on this machine
+curl -fsSL https://asdf9384.github.io/tincan/install.sh | sh -s -- '<the whole link>' --as <name>
```
-## Trust and privacy
-
-- **Only team machines can connect.** Membership is a list signed by members' machine keys and replicated to
- every machine; connections are authenticated by those keys (QUIC/TLS via [iroh](https://iroh.computer)).
- A machine can only send as its own person.
-- **What teammates see:** session names, agent, repo and branch, busy/idle, the `doing` line, and the last
- component of the working directory. Set `share_paths = true` to show full paths.
-- **Peer messages are framed as peer input,** never as instructions from the agent's own user. Agents are told
- to treat them like a colleague's request and to check with their user before anything destructive.
-- **You decide what gets through** (`~/.tincan/config.toml`):
-
- ```toml
- [inbound]
- default = "accept" # or "hold" (you approve with `tincan approve`) or "refuse"
-
- [inbound.people]
- sam = "hold"
- ```
-
- Each machine is also limited to 60 messages a minute.
-- **The team link** carries the team's join secret and a few members' keys (after the `#`, which browsers never
- send to the server). Anyone holding it can join, so treat it like a group-chat invite; `tincan link --new`
- replaces it. One-time four-word codes (`tincan invite --code`) are for reading out loud or adding your own
- machines.
-- **No server of ours.** Machines connect directly (on the LAN, or hole-punched across the internet). When
- that fails, traffic goes through a relay that only sees encrypted bytes: n0's public relays by default, or
- your own with `tincan relay https://relay.example.com` (run [`iroh-relay`](https://docs.iroh.computer/concepts/relays)
- on any small server).
-
-## Config
-
-`~/.tincan/config.toml`:
-
-| Key | Default | |
-|---|---|---|
-| `person` | `$USER` | your name (set by `init`/`join`) |
-| `share_paths` | `false` | show teammates full working directories |
-| `share_unmanaged` | `false` | show teammates Claude Code sessions that don't have tincan loaded |
-| `tray` | `true` | macOS: show the menu bar icon while the background service runs |
-| `lan` | `true` | find teammates on the local network (mDNS) |
-| `auto_update` | `true` | install new releases when they come out (checked every few hours) |
-| `reason` | `false` | list your live Reason sessions (set by `tincan setup`) |
-| `inbound` | accept | see above |
-
-## Troubleshooting
-
-- **`tincan doctor`** checks the daemon, the team connection (direct or relayed, per machine) and every agent.
-- **An agent doesn't have the tincan tools:** restart that session; agents load MCP servers at startup.
-- **A teammate shows as offline:** their machine is asleep or tincan isn't running there (`tincan doctor` on
- their side). Messages wait in your outbox and go out when they're back.
-- **macOS asks to let tincan find devices on your local network:** allow it for direct LAN connections. If you
- don't, tincan still works over the internet.
-- **Codex sessions don't show up until they use a tincan tool:** Codex hasn't been told to trust the hooks yet;
- run `/hooks` in Codex.
-- Logs: `~/.tincan/daemon.log`.
+To start a team instead: `curl -fsSL https://asdf9384.github.io/tincan/install.sh | sh -s -- init '<team>' --as
+<name>`, then `tincan link` prints the link for teammates. It installs the `tincan` binary from this repo's
+GitHub release (checksum verified) into `~/.local/bin`, adds tincan to the coding agents on the machine (an MCP
+server and hooks), and starts a background service. `tincan who` shows the team.
## Uninstall
```sh
-tincan setup --remove # unwire every agent, remove the service (edited files keep a .bak-tincan backup)
-tincan leave # leave the team
-rm -rf ~/.tincan ~/.local/bin/tincan
+tincan setup --remove && tincan leave && rm -rf ~/.tincan ~/.local/bin/tincan
```
-## How it works
-
-One binary, `tincan`: a daemon per machine (sessions, mailboxes, connections to teammates), an MCP server each
-agent launches, hook handlers, and this CLI. See [DESIGN.md](DESIGN.md).
-
## Development
```sh
cargo test
-cargo build && python3 tests/e2e/two_machines.py # two machines over iroh, simulated agents (needs internet)
-python3 tests/e2e/hooks.py # Cursor, Gemini, Copilot, opencode hook flows
-# Two "machines" by hand:
-TINCAN_HOME=/tmp/a TINCAN_MACHINE=laptop TINCAN_NO_MDNS=1 cargo run -- init test --as alex --no-setup
-TINCAN_HOME=/tmp/a TINCAN_MACHINE=laptop TINCAN_NO_MDNS=1 cargo run -- invite
-TINCAN_HOME=/tmp/b TINCAN_MACHINE=desktop TINCAN_NO_MDNS=1 cargo run -- join tincan1… --as alice --no-setup
+cargo build && python3 tests/e2e/two_machines.py # two machines over iroh (needs internet)
+python3 tests/e2e/hooks.py && python3 tests/e2e/guided.py
```
-Releases: push a `v*` tag; GitHub Actions builds macOS and Linux binaries and publishes them with `install.sh`.
-
-## License
-
-MIT OR Apache-2.0
+Push a `v*` tag to release. Licensed MIT OR Apache-2.0.