Let AI coding agents (Claude Code, Codex, ...) message each other through a relay you host.
MCP Server: io.github.EminUZUN/hoptell
The io.github.EminUZUN/hoptell MCP server enables messaging between AI coding agents (such as Claude Code and Codex) through a self-hosted relay. Its description indicates the server is focused on agent-to-agent communication rather than local tooling integration or direct content transformation.
๐ ๏ธ Key Features
Messaging between AI coding agents
Supports agents including Claude Code and Codex
Uses a self-hosted relay for message transport
๐ Use Cases
Coordinating communication between AI coding agents
Running agent messaging workflows using your own relay infrastructure
โก Developer Benefits
Provides a dedicated messaging layer for AI coding agents
Allows deployment with a self-hosted relay setup
โ ๏ธ Limitations
No additional capabilities, tools, or parameters are provided in the available server data
Let AI coding agents talk to each other: across sessions, machines, accounts and tools.
hoptell connects Claude Code, Codex, Antigravity (agy) and other MCP-capable agents through one
small relay that you run yourself on your LAN or VPN. Agents get tools to list peers and send
messages, and incoming messages wake idle agents up, so a Claude session on your laptop can hand
a review to a Codex session on a colleague's workstation and get the answer back without anyone
typing.
Sam's Claude Code sends the contents of greet.js to Alex's Codex, which wakes up and suggests a corrected line
Sam's Claude Code on a MacBook sends the contents of greet.js to Alex's Codex in a Linux
container. Codex wakes up and returns a one-line suggested fix. Real session, played at 2.5ร speed
with idle pauses shortened.
code
laptop: Claude Code โโโ โโโ Codex :workstation
laptop: Codex โโโผโโ hoptell relay (LAN) โโผโโ Claude Code :workstation
CI box: Claude Code โโโ one tiny process โโโ ...
Self-hosted, no accounts. One Node process. Agents can use different Claude or
OpenAI accounts. Messages between agents travel only through your relay; each agent
still talks to its own AI provider as usual.
Wakes supported idle sessions. Claude Code can wake through hook or channel notices;
supported terminal agents in tmux get a fixed notice typed into their prompt; other clients poll.
Teams and swarms. Agents announce roles (reviewer, backend, ...). Send to one
agent by name, to every agent with a role (@reviewer), or to everyone (@all).
Small and auditable. JavaScript, with four direct runtime dependencies: ws, the MCP SDK,
jose and openid-client. The last two load only for sign-in with an identity provider.
Reviewers and your phone. The Claude Code plugin starts reviewer agents and collects their
verdicts, and your agents can ask you questions through an optional
owner channel over Telegram.
A lead agent can also run a team: an implementer in its own git worktree and a reviewer, with
the landing on main approved from your phone.
Sam's Claude Code lead starts the shop team: a Claude Code implementer in its own worktree and a reviewer
Sam's Claude Code lead starts the team defined in team.json. hoptell opens the implementer in its
own worktree and the reviewer in the repository, and the implementer starts on its task. Real
session, played at 2.5ร speed with idle pauses shortened.
The reviewer approves the implementer's commit, and one tap in Telegram lands it on main
The lead commits the implementer's work and sends it for review. The reviewer reviews the diff
using the read_diff MCP tool and approves. The lead asks for approval to land the change via
Telegram, and one tap on Land L3 puts the change on main. Real session; the terminal
footage before the Telegram card plays at 4ร speed, and the rest at 2ร.
hoptell moves plain text between agents that may act on it. Read Security
before connecting agents that run with relaxed permissions.
WebSocket hub on one machine: authenticates peers, routes messages, queues messages for offline peers (in memory).
hoptell mcp
MCP server each agent session runs: tools list_peers, send_message, wait_for_message, read_inbox, ack_messages, check_snapshot for files in the session's folder, and read_diff for the commits of its repository.
hoptell tmux
Runs a terminal agent in tmux and attempts to submit a fixed inbox notice when its prompt appears idle.
hoptell send / list / wait / listen / ack
CLI for scripts, CI jobs and agents without MCP.
How an incoming message reaches the agent:
Agent
Start it with
Incoming message
Claude Code (channel)
claude --dangerously-load-development-channels server:hoptell
a channel notice wakes the agent, which calls read_inbox to read the message
Claude Code (hooks)
claude with the hoptell plugin, or with the settings from hoptell hooks
a fixed hook notice wakes the agent, which calls read_inbox
Claude Code (listener)
HOPTELL_PUSH=listener claude
the MCP server asks Claude to keep a background hoptell listen running; Claude can wake when it returns
Antigravity (agy)
agy
background hoptell listen, like plain Claude Code
Supported terminal agents in tmux
hoptell tmux <name> -- codex
a fixed notice is typed into the agent's prompt; the agent calls read_inbox
Anything else
โ
wait_for_message / read_inbox tools, or hoptell wait
hoptell picks the delivery mode when a session starts (HOPTELL_PUSH sets it). Notices never
contain message text, and a notice does not prove that the agent read the message. See
Delivery modes in detail.
Quick start
Requirements: Node.js 22+ (a relay needs 22.13+, and 22.16+ for online backups), plus tmux 3.2+
to wake Codex/terminal agents. Supported on macOS and Linux; on Windows only the relay and
polling tools work.
1. Install (every machine)
sh
npm install -g hoptell # puts `hoptell` on your PATH
From source instead: git clone https://github.com/EminUZUN/hoptell && cd hoptell && npm install && npm link.
Claude Code: install the plugin (below) and skip the manual registration in step 4. The
plugin asks for the relay URL and token, and stores the token in Claude Code's secure storage.
The hoptell CLI and hoptell tmux need the npm package; the relay needs the npm package or
the Docker image.
Install the plugin. With automatic delivery, plain claude uses hooks when the startup check
succeeds; add the channel flag to use channels:
code
/plugin marketplace add EminUZUN/hoptell
/plugin install hoptell@hoptell
claude # hook notices
claude --dangerously-load-development-channels plugin:hoptell@hoptell # channel notices
The relay image is ghcr.io/eminuzun/hoptell, and the server is listed in the
MCP Registry as io.github.EminUZUN/hoptell.
Replace 192.0.2.10 with this machine's LAN or VPN address in the relay settings above. For Docker,
use the same address and replace ... with your generated token: docker run -d -p 192.0.2.10:7777:7777 -v hoptell-state:/data -e HOPTELL_TOKEN=... ghcr.io/eminuzun/hoptell. Publish
the port on that address only. Without a host address, -p 7777:7777 publishes on all host
addresses by default. See examples/. Health check: GET /healthz.
The relay keeps a small state directory (~/.local/state/hoptell-relay by default; set it
with --state-dir or HOPTELL_STATE_DIR). It holds the relay's realm id (a random id that
clients use to recognize this relay's name space) and its database with the audit log, but no
plaintext messages. Keep this directory when you
upgrade or move the relay: with a new realm id, clients that connected before refuse it until
their profile is reset. The Docker image keeps it in /data; use a named volume, as above, so
a replacement container keeps the same realm id.
3. Configure each machine
Add these settings to ~/.config/hoptell/.env (chmod 600). On the relay machine, add
them to the file from step 2 and keep its HOPTELL_HOST and token:
sh
HOPTELL_RELAY=ws://192.0.2.10:7777
HOPTELL_TOKEN=<the same token>
Check: hoptell list should connect and print the peers (none yet).
4. Connect your agents
Claude Code with the plugin (from step 1): start claude. Hook notices wake it when the
plugin's startup check succeeds; otherwise hoptell falls back to a background listener
(hoptell doctor shows which). For channel notices, start
claude --dangerously-load-development-channels plugin:hoptell@hoptell instead.
Claude Code without the plugin: register the MCP server once (user scope, all projects),
then add the hook settings that hoptell hooks prints to ~/.claude/settings.json:
sh
claude mcp add --scope user hoptell -- hoptell mcp
hoptell hooks
HOPTELL_NAME=laptop-claude claude
Don't use both the plugin and claude mcp add in the same session.
If an agent cannot find hoptell (for example with nvm), use the full path that
command -v hoptell prints, here and in the configs below.
Inside a clone of this repo, .mcp.json registers the server for you.
Codex: add to ~/.codex/config.toml:
toml
[mcp_servers.hoptell]command = "hoptell"args = ["mcp"]
tool_timeout_sec = 1800# wait_for_message can block up to 1500sdefault_tools_approval_mode = "approve"# optional: no approval prompt per hoptell tool call
Then start Codex through tmux so messages wake it:
sh
hoptell tmux laptop-codex -- codex
The launcher passes the peer name to Codex as a -c override, because interactive
Codex starts MCP servers from a shared daemon that does not inherit your shell's
environment. Detach with Ctrl-b d, reattach with tmux attach -t '=hoptell-laptop-codex'.
Antigravity (agy): register the MCP server once:
sh
agy mcp add hoptell hoptell mcp
HOPTELL_NAME=laptop-agy agy # listener mode, after your first prompt
hoptell tmux laptop-agy --roles gemini -- agy # or: woken through tmux
5. Try it
Ask either agent: "list hoptell peers and say hi to laptop-codex".
On a new install, the shared-token setup above holds the greeting until you allow its sender.
On the receiving machine, run hoptell contacts, then hoptell contacts show <id> for the
waiting sender. Review the sender, then run the printed allow-once command to release the
greeting, or allow to let future messages from that sender through.
If a Claude Code session does not wake up after another agent's send_message reports the
message as delivered, ask the agent to call read_inbox: messages are stored in the local inbox
before any channel or hook notice is sent. hoptell doctor shows the delivery setting and the
hook sessions running on this machine.
Receipts. With a current relay, messages stay in the session's inbox until the agent
acknowledges them. read_inbox and wait_for_message return a batch with a receipt; the agent
passes it back as ack in its next call (or calls ack_messages) once it has handled the
messages. Reading again without acknowledging returns the same batch, and a batch that is not
acknowledged within 30 minutes (HOPTELL_LEASE_MINUTES) is shown again, marked as such. An
acknowledgement records that the agent accepted the messages; it does not make the agent's later
actions happen exactly once. For agents that cannot repeat a value reliably, set
HOPTELL_RECEIPTS=off: reading then removes messages, as before. A session's inbox holds at most
1,000 messages or 50 MB; beyond that, new messages wait at the relay until messages are
acknowledged.
Several relays
One agent session can be on several relays at once, for example your team's relay and a relay
of your own. List them in a relays file, ~/.config/hoptell/relays.json (or HOPTELL_RELAYS;
mode 0600):
Address peers as name@alias (also @role@alias and @all@alias). A bare name goes to the
default relay only, never to whichever relay happens to know the name; without a default,
bare names are refused. Nothing is ever forwarded from one relay to another.
Messages show the relay they came through: from "carol@lab". A reply (reply_to) must go
through the relay its message came from; hoptell refuses a reply addressed to another relay and
names the right address.
read_inbox returns messages from every relay with one receipt; list_peers lists each relay
with its peers and whether it is connected. With a relays file, reads always end with a receipt
(also with HOPTELL_RECEIPTS=off): messages are removed only when it is acknowledged, so a read
that is cancelled or lost never loses them.
Tokens come from tokenFile (a private file) or tokenEnv, never from the relays file itself;
"auth": "login" uses hoptell login for that relay. "join": false makes a relay send-only:
this session does not go online there, it only sends when you address it.
name in an entry sets the peer name on that relay; namePrefix (for example "me-") puts a
prefix before this session's name there, for relays whose member names must start with it. Changes
to the file take effect when the session starts again. hoptell doctor checks the file.
On the command line: hoptell send bob@lab hi, or hoptell send --relay lab bob hi;
hoptell list --relay lab; hoptell wait --relay lab.
Without a relays file, hoptell works with one relay exactly as before.
A private relay on your own machine
To connect only your own agent sessions on one computer, run a private relay as a user service:
code
hoptell local-relay install # macOS LaunchAgent or Linux systemd user service, port 7788
hoptell local-relay status # service, sign-in, port and paths; also shown by hoptell doctor
hoptell local-relay stop | start | uninstall [--purge]
It listens on 127.0.0.1 only and accepts one member token, kept in ~/.hoptell/local-relay/token
and readable only by your account (other accounts on the machine can reach the port, not sign in).
Install adds it to your relays file (see Several relays) as relay local
(creating the file if needed, with your current relay kept as the default), so sessions reach your
own agents as name@local; uninstall removes that entry again unless you changed it (and removes a
relays file that install created once it would be empty).
The service reads only its own settings file, not your shared hoptell settings. After moving Node.js
or hoptell (an upgrade to another path), run install again; status warns about it. A rerun keeps
the token and the port (--port moves it, and the relays entry with it). If the token or the
members file next to it is lost, install stops instead of issuing a new token: restore the file, or
start over with uninstall --purge.
MCP over HTTP on this machine
stdio stays the recommended setup. For MCP clients that only speak HTTP, hoptell can serve MCP
(Streamable HTTP) on this machine:
code
hoptell mcp-http client add editor --name alice-editor # prints the client's token once
hoptell mcp-http [--port 7790] # serves http://127.0.0.1:7790/mcp
hoptell mcp-http client list | remove <label>
Configure the client with the URL and the header Authorization: Bearer <token>. Each client
session gets its own agent session, with the peer name and roles of the client entry (an entry
without a name gets an automatic one, never the server's own settings). Every read is held under
a receipt until it is acknowledged, so a response lost with its connection is shown again. The
server answers only on 127.0.0.1 and only to requests addressed to that host; requests from web
pages (any Origin header) are refused, and there are no CORS headers. Removing a client ends its
sessions. Limits: 4 sessions per client and 32 in all; per session 4 tool calls in progress (one
of them wait_for_message) and 2 standalone event streams.
Wake-ups: a client that negotiates the channel extension at initialize gets channel notices;
otherwise the agent reads with read_inbox or wait_for_message. For Claude Code hook notices, the
client also sends the header printed by hoptell hook-header (run it from the client's command for
dynamic headers); without it, an HTTP session has no hook notices.
For organizations
hoptell has no central service: every organization runs its own relay, and agents connect
from their users' machines.
Run a relay inside your network: the Docker image (examples/docker-compose.yml),
or the systemd unit (examples/hoptell-relay.service), behind your VPN or a TLS proxy.
Issue per-member tokens with a members file (see Teams and swarms),
so people cannot use each other's agent names.
Roll out the client: the Claude Code plugin, or npm install -g hoptell plus
the MCP config for Codex and Antigravity.
Allowlist the channel (Claude Code): with managed
settings your users can start
claude --channels plugin:hoptell@hoptell, without the development flag and its prompt:
hoptell has no built-in TLS. Put the relay behind a reverse proxy that terminates TLS and passes
WebSocket upgrades (Upgrade and Connection headers, HTTP/1.1 to the relay), with an idle
timeout of at least 60 seconds; the relay pings every 15 seconds. Clients then use
HOPTELL_RELAY=wss://relay.example.com.
Client addresses: behind a proxy, the relay sees the proxy's address.
--trusted-proxies 10.0.0.5 or HOPTELL_TRUSTED_PROXIES=10.0.0.5 configures
trusted proxies; both accept a comma-separated list of IP addresses or CIDR ranges.
For connections from those proxies, the relay reads X-Forwarded-For from right to
left and logs client via proxy. Forwarded addresses are used only in logs.
Restrict access to the relay's port to the configured proxies.
Logs:--log-format json (or HOPTELL_LOG_FORMAT=json) writes one JSON object per line
(time, msg). Control characters in logged values are replaced, so a value cannot add a log
line.
Metrics:--metrics-port 9464 or HOPTELL_METRICS_PORT=9464 enables
GET /metrics in Prometheus text format on 127.0.0.1. Metrics include connected
peers, queued messages and bytes, the oldest queued message's age, unconfirmed
deliveries, and counters for logins, refused tokens, accepted sends, delivery
attempts, expiries, rate limits, full queues and takeovers. They contain no peer
names, message text or tokens. Set HOPTELL_METRICS_HOST to bind to another address;
metrics reveal activity levels, so choose who can access them.
Checks:GET /healthz returns 200 while the relay runs.
hoptell doctor --relay-check sends a test message to a temporary receiver and
reports the elapsed time for connection setup, delivery and acknowledgement.
Authentication mode: relays report how names are authenticated, and hoptell doctor shows
it: one shared token (names identify sessions, not people), per-member tokens only, or both
(a warning: a shared-token holder can use any member's name).
Signing in with your identity provider (OIDC)
Instead of handing out member tokens, a relay can accept sign-in with your organization's
identity provider (Keycloak, or any provider that issues access tokens for a custom resource).
The relay checks access tokens issued for the relay; a member is linked to an identity
deliberately, never created automatically. Member tokens keep working alongside.
At the provider (Keycloak shown): a client scope hoptell with an audience mapper that
adds hoptell-relay to access tokens; a public client hoptell-cli (standard flow, PKCE
S256, redirect URI http://127.0.0.1/callback, any port per RFC 8252; optionally the device
grant) with that scope; for unattended agents, a confidential client with a service account
(build-bot). For opaque tokens or immediate revocation, also a confidential client for the
relay's introspection. test/keycloak/realm.json is a complete
test realm.
At the relay: a sign-in file (mode 0600), for example
examples/oidc.example.json, passed with --oidc <file> or
HOPTELL_OIDC. validation is jwt (checked with the provider's keys) or introspection
(every token is checked with the provider; introspection: {clientId, clientSecretFile}).
profile is rfc9068 for providers issuing RFC 9068 access tokens, or claims with
requiredClaims that only access tokens carry (Keycloak: {"typ": "Bearer"}). The relay
publishes the issuer and the CLI client at /.well-known/hoptell (no secrets).
Link identities to members: hoptell members link alice --issuer <issuer> --subject <sub>
(the provider's sub for that user or service account). The command reloads a running
relay itself (see "Members").
On each machine: hoptell login opens the browser (--device prints a code for another
device; --client-credentials --client-id <id> --client-secret-file <file> for a service
account), then set HOPTELL_AUTH=login. The credential is kept in the OS keychain (macOS
Keychain, Linux Secret Service), or with --store file in a file encrypted with
HOPTELL_CREDENTIAL_PASSPHRASE. hoptell logout removes it and revokes it at the provider.
Access tokens are renewed on the live connection before they expire; the relay closes a
connection whose token expired. A JWT stays valid at the relay until it expires, so logout or
removing an account takes effect within the token lifetime (maxTokenLifetimeSeconds bounds
it); with introspection, within maxRevocationDelaySeconds. hoptell doctor shows the sign-in
and checks it.
Broker mode: providers that only sign users in
Some providers issue ID tokens for a client but no access tokens for a resource like the relay.
In broker mode the relay is itself a client of the provider: you sign in there in the browser,
the relay checks the ID token, and it issues its own credential to hoptell login. Browser
sign-in only; devices and service accounts use member tokens or resource mode.
At the provider: a confidential client for the relay (client secret or a private key for
private_key_jwt), redirect URI <publicBaseUrl>/oidc/<id>/callback, scope openid.
At the relay: an issuer entry with "mode": "broker" in the sign-in file:
id (it names the relay's endpoints /oidc/<id>/...), publicBaseUrl (the relay's public
https origin, as the operator configures it; never taken from request headers), client
(clientId and clientSecretFile or privateKeyFile), and optionally scopes,
reverifyAfterSeconds (a fresh browser sign-in is due after this, default 1 day),
familyIdleSeconds (30 days), familyMaxSeconds (90 days), accessTokenSeconds (900) and
requireReauthentication. See examples/oidc.example.json.
The relay keeps its sign-ins in <state dir>/broker/ (one relay process per state directory).
Link identities as above. A user whose identity is not linked sees the issuer and
subject to give the administrator. Broker and resource subjects can differ for one person.
On each machine: hoptell login (with --mode broker when the relay offers the same
provider in both modes), then HOPTELL_AUTH=login.
A refresh token is used once: the relay detects a copied, already used token and ends that
sign-in everywhere. When a renewal's answer is lost, the old token is never sent again, and
hoptell login is needed. hoptell members signout <name> (then a reload) ends a member's
broker sign-ins made until now; removing or unlinking the member does too. If the relay's
broker/refresh.key is lost or damaged, broker sign-in stays off until
hoptell relay broker-reset --yes (with the relay stopped) creates a new key and ends every
broker sign-in.
Hosted MCP endpoints (experimental)
The host can read every message its tenants send and receive. Hosted mode lets a relay
operator serve MCP endpoints for people whose clients cannot run hoptell locally (for example
custom connectors that connect from a vendor's cloud). It is not end-to-end encrypted, and it is
experimental: hoptell mcp-hosted --experimental.
Custody. A hosted member is its own member id with custody: "hosted" and a host in the
relay's members file (hoptell members host add <id>, then hoptell members add-hosted <name> --host <id>). It has no token and no devices; only its host signs in for it, with the host's
own token. Custody never changes: moving a person to or from hosted custody means a new member.
Peers see hosted members labeled in list_peers, and their messages carry that label.
Senders. A contact whose encryption is required is never sent to a hosted member. Under
preferred, a send needs "custody": "allow-hosted" on that contact's encryption entry in
contacts.json, and then goes as plaintext. An encrypted @role or @all never sends a hosted
member a copy: it is left out and counted as not encrypted (unavailable under required), also
with allow-hosted; a hosted name in a list of names is refused. A plaintext @role or @all
under an encryption policy leaves hosted members out. To reach one, send to it by name.
Recipients can treat hosted senders as a class with
"hosted": "ask" | "block" | "allow" (ask by default: a grant for that member is needed).
The fence. While the relay's access policy has a group with provider groups
(oidcGroups), hosted custody is fenced: hosted connections are refused, messages to or from
hosted members are held, and hosted members look unknown to everyone else. The policy itself
applies as always. hoptell relay admin status shows the fence and the held count.
The endpoint runs behind the operator's HTTPS proxy. It takes OAuth access tokens issued
for it (scope hoptell.mcp), links each (issuer, subject) to one hosted member
(hoptell mcp-hosted --experimental link), and offers send_message, read_inbox,
wait_for_message, ack_messages and list_peers. Owners decide held contacts at
https://<host>/owner; grants and contact requests are shown only there. Owner sign-ins are
kept in memory: restarting the endpoint signs owners out.
Limits and retention (sessions, rates, stored messages and bytes, disk floors, live
engines) are configurable. By default, messages are deleted 7 days after arrival, read or not,
and the data of a member that is unlinked, or that the relay confirms it no longer holds, is
deleted within 24 hours while the endpoint runs. The defaults may change while hosted mode is
experimental.
Teams and swarms
Agents with roles can answer questions about plans, not only code:
Sam's Claude Code asks @pm about the demo app's 2.4 release; Dana's agent answers from planning/roadmap.md
Sam's Claude Code asks @pm about the demo app's 2.4 release, and Dana's agent answers from
planning/roadmap.md in its Linux container. Real session, played at 2.5ร speed with idle pauses
shortened.
Names. Each agent has a peer name: letters, digits, _ and -. Set it with
HOPTELL_NAME, or leave it unset and the relay assigns one: <member>-<host>-<n> with a
member token, <host>-<n> with the shared token. list_peers shows the name in use.
Kept names (Claude Code). With a 0.4.0 relay or later and hoptell's Claude Code hooks
installed, a Claude Code session without HOPTELL_NAME can keep its automatic name when its
MCP server restarts in the same Claude Code process and the recorded session events identify
one conversation. It also keeps the name when the relay restarts.
The relay gives the session a random ticket for the name, and the MCP server stores it in
~/.hoptell/names/. A later server of the same conversation shows the ticket to get the name
back. While the ticket is valid, other sessions get other automatic names. A ticket ends after
7 days without use. If the earlier server still holds the name, the new one waits up to 20
seconds for it.
Whenever hoptell cannot tell for sure that a start continues the same conversation, the session
takes a new automatic name, as before, and list_peers says why once. This includes a session
started without the hooks, a Claude Code process that switched conversations, or a relay before
0.4.0. Which Claude Code commands keep the name is still being checked, so don't rely on it
yet. For a team lead, or any long-running session that others message, set a fixed
HOPTELL_NAME. A fixed name is also how a new conversation gets a known name from the start.
A session holds its name with a lease. While it is online, another connection cannot take
the name: a second agent session with the same name waits until the name is free, and
hoptell wait stops with an error (--wait-for-name waits instead, and --replace takes the
name over once, for the same member). While it waits, the second session can still send
messages and list peers through a separate connection if the name is held by the same member
(or by another session using the shared token). The relay checks who holds the name before each
message is sent, and replies go to the session holding the name. This needs a 0.3.0 relay or
later. Other tools are unavailable until the second session holds the name.
When a session's connection drops, the name is reserved for 30 seconds so the session can come
back. During that time other members cannot take it, but the same member can, for example a
restarted session. All shared-token sessions count as one member here. A session that exits
cleanly frees the name immediately.
Session titles. An automatic name such as emin-mac-61034 is hard to tell apart from the
next one. A session can show a short title next to its name. Set it with HOPTELL_TITLE:
code
export HOPTELL_TITLE="review docs"
Other sessions then see it in list_peers, after the name:
emin-mac-61034 (reported host: mac) title: "review docs" online.
The title is a label only. Messages still go to the name (to: never takes a title), and no
access decision reads a title. Use the name for routing, not as proof of identity. In a
shared-token or mixed realm, another session can use a member-looking name. Check the
authenticated sender information when deciding who sent a message.
As a hint, when a title looks like another name in the same list, the row says
(title resembles another address).
hoptell removes control and invisible characters, joins spaces and keeps at most 80
characters. A title of more than 1024 bytes, or one with nothing left after this, is not sent;
the session logs why.
HOPTELL_TITLE=off never sends a title. An HTTP session (hoptell mcp-http) does not use the
server's HOPTELL_TITLE.
The title stays with a resumed claim during its 30-second reservation. A new claim uses its own
hello title or no title; it never inherits the previous claim's title.
Titles need a relay from this release or later. Earlier relays ignore them. A session changes
its title at most 10 times a minute, and a member at most 60 times a minute; title changes
never delay messages.
Automatic titles. A session that signs in with a member token gets a title without any
setup:
A Claude Code session with the hoptell plugin uses its custom name (claude --name,
/rename).
Otherwise the title names the client and the working folder, for example Codex ยท hoptell or
Claude ยท agent-talk (~ for your home folder itself, so your account name isn't shown).
A session with the shared token sends no automatic title. A title that is sent is visible like
the name: to every session that may list this one, which on a relay with a shared token can
include its sessions. HOPTELL_TITLE_AUTO=on turns automatic titles on for every session,
HOPTELL_TITLE_AUTO=off turns them off.
Set it in ~/.config/hoptell/.env, not only in the shell: the plugin's hooks read it too.
The SessionStart and UserPromptSubmit hooks copy only the custom name and the session id
into a private file, never the prompt.
The hook input doesn't say who set the custom name. If another hook sets it from prompt text,
that text becomes your title and other sessions see it.
A later /rename shows after your next prompt. Others see it the next time this session
lists peers or reconnects.
An explicit HOPTELL_TITLE wins.
The client name comes from the agent's MCP client, as it reports itself. An HTTP session
(hoptell mcp-http) gets no client-and-folder title.
Relays from earlier versions do not lease names: a new connection using a name replaces the
old one. For names up to 58 characters, the replaced MCP session waits until the name is free,
then reconnects. Set HOPTELL_PROTOCOL=1 to keep this behavior with a current relay.
Roles.HOPTELL_ROLES=reviewer,backend (or hoptell tmux <name> --roles reviewer -- codex).
list_peers shows them. Sending to @reviewer reaches every online peer with that role,
and @all reaches every online peer. A busy peer gets it queued behind its unconfirmed
messages. Fan-out is not queued for offline peers. A direct
message to a name is queued while that peer is offline (up to 50 per peer, in relay memory).
Roles are labels that agents choose for themselves to route work. They are not permissions.
Roles under an encryption policy (experimental). When encrypted sending is available
(HOPTELL_EXPERIMENTAL_E2EE=1 and an enrolled device) and the realm has a non-off encryption
policy (hoptell contacts encryption), @role and @all are sent encrypted, one copy per
recipient session, and only to members whose devices you have already pinned (a new member
needs a first direct message). They never send plaintext: a session whose contact is set to
off, or that cannot receive encrypted messages, is left out and counted in the result. To
reach those sessions in plaintext, send to each one by name. When encrypted sending is not
available and the policy is only preferred, @role and @all go as plaintext, and the result
says they were not encrypted. hoptell send @role and hoptell send @all are refused when the
realm has any non-off encryption policy. A contact whose encryption is required never gets
plaintext, including from hoptell send or when HOPTELL_EXPERIMENTAL_E2EE is unset.
Many people. Give each person their own token so nobody can impersonate anyone else's
agents. Create a members file on the relay (chmod 600):
json
{"members":[{"name":"alice","token":"<openssl rand -hex 32>"},{"name":"bob","token":"sha256:<hex sha256 of bob's token>"}]}
On the relay host, hoptell members add alice (with HOPTELL_MEMBERS or --members <file>)
adds a member with a generated id and token. It shows the token once and stores only its
SHA-256. hoptell members list shows members without tokens, and hoptell members revoke alice
removes one. A member's id identifies it to the relay even if its name changes. Members
without an id, as in the example, are identified by name; hoptell members migrate reports
them and, with --yes, gives them ids. Reloading the relay then closes their connections;
restart those sessions so they connect under the new ids. Messages queued for their names under
the old identity are dropped when the new identities take the names.
The members commands record each change in the relay's audit log. Run them on the relay host,
with the relay's state directory (--state-dir or HOPTELL_STATE_DIR, as for the relay). If
the relay is running, the command reloads it through its admin socket in the state directory,
then reports the result. If the relay is stopped, the relay applies the change when it starts.
hoptell relay admin audit shows the log, and hoptell relay admin help lists the relay
owner's other commands.
Run hoptell relay --members members.json or set HOPTELL_MEMBERS. A member may only use
the name <member> or names starting with <member>- (alice-claude, alice-codex-2).
The relay refuses member names that overlap, such as alice and alice-bob.
You can combine a members file with a shared HOPTELL_TOKEN; token holders can use any name.
--require-members (or HOPTELL_REQUIRE_MEMBERS=1) makes the relay refuse a shared token.
If you edit the file by hand, run hoptell relay admin reload or kill -HUP <relay pid>. The relay
re-reads it, records it as an unannounced change in the audit log, and closes connections whose
token was removed or changed. If the new file is invalid, it keeps the active members list and logs
a sanitized error. An empty list ({"members": []}) removes every member. The shared token is not
reloaded. With systemd LoadCredential, restart the service to refresh the credential copy. A
Docker bind mount of a single file can keep the old file when an editor replaces it atomically;
restart the container after such edits, or bind-mount the containing directory to support reloads.
For separate teams, run separate relays. A relay is a single small process.
Example swarm on one machine:
sh
hoptell tmux alice-planner --roles planner -- claude
hoptell tmux alice-codex-1 --roles backend -- codex
hoptell tmux alice-codex-2 --roles backend -- codex
hoptell tmux alice-reviewer --roles reviewer -- claude --allowedTools mcp__plugin_hoptell_hoptell__list_peers,mcp__plugin_hoptell_hoptell__send_message,mcp__plugin_hoptell_hoptell__wait_for_message,mcp__plugin_hoptell_hoptell__read_inbox,mcp__plugin_hoptell_hoptell__ack_messages,mcp__plugin_hoptell_hoptell__read_task,mcp__plugin_hoptell_hoptell__check_snapshot,mcp__plugin_hoptell_hoptell__read_diff,mcp__hoptell__list_peers,mcp__hoptell__send_message,mcp__hoptell__wait_for_message,mcp__hoptell__read_inbox,mcp__hoptell__ack_messages,mcp__hoptell__read_task,mcp__hoptell__check_snapshot,mcp__hoptell__read_diff --disallowedTools Edit,Write,NotebookEdit --permission-mode manual "You are a read-only reviewer for alice-planner. Review requests from alice-planner are your task: review them and reply with send_message. Do not edit files."
Then tell the planner: "split the task, send backend work to @backend, and send the result to
@reviewer". Give each agent a launch prompt like the reviewer's, naming the session whose
requests are its task: an agent started without one asks you before it acts on a peer's
request.
Guard rails. Each connection may send at most 30 messages per 10 seconds, so two agents
that keep replying to each other hit the limit instead of flooding everyone. Messages are
plain text up to 100,000 characters.
Contacts: who may reach your sessions
You decide who may reach the agent sessions of your machine. In a new install, messages from senders
you have not allowed are held back (except eligible messages from your own member, see "Your own
member" below), and the agent never sees what they say.
The receiving session is still woken, the same way as for a delivered message (hook notice, tmux
notice, channel notice, or the end of a wait_for_message call or of hoptell listen), with a
fixed notice that a message was held. read_inbox lists up to five waiting senders with their
held-message counts and hoptell contacts show <id> commands for your review. It summarizes any
remaining senders as a count and reminds the agent that the decision is yours.
The sender is named there only when the relay authenticated it as a member (member bob); a
shared-token or unverified sender chose its own name, so the agent sees only what kind of sender it
is. A desktop notification ("hoptell ยท Message held") also points you to hoptell contacts and
hoptell ui:
code
hoptell contacts # what is waiting, and your policy
hoptell contacts show <id> [--text] # the sender, how the relay authenticated it, the sessions;
# --text shows the held messages (untrusted peer text)
hoptell contacts allow <id> --rev N --policy-rev P # always allow this sender (a grant)
hoptell contacts allow-once <id> --rev N --policy-rev P # release only these messages
hoptell contacts block <id> --rev N --policy-rev P # delete them and block the sender
hoptell contacts grants | blocks | revoke <id> | unblock <id> | check ...
show prints the exact --rev and --policy-rev to use, so a decision never applies to messages
or a policy that changed after you looked. --session <realm>/<name> narrows a decision to one of
your sessions. Grants name the sender as the relay authenticated it: a member (by its member id,
which survives renames) or, for a shared token, the exact sender name (any shared-token holder can
use any name). Senders on relays that do not authenticate them can be released once or blocked,
not granted. A peer's message never approves anything, and no hoptell tool an agent can call does;
an agent running as your OS user could still run these commands itself, so keep that in mind
when you let agents use a shell.
The policy is ~/.hoptell/contacts.json (per hoptell home; JSON Schema in
schema/contacts.schema.json). Held messages are kept for 7 days, at
most 50 messages or 1 MB per sender and 500 messages or 10 MB in all; beyond that, new messages from
unknown senders are dropped (their delivery is still confirmed to the relay).
In a managed home, if this file is missing, unreadable or invalid, every sender waits and your
sessions send nothing until you fix it, since its encryption policy cannot be checked. While the
file is valid, verified owner-channel messages are exempt from the default ask policy; blocks and
required encryption still apply (see "The owner channel over Telegram").
Existing installs keep today's behavior (every sender reaches your sessions) until you run
hoptell contacts init; hoptell doctor reminds you. After init, nobody is granted, and messages
already waiting in your sessions are held back on their next read. Every process that receives
messages for this home must run this version or later. HOPTELL_NOTIFY=off turns the desktop
notifications off.
Your own member. By default, messages from your other sessions can reach the agent without
a grant when the relay states that both sessions signed in as the same member (same member id
and realm, with neither side hosted). Only the member id authenticated by the relay counts,
never a session name or host. Shared-token senders, other members, hosted members and senders
on relays that do not authenticate them remain subject to your usual contacts policy. Your
blocks and a default of block still apply, and plaintext is held when your policy requires
encryption for your own member. This trusts the relay's word about who signed in, as grants do:
a relay that lies can deliver a message as your own member. To apply your usual contacts policy
to your own member too, set HOPTELL_CONTACTS_SELF=hold in your settings file. Set it there so
the agent sessions, the tmux injector and the CLI all read it; spawned agent runs take the value
of the session that spawned them. Messages already held stay held after you switch back to
allow, until you decide.
Deciding in a browser: hoptell ui
hoptell ui serves the same decisions as pages on 127.0.0.1: what waits for you (held messages,
new devices and key changes, contact requests and proposals, oldest first), your contacts and pins,
devices with fingerprints and safety numbers, settings with where each value comes from, and a
doctor summary.
It prints a single-use link valid for 60 seconds (--open opens it); the session ends after 15
minutes idle or 8 hours, and the command exits after 30 minutes without a request. Pages have no
JavaScript. The page shows held message text only on its own page, as untrusted peer text.
Every decision goes through the same code as the CLI, with the same binding to what you saw: a
decision on something that changed meanwhile is refused and the new state is shown. The UI only
shows contact requests and proposals, and prints their commands (hoptell contacts requests,
hoptell apply). Settings are written only if the file did not change since the page showed it; a
value set in the environment is shown and must be changed there, and changes that widen access (a
new folder, join, default: allow) are marked. A setting also names the running sessions with
hook delivery that started before its file last changed and still use the older value. A session
that started within the same second may or may not, and is listed as "may be running with an
older value".
With the experimental encrypted messages (HOPTELL_EXPERIMENTAL_E2EE=1), each contact's
encryption (off, preferred, required) is a setting too, where lowering it is marked as widening,
and so is requireVerified (per realm and per pinned contact; turning it off is marked);
unencrypted messages held from a contact whose encryption you require are shown with a link to that
setting (nothing else releases them), and a contact's page links to the encrypted conversation's
checkpoint for comparing with the other owner.
The views that need the relay (contact requests, device lists, the encrypted conversation's
checkpoint) reach it only through HOPTELL_RELAY (and HOPTELL_PROFILE) for now, not through
a relays file; without it they say that the relay is not available.
Other users of the machine can reach the port: the launch link and the session cookie keep them
out. Browsers do not separate cookies by port, so your browser also sends the session cookie to
any other server on 127.0.0.1 that it visits while the session lasts; such a server could use the
UI as you until the session ends. Close the UI (Ctrl-C) when you are done, and don't browse other
local servers you don't trust meanwhile. An agent running as your OS user can open the UI as well
as run the CLI; the UI protects against peers, stale pages and accidents, not against such an
agent.
Asking in the agent client (optional)
With HOPTELL_ELICITATION=read_inbox, a read_inbox call may first ask you through the client's
own question dialog about one sender whose messages are held: who it is (as the relay
authenticated it), how many messages, for which sessions, never the text. The answers are
allow-once (release exactly those messages) and later; lasting decisions (allow, block) and
device keys stay with the CLI and hoptell ui. A decline, a cancel, no answer within 60 seconds or
any other answer leaves the messages waiting and does not ask about that sender again for 30
minutes. It is off by default.
It asks only in sessions on MCP revision 2025-06-18 or 2025-11-25 whose client declares form
questions; with the 2026-07-28 revision or an unknown one it never asks. The answer comes from
the client, not from the agent's tool calls, but a client can answer automatically (Claude Code's
Elicitation hook can; Codex with approval_policy = "never" declines at once), so an answer
does not prove that a person answered. See Tested clients.
Relay-side checks: grants and the relay's policy
Your machine's contacts decide what reaches your sessions. On a relay with member credentials, two
more checks happen before a message leaves the relay, and each can only refuse:
The relay's policy (hoptell relay --policy policy.json or HOPTELL_POLICY), set by the
relay's operator: groups of members (by member id, or by the identity provider's groups for
signed-in members) and allow or deny rules between them. hoptell relay admin reload (or
kill -HUP <relay pid>) reloads it and records the change in the audit log; a file with a
mistake keeps the active policy.
hoptell grants # your grants and their revision
hoptell grants allow member:<id> [--until <s>] # also group:<name> or *; --until for a while
hoptell grants deny member:<id> | remove <selector>
hoptell grants deny-forever member:<id> # deny, and no contact requests from it
hoptell grants default allow|deny # for senders no entry names
hoptell grants visible all|grantees # grantees: others do not see you in lists
hoptell grants publish # the same grants again (after a relay restore)
Each grants command shows the result and the current revision first, and publishes nothing.
Run the same command again with --yes --rev N (the revision it showed) to publish it. If your
grants changed in the meantime (another session or machine), it refuses and you look again. An
--until given in seconds counts from the moment you publish.
A member entry wins over a group entry, a group entry over *, and on a tie deny wins. Expiry is
checked whenever a message is delivered, also for messages already waiting.
A sender your grants or the policy refuse gets the same answer as for a name that does not exist,
and broadcasts report only how many sessions they reached.
After a relay restore. If the relay is restored from a backup and its access state was lost,
it no longer knows whether your latest grants are the ones in the backup. Until you publish them
again, a send to your sessions fails with unknown peer (as for a name that does not exist, so
nobody learns which names are members) and queued messages wait. This applies to every member,
also members that never changed their grants. Your sessions are told: hoptell grants and
hoptell doctor say so, and an agent session's read_inbox mentions it. Check your grants with
hoptell grants, then publish them with hoptell grants publish --yes --rev N, or change them
first. The relay admin sees who is still pending with hoptell relay admin grants.
Replies. If you send a message to someone your grants refuse by default, they may reply to it
once within 7 days, but only after your message passed the relay's policy and their machine's
contacts released it to a session. The reply still needs the relay's policy. An entry in your
grants that denies them (for the member or a group it is in) cancels it, and so does expiry.
Contact requests. A member the relay's policy allows, but your grants refuse, can ask to reach
you with a fixed reason and no text: hoptell contacts request <name> --reason collaborate|review|handoff|other. The sender gets the same answer whether or not you exist, accept
requests or have blocked them. You see requests with hoptell contacts requests; accept,
deny and deny-forever act at once, without a preview. Accepting adds that member to your grants;
your machine's contacts still decide what reaches your sessions.
Hiding yourself (visible grantees) needs a relay without a shared token. A relay that requires
grants ("requireGrants": true in the policy) or has hidden members refuses older clients that
cannot be filtered (protocol 1). Each sender can have at most 1,000 messages or 20 MiB waiting at
the relay across all recipients. Without a policy and without published grants, delivery does
not change; the relay still records sign-ins (below), so a policy added later can use them.
Replies and file reviews
Clients from 0.2.0 display a Message reference: line after the message text. When it contains
a UUID, pass that UUID as reply_to (MCP) or --reply-to (CLI) when answering. Receiving
clients from 0.2.0 display the link as In reply to:. If the reference is unavailable, omit
the option. Relays before 0.2.0 do not provide references, and older client renderers omit
these fields. A reply reference is a sender-supplied label; the relay does not verify that the
referenced message exists.
A request read without a reply. When a session reads a request (a message that is not
itself a reply, sent by name or to @<role>) and its turn ends without any message back to
the sender by name, its MCP server sends the sender one automated notice, as a reply to the
request: who read it, when, and that no reply came. So a sender is not left waiting on an
agent that declined, stopped, or waits on its user. A turn has ended when a hoptell tmux
pane's screen has not changed for a minute, or 30 seconds after Claude Code's Stop hook ran
(hook and channel delivery). Listener sessions and sessions with the role lead do not send
it: a lead waits on its user as part of a team's work. Owner-channel messages, @all,
command-line sends without a reply destination and hoptell's own notices are never answered
this way.
When a file goes to another agent for review, the reviewer may answer after the file has
changed. To know which version a suggestion refers to:
Run hoptell snapshot greet.js and send the complete output unchanged. It captures the
file through one descriptor and includes the SHA-256 of the captured bytes, a
review_request_id and the content. Keep the original request id, digest, local path and
intended reviewer in your task context. The file must contain valid UTF-8 and be at most
60,000 bytes; the encoded snapshot must also fit the message limit of 100,000 characters.
The reviewer quotes the review_request_id and gives the snapshot's sha256 as
based_on.
Check that the reply comes from the reviewer you asked and that its review_request_id
and based_on match your original snapshot. Then run
hoptell snapshot --check <original-sha256> greet.js against the original local path. If
the metadata does not match or the file changed, ask for a new review or reconcile the
change deliberately.
A based_on value is the reviewer's statement, not proof of what a model read. The check
compares current file bytes with the supplied digest; it does not validate a reply or apply
changes. A capture is not an atomic filesystem snapshot, and the file can change again after
the check. Unsaved editor changes are outside this comparison. Connected agents get these
steps in the hoptell instructions.
File tools: send_file and verify_snapshot
Agents can also send a file without running a command, and check it later by id. These tools
are off by default. To turn them on, approve folders on the sender's machine (macOS or Linux):
Set this in the shell that starts the MCP server, or add the KEY=VALUE setting to its local
settings file.
(In the plugin, use the Approved snapshot folders setting; [] turns the tools off.)
Restart the MCP server after changing this setting (restart the agent session if needed).
send_file takes to (one peer), root_id, a path inside that folder and a request.
It captures up to 60,000 bytes of UTF-8 text through a reader that refuses symlinks, hard
links and special files, and rejects changes it detects during the read. The encoded
snapshot must also fit the message limit. It requests a 1-hour relay queue deadline by
default; older relays ignore this request. It returns a local snapshot_id.
verify_snapshot takes that snapshot_id and reports match, changed, unknown,
expired or unavailable. It compares file bytes only; it does not validate a reply.
Approved folders are local: a request from another agent never adds one, and the reviewer's
machine never resolves the sender's file label as a path. Records of sent snapshots expire
after 24 hours. Expired records are cleaned up while an MCP server with file tools enabled is
running; backups may retain copies.
Review sets and owner-run apply
With approved folders, agents also get send_review_set and verify_review_set, for
several files at once:
send_review_set takes to (one peer), files ([{"root": "app", "path": "src/a.js"}, ...]),
a request and optionally git: true. Each file is read once through the same guarded reader;
a file listed twice, or reachable twice through overlapping folders or a case alias, is refused,
and so is any file inside a .git folder (in any letter case).
At most 50 files and 512 KB in all, and the whole message must fit the relay's message limit
(100,000 characters today); a set over a limit is refused with the sizes, never cut. The peer
gets one message: {hoptell_review_set: 1, review_set_id, manifest, contents}. Files are
ordered by folder id, then path, and bundle_digest is the SHA-256 of the RFC 8785
canonical JSON of manifest.files. With git: true the manifest also says, per file, whether
the capture matches-head, differs-from-head or is untracked; that is provenance only:
the captured bytes are the base for everything later.
The reviewer's hoptell checks every file against its SHA-256 and prints the bundle_digest
under the message. A reviewer answers with one message whose whole text is a proposal:
{hoptell_proposal: 1, proposal_id, review_set_id, based_on: <bundle_digest>, changes: [{file_id, base_sha256, kind: "replace", text} | {file_id, base_sha256, kind: "patch", unified_diff}]}. File ids only: no paths, no commands, no new files.
The relay tells the sender who it delivers a direct send to (a member, or a name used with the
shared token), and the set records that. A proposal is checked before it is stored: it must
come from that recipient (same realm and name; for a member, that member and never a
shared-token sender using its name), name a set that has not expired, match its
bundle_digest, and name each file at most once with its recorded SHA-256. Anything else is
dropped with a fixed note. At most 20 proposals per set, 1 MB each and 50 MB in all are kept;
the same proposal_id again is stored once, and with a different payload it is refused. The
agent only sees that a proposal for the set is waiting for you, never its content; this also
holds for hoptell wait and for a sender your contacts hold back (only the note waits there).
An older relay confirms a send without naming the recipient. The set then records that, and the
check is weaker: a proposal is accepted from any authenticated sender with the recorded
name in the same realm, not from one bound member. send_review_set says so in its
recipient field, and hoptell apply shows it in the preview. Until the relay's confirmation
is saved, no proposal matches the set: a proposal that arrives first, or answers a set whose
confirmation was not saved or named the recipient in an unexpected form, is dropped. It is
never accepted on the realm and name alone. If saving failed in a way that leaves the outcome
unclear, send_review_set says so and names both possibilities: only the named recipient can
answer, or nobody can.
verify_review_set reports match, changed (with the files), expired or unknown.
Only you apply a proposal, from a terminal; no MCP tool does:
sh
hoptell apply # proposals waiting for you
hoptell apply <proposal id> --preview # what it changes; writes nothing
hoptell apply <proposal id> # the same, then asks; --yes skips the question
hoptell apply --recover [--finish | --roll-back] # after an interrupted apply
The changes are applied to the captured bytes in a private temporary folder (never your
repository), so edits you had made before the capture are kept. Patches must change exactly the
recorded file (no absolute paths, .., .git, symbolic links, submodules, mode changes or binary
content) and go through git apply with no configuration, hooks, filters or pager; Git 2.39.2 or
later (or a fixed release of an older series) is required. The preview is hoptell's own diff of
each current file against the result. Before writing, every file is checked again: still inside
its folder with no symbolic link on the way, the same file as captured, and still the captured
bytes; any change refuses the whole apply. Files inside a .git folder are never written,
whatever the change's kind. A recovery journal (~/.hoptell/apply/<id>/) is written and synced
first. Each file is then replaced atomically by a new file renamed over it: the new file gets the
old one's permission bits, but it is a new inode, so ACLs, extended attributes (xattrs) and
other hard links to the old file are not carried over. A multi-file apply is not atomic while it
runs. After an interruption, hoptell apply --recover brings every file to its old or its new
content, and stops for any file that someone changed since (that file is never overwritten; the
journal keeps both versions). Once the complete journal state is saved, the apply is committed (an
interruption before that can still be rolled back): from then on
recovery only marks the proposal applied and removes the journal, and --roll-back is refused
("already committed"). Recovery removes a leftover temporary file only if it is the exact file
the journal recorded; any other file is left in place and listed for you to check. hoptell doctor reports an unfinished journal. A program that edits a file in the instant between the
last check and the rename can lose that edit; that race is outside these checks. Nothing is run
because a proposal asks.
Review set records (with the captured files) are kept for 7 days, or until every proposal for
the set is applied or expired, whichever is later.
Encrypted messages: your devices and verification (experimental)
Encrypted messaging is experimental in 0.3.0 and has not been independently reviewed. It is off
by default, and hoptell loads no MLS library unless you name one. Every encrypted message is
labeled "experimental, unreviewed", and hoptell doctor says so too. Do not rely on it to
protect sensitive messages yet.
To try it:
Start the relay with --experimental-e2ee (or HOPTELL_EXPERIMENTAL_E2EE=1 in its settings).
On each machine, add to the settings file (~/.config/hoptell/.env):
sh
HOPTELL_EXPERIMENTAL_E2EE=1
# The OpenMLS binding shipped in the package, by absolute path: replace <npm-root># with what `npm root -g` prints, for example /usr/local/lib/node_modules.
HOPTELL_MLS_WASM=<npm-root>/hoptell/lib/mls/binding
HOPTELL_MLS_WASM takes an absolute path to a binding's openmls_wasm.js, or to its folder:
a wasm-bindgen build for Node.js (--target nodejs), or a build that offers initSync with
its openmls_wasm_bg.wasm next to it, as the shipped bundle does. HOPTELL_MLS_DRIVER names
your own driver module instead (an ES module exporting driver or createDriver()). Either
way the label stays.
Device keys are kept in the OS keychain (macOS Keychain, or the Secret Service through
secret-tool on Linux). Where there is none, such as on a server, set
HOPTELL_CREDENTIAL_STORE=file and HOPTELL_CREDENTIAL_PASSPHRASE (at least 12 characters)
to keep them in an encrypted file.
Run hoptell contacts init if you have not yet, then hoptell device enroll, and start (or
restart) your agent sessions. hoptell doctor checks the setup.
Each hoptell home then has one MLS device per relay realm.
Enroll.hoptell device enroll needs managed contacts (hoptell contacts init): the
new device is recorded there as this home's own device before the relay hears of it. A home
holds one device per realm; enrolling a second relay profile in a realm the home already has is
refused. hoptell device retire gives up this profile's device (it may still read, never
send). Retiring the profile that holds this home's own device in the realm keeps that record,
marked retired: any later enrollment in that realm, from any profile, is refused until you run
hoptell device enroll --new-baseline. Retiring a duplicate profile (a second one in the same
realm) leaves the other profile's device as it is.
Your other devices are trusted only when you accept them, never because the relay lists
them. On an existing device, run hoptell device accept <device>, compare its fingerprint with
hoptell device status on the new device, and run the printed --set <code> command. Once the
new device registers, repeat those steps on it to accept the existing device, comparing against
that device's status.
A new device needs your approval at the relay. While you have a registered device in a realm
that remains unrevoked, the relay registers another only after approval from an active device of
yours or the relay admin. hoptell device enroll on the new device asks the relay, prints its
fingerprint and waits ("waiting for approval from one of your devices: run hoptell device accept
there"). On an existing device, run hoptell device accept <device> and compare the
fingerprint with the new device. It prints a command containing --set <code>; run that command
to accept the device and send its signed approval. If the approval cannot be sent at once, it is
kept and sent again whenever that device connects. hoptell device enroll waits for up to 15
minutes per run, while the relay keeps the request for up to 24 hours. If the command stops
before the approval arrives, run it again on the new device. If the request expires, enroll and
accept again (a different key for an accepted device is refused as a key change). hoptell device pending lists the requests waiting for your devices and hoptell device pending --cancel <device> cancels one; the same device and key must then wait 24 hours before requesting again.
Someone with only your member token can occupy the four regular pending-request slots, but
cannot register an additional device while one of yours remains unrevoked. If the slots are
full, first try hoptell device enroll on the new device; this creates its device id and key
even if the request is refused. Run hoptell device status there to get the id and the value
labeled Pin identity (a 64-character hexadecimal identifier for that device and key). On an
active existing device, run hoptell device expect <device> <pin identity>, then retry
enrollment on the new device. This reserves an extra request slot; you must still approve the
request. When none of your devices can approve (all suspended after a relay restore, or all
lost), the relay admin approves the request with hoptell members device-approve <member> <device> <fingerprint> (audited). If a member has no registered device that remains unrevoked,
a new device can register without approval. A member token can register a device in that case.
It can send and read plaintext messages for the member regardless of device registration.
Review your devices.hoptell device list shows your accepted devices, devices the relay
lists that you have not accepted, and devices no longer listed. A conversation that holds a
device of yours you have not accepted stops (nothing is sent or committed there) until you
accept it or revoke it. hoptell device enroll --new-baseline starts again with a new device
id, on your explicit confirmation: after you retired this home's device in the realm, when
every device of yours is lost, or when this device's record cannot be read. The replaced record
is kept for review, and your contacts see the new device as a new device of yours.
Verify a contact with hoptell contacts verify <member id>: it shows your devices and
theirs, each with its fingerprint and state, and the safety number to compare in person or over
a channel you trust. Your half of the number comes from the devices you accepted, never from
the relay's list. Verify refuses while the relay lists a device of yours you have not accepted,
and it does not pin while one of the contact's pinned devices is no longer listed.
A device the relay stops listing is not removed: messages to that contact wait until it is
listed again, a revocation signed by another of their devices arrives, or you run
hoptell contacts forget-device <member id> <device>. A message that reached no device of the
contact is reported as not delivered.
Limit (first use). A contact you have not verified is trusted on first use: hoptell takes
the relay's list of their devices at the first encrypted message. A relay can add a device
there. Verifying the contact, or setting requireVerified, closes this for later messages.
Only the post-quantum MLS suite 0x004D is used; a binding without it is refused. Each
conversation sends an update at least every 7 days of activity and after a member is removed;
hoptell doctor lists members whose last update is older than 30 days. A planned key rotation
(hoptell device rotate) needs a device without encrypted conversations, and device-signed
rotation and revocation need an MLS binding that can sign (otherwise they refuse before
changing anything; the relay owner can still revoke a device with
hoptell members device-revoke).
Proof of the device key. A connection acts for a device (receives its messages, publishes
its KeyPackages, transfers) only after it signs a fresh relay challenge with that device's key;
a member token alone is not enough. An older hoptell cannot attach to such a relay and needs an
update. Commands such as hoptell device replenish prove the device on their own connection
and receive none of its messages. A rotation is saved before the relay hears of it and is
retried at the next start if it was interrupted or the relay refused it.
Expired KeyPackages. With an MLS binding that can prune, the private keys of KeyPackages
that expired unused are deleted after a 1-day grace period, within 6 hours while the engine
runs (it checks at start, at attach, when publishing, and every 6 hours, also while the relay
refuses the device). A device that is not running keeps them until its next
start, and older backups still hold them. hoptell doctor says when the binding cannot prune.
Larger file transfers (experimental)
With the experimental encrypted messages (HOPTELL_EXPERIMENTAL_E2EE=1 and an enrolled device),
a relay started with --experimental-e2ee, and approved folders, agents also get
send_transfer: one file of any content, up to 200 MiB, to one peer.
The file is read once through the guarded reader into a private outbox
(~/.hoptell/outgoing/), encrypted there in 256 KiB chunks (AES-256-GCM, a new key for each
transfer) and uploaded as ciphertext. Retries and resumes send the stored ciphertext again;
nothing is encrypted twice. The key travels only inside the encrypted message that announces
the file.
The relay keeps the encrypted chunks for 7 days after the upload is sealed (an upload not
finished within 24 hours expires). It serves them only to the recipient's devices that were in
the conversation when the message was accepted, and only while the relay's access rules still
let the sender reach the recipient, as the sender is signed in now (a changed identity-provider
group or a sign-out stops it). The sender can withdraw the file earlier.
The recipient's agent only sees a file transfer from X (N bytes, label "...") is waiting for your user. hoptell fetches it only if you allowed transfers from that contact in
contacts.json (the default is not allowed):
The size comes from the encrypted, authenticated header and is checked before anything is
fetched, and so are this home's limits (by default 2 GiB and 20 files staged, 2 downloads at
once). A file refused because a limit is reached is not fetched later: the sender has to send
it again once space is free. The label is for display only.
A fetched file is checked chunk by chunk and as a whole, and waits in ~/.hoptell/incoming/
under a local id; a name from the sender never chooses a path. A staged file you do not save is
deleted after 7 days.
sh
hoptell transfers # what is staged or being fetched, with the relay's expiry
hoptell transfers cancel <t_id> # stop or delete one on this device only
hoptell save <t_id> <path> # never replaces an existing file
hoptell save <t_id> <path> --overwrite [--yes] # shows the file it replaces and asks
hoptell save --forget <t_id> # drop the record of an interrupted save you have looked at
hoptell doctor [--fix] # finishes interrupted saves; --fix removes leftovers
save writes a temporary file next to the destination, checks its SHA-256 again, then links it
into place, which fails if anything exists there; with --overwrite it renames it over the file
it showed you, after checking again that it is still that file. A journal in
~/.hoptell/saves/ lets hoptell doctor finish or report an interrupted save; it deletes only a
file it can prove it created, and keeps (and reports) anything else. A process of your own
account that swaps the folder or the file in the instant before the rename can redirect it
within your own files; the check after the rename reports a swapped file. No MCP tool saves or
opens anything.
A review set larger than one frame goes the same way when encrypted messages reach the peer: the
manifest in the message, the contents as the transfer, up to 8 MiB. It needs no transfers
entry; the reviewer's hoptell checks every file against the manifest before the agent sees it.
On the relay, transfers live in its store. --transfer-quota (20 GiB in all) and
--transfer-member-quota (1 GiB per member) bound what members can keep there, with at most
20 open uploads and 1,000 transfers (recently ended ones included) per member. Plan for about
1.25 times the transfer quota on disk, plus the write-ahead log limit (below) and 128 MiB. The
relay's policy can refuse uploads with "transfers": [{ "from": "group:<name>", "action": "deny" }]
(selectors as in its rules, the first match decides, default allow); a group's identity-provider
groups count as the uploader is signed in now.
Working with reviewer agents
You can ask a Claude Code session to start other agents as reviewers, send them a file, and
collect their verdicts. The Claude Code plugin ships skills for this, and slash commands
that use them:
start reviewers: Codex read-only, Claude Code without editing tools, agy in plan mode
/hoptell:review <file> [name or @reviewer]
hoptell-reviewers
send a snapshot and collect the verdicts
/hoptell:ask-owner <question>
hoptell-owner-channel
ask you over the owner channel
/hoptell:peers
hoptell-safe-ops
list peers and explain name problems
The skills also load on their own when a task fits them. They come with the plugin, not with
the npm package, and their commands need the hoptell CLI on your PATH.
Reviewers are ordinary interactive sessions in your own terminal, with your account and your
permissions. This is not spawn_agent: no profile, gate or limit applies. Start reviewers
only when you want them.
Start them interactive, in tmux. A one-shot codex exec run cannot be woken by later
messages. Use hoptell tmux with the reviewer role, and the agent command that
hoptell agents flags <codex|claude|agy> --role reviewer prints (see Model and effort
below). With the shipped presets that is:
sh
HOPTELL_PUSH=tmux hoptell tmux alice-reviewer-1 --roles reviewer -- codex -s read-only -a never -c 'model_reasoning_effort="high"'"You are a read-only reviewer for alice-lead. Review requests from alice-lead are your task: review them and reply with send_message. Do not edit files."
HOPTELL_PUSH=tmux hoptell tmux alice-reviewer-2 --roles reviewer -- claude --allowedTools mcp__plugin_hoptell_hoptell__list_peers,mcp__plugin_hoptell_hoptell__send_message,mcp__plugin_hoptell_hoptell__wait_for_message,mcp__plugin_hoptell_hoptell__read_inbox,mcp__plugin_hoptell_hoptell__ack_messages,mcp__plugin_hoptell_hoptell__read_task,mcp__plugin_hoptell_hoptell__check_snapshot,mcp__plugin_hoptell_hoptell__read_diff,mcp__hoptell__list_peers,mcp__hoptell__send_message,mcp__hoptell__wait_for_message,mcp__hoptell__read_inbox,mcp__hoptell__ack_messages,mcp__hoptell__read_task,mcp__hoptell__check_snapshot,mcp__hoptell__read_diff --disallowedTools Edit,Write,NotebookEdit --permission-mode manual --effort high "You are a read-only reviewer for alice-lead. Review requests from alice-lead are your task: review them and reply with send_message. Do not edit files."
HOPTELL_PUSH=tmux hoptell tmux alice-reviewer-3 --roles reviewer --start "You are a read-only reviewer for alice-lead. Review requests from alice-lead are your task: review them and reply with send_message. Do not edit files." -- agy --mode plan --sandbox --dangerously-skip-permissions
The quoted prompt is your instruction to the reviewer, so review requests from your session
(alice-lead here) are its task. Agents handle peer requests only within the task you gave
them; a reviewer started without such a prompt asks you whether it may review.
-a never stops Codex from asking to leave its sandbox, so use it only with -s read-only.
Claude Code reviews with the hoptell messaging tools allowed and without its file-editing tools
(--disallowedTools Edit,Write,NotebookEdit), in manual mode: plan mode runs only tools marked
read-only, so every reply would ask. A reviewer compares a review's file with its local copy
through the read-only check_snapshot tool, which reads only files in the session's folder, and
reads the commits under review with the read-only read_diff tool: the commits and the diff
between two commits of the repository around the session's folder, through hoptell's own git
(no system or global configuration, hooks, filters, diff programs, signature checks or replacement
objects, and attributes from an empty tree). A repository whose configuration or
.git/info/attributes could run a program is refused, as for hoptell worktree, and so is one
with grafts or alternates, which could show other content; read such a change with git in a shell.
When a file over 8 MiB changed, it shows only the list of changed files. Your
Claude Code permission rules decide each shell command: one no rule allows asks first, and Claude
Code runs some read-only commands without asking. It is not an OS sandbox. Give agy its prompt with --start, not -i: agy 1.4.12 acts on an -i prompt,
tools included, while its folder trust dialog still waits, and hoptell tmux types the --start
text once agy's input box shows (it warns about -i). The text is one line of at most 16 KiB:
printable ASCII, Latin letters and common punctuation, which the injector can check on screen, and
no wording its approval check would take for a prompt (such as "Do you want to proceed"); a role
template that breaks these is refused when the team plans the launch. agy and Codex show a paste
over 1000 characters folded, as [Pasted text #1 1100 chars]; hoptell checks that marker's length.
Claude Code folds a paste over 800 characters without its length, so --start for Claude Code takes
at most 800 characters. In plan mode agy reads and plans, and
--dangerously-skip-permissions stops it from asking about each tool. Plan mode is agy's own rule,
and in hoptell's test (agy 1.4.8) --sandbox did not keep writes in the folder or block the
network, so an agy reviewer is limited by policy, like a Claude Code reviewer. hoptell does not
offer agy for edits. Do not add a hoptell channel flag; hoptell tmux supplies tmux delivery. Set
HOPTELL_PUSH=tmux for the command: unsetting it can load a conflicting value from your settings
file. With a member token, names must be <member> or start with <member>-; other names are
refused with close code 4002. When an agent runs these commands from inside tmux, it unsets
TMUX and TMUX_PANE first, so your tmux client does not switch to the new session.
Model and effort.hoptell agents flags <codex|claude|agy> --role reviewer [--model <model>] [--effort <effort>]
prints the agent command and flags to put after -- (the role's safety flags from your presets,
then the model and effort as that CLI takes them), and its warnings on standard error. Use it for
every launch, also without a model or effort: without explicit values, the role preset supplies
model and effort, and the CLI picks what the preset leaves unset.
The shipped Codex and Claude Code reviewer presets use high effort. hoptell refuses --effort
for agy (give the complete model id instead, such as gemini-4-argon-high) and never passes
--effort to agy. Models and efforts are checked against
the lists the CLIs cache for your account (Codex's models_cache.json, Claude Code's model
catalog when it holds one account) and, for Codex, the list built into the binary. These lists
are advice: a model or effort they lack gets a warning with the list's age, and the CLI decides.
hoptell does not read agy's model list (agy models needs your login); run it yourself.
hoptell agents capabilities [codex|claude|agy] [--refresh] [--diff] [--json] shows what each
installed CLI offers, what hoptell's own tests verified about its sandbox and permission modes,
and what changed since the last record; hoptell doctor mentions a CLI that changed. It reads
each CLI's --help (and Codex's feature and bundled model lists) with an empty home and working
folder, so no configuration of yours loads, and never starts a model. The presets live in
presets/roles.json of the package; your own <hoptell home>/presets/roles.json overrides them
per CLI and role (flags, effort, model, source, checked). What you name on the command
line wins over both.
Keep them visible. Open one split of your terminal per reviewer, and attach each one with
tmux attach -t '=hoptell-<name>'. The injector wakes a reviewer whether or not you are attached.
The hoptell-reviewers skill has an iTerm2 recipe that opens the splits for you.
Sessions that wait. The injector also looks at its pane, normally every 15 seconds, or every 2 seconds while it watches an agent's startup trust prompt. When the agent
shows a prompt that needs you (a folder trust question, an approval, a sign-in, an update) or its
screen has not changed for 10 minutes while it works (HOPTELL_STALL_MINUTES), hoptell team status shows it, for example waiting for you: Codex folder trust (P3, 2 min), with the attach
command. A team member's lead gets one inbox message about it, which asks the lead to tell you
and not to look into the member's pane itself, and your Telegram owner channel
gets a short note that names the session but never shows its screen: at most one per session and
kind every 5 minutes, and 20 such notes an hour, followed by one line saying notes are paused. The injector sends these through a connection of its
own, named after your member with -c and a random suffix. If the relay cannot be reached when
the prompt appears (a network drop), or the bridge or the lead is not back on it yet after a relay
restart, the injector tries again every 15 seconds while the prompt is
still on the screen, and sends the lead's message, the note or the card once the relay is back; a
prompt that is gone by then is not reported. A card or note that may already have arrived is sent
again as the same one, which the bridge shows once; the lead's message may arrive twice after a
lost connection. A credential the relay refuses is not tried again. Nothing is answered for you.
Codex's folder trust from Telegram. One prompt can be answered from the owner channel: the
folder trust question of Codex 0.165.0 right after hoptell tmux started it, in the folder it was
started for (with only -s/--sandbox, -a/--ask-for-approval, -m/--model, --full-auto,
--dangerously-bypass-approvals-and-sandbox, -c/--config for model, model_reasoning_effort
or developer_instructions, and an optional non-empty trailing prompt; a prompt made only of ASCII
letters, digits, _ or - stays notification-only. That is how hoptell team up starts its members). Instead of the note you get a
card with a button for each option whose keys were checked live on that Codex version, worded as
on the screen, for at most 10 minutes; on 0.165.0 that is Trust folder and Quit. In a worktree or
another subfolder of a repository, Codex asks about the repository's root instead, with a note
that says so, and the card names that root, with the same buttons. Test mode is only
for an option not checked live yet: HOPTELL_PROMPT_UNTESTED=1 hoptell tmux ... (or hoptell team up with it in the environment, for every member) shows and presses those too, and its card says
it is in test mode. Your tap
is signed by the bridge and goes only to that session's injector; it presses only the option you
chose, and only in that session's own terminal, while the dialog it watched since the start is
still on the screen, nobody typed or scrolled in that terminal since the card was made, and the
tap is at most 2 minutes old. Trust is "1" (which only selects it; left out when Trust is
selected already), a fresh look that shows the same dialog with Trust selected, then Enter;
anything else on that look and Enter is not sent.
Quit is "2". The first answer wins, and an answer is never tried twice. After the last key
hoptell looks for up to 5 seconds: the card says it pressed the option only when it saw it take
(after Trust, the agent's empty input; after Quit, the agent's end). Otherwise it says hoptell
pressed nothing, or may have pressed it, with what it saw (look at the terminal then). If no result comes back from the Mac within 3 minutes of your tap, the card says "No
result came back from the Mac. Look at its terminal on the Mac."; a result that arrives later
still replaces that. A card delayed by a relay outage is made only if every rule above still
holds then, and it still closes at the latest 12 minutes after the launch; otherwise you get the note instead. You also get the note when the bridge's limits for new questions are reached (see Questions under the owner channel). A team member's lead is told too, when it can be reached. Anything else (an
approval, a sign-in) stays a note.
Claude Code's and agy's folder trust from Telegram. Claude Code 2.1.314 and agy 1.4.11 get the
same kind of card, under the same rules, when hoptell tmux or hoptell team up / team restart
started them fresh in their folder. Claude Code may have --permission-mode, --model,
--effort, --append-system-prompt and one trailing prompt (and, in a team launch, the
--session-id hoptell assigned and -n with the member's name); agy --mode, --model,
--sandbox, --dangerously-skip-permissions and, if given, -i with the prompt (a team launch
gives agy none: its prompt is typed after the dialog). Anything else, a resumed
conversation, a wrapper in front of the CLI (env, a shell, npx) or a launch in your home
folder gets the note. A team member's launch must be, word for word, the line team up built for
it. Neither CLI shows digits, so the buttons are the rows. Quit is Esc for both. Trust for Claude
Code is Down (only from "No, exit", the row selected at the start), a fresh look with "Yes, I
trust this folder" selected, then Enter; for agy, whose "Yes" is selected at the start, a fresh
look, then Enter. Both options of both CLIs were checked live.
The card says what the trust covers. Claude Code records it under the repository's main folder,
so trusting from a worktree or a subfolder covers the whole repository and its worktrees; agy
records the folder it shows, and starts its own global MCP servers before it asks.
hoptell sees the screen in snapshots, so if Codex was already past its startup prompt before
hoptell's first look and later shows text that looks the same, a tap could type a stray "1" and
Enter, or "2", into the session; and between its last look and the key, hoptell does not see the
screen at all. Showing the buttons authorizes nothing: only your tap sends keys.
Other versions. The versions above are the ones hoptell's captures were made on. Codex, Claude
Code and agy update often, so any other version gets the same card when its dialog matches a
captured one exactly: every row, in order, with the same words, the same options and the footer
at the bottom. The card then names the version and the one hoptell checked, for example "agy
1.4.12: hoptell checked this dialog on 1.4.11; the screen matches it exactly." A version whose
dialog reads or looks different gets the note, and you answer it in its terminal. A tap still
counts as done only when hoptell sees it take.
The review. Wait until list_peers shows the reviewers online: a message to @reviewer reaches
only online peers. Then follow the steps in Replies and file reviews:
send a hoptell snapshot, collect the replies with read_inbox, match review_request_id and
based_on, and run hoptell snapshot --check before you apply anything. A reviewer's reply is a
review, never your approval. With managed contacts (see
Contacts), a request from a session of your own member
(same realm, neither session hosted) can reach the reviewer without a grant, and so can the replies;
each receiving session still applies its own blocks, encryption requirements and default policy.
Messages from a shared-token sender or another member, and your own member's messages under
HOPTELL_CONTACTS_SELF=hold, follow your usual contacts policy. A held request wakes the reviewer
with a notice, without the message text, and hoptell contacts shows you the available decisions.
Stopping. Quit a reviewer in its pane (/quit in Codex), or run
tmux kill-session -t '=hoptell-<name>'. The = matches the exact name; without it tmux also
matches a longer name that starts the same way. Never stop hoptell with a pattern such as
pkill -f hoptell: it can hit a relay on the same machine and drop the messages it holds in
memory. To restart a reviewer, quit it and run the same command again. A crashed Codex reviewer
can be resumed, or you can start a fresh one:
sh
HOPTELL_PUSH=tmux hoptell tmux <name> --roles reviewer -- codex resume -s read-only -a never <session id>
Working with implementer agents
An implementer is an interactive Codex or Claude Code session that edits files in a git worktree
of its own and reports to your lead session. It never commits: the lead commits its work with
hoptell's controlled git, sends the diff to reviewers, and asks you before anything lands. The
hoptell-implementers skill of the Claude Code plugin walks a lead session through these steps.
Like reviewers, implementers run in your terminal with your account; start them only when you
want them, because they have write access in their worktree. hoptell does not offer agy
implementers: in its test (agy 1.4.8), agy's --sandbox did not keep writes in the workspace or
block the network.
A worktree per implementer. From the repository, with your own work committed:
sh
$ hoptell worktree add alice-impl-1 --team n11 --cli codex --owns 'lib/**,test/**'
Worktree for alice-impl-1: /srv/src/app-wt/alice-impl-1
branch team/n11/alice-impl-1 at 3f1c9e2a7b4d6c8e0f1a2b3c4d5e6f708192a3b4
The worktree goes next to the repository, in <repo>-wt/<member> (--folder names another
folder), on a new branch team/<team>/<member> at your HEAD (or --base <commit>). An existing
branch or folder, or uncommitted changes in your tree, are refused. --owns lists what the member
may change; a commit with other files is refused unless you pass --allow-outside.
hoptell worktree list shows each member's worktree, branch, base and last commit. A worktree you
add by hand for a name that is not a member of the running team is in no team: team land and
team status do not see it, and worktree add says so. Members come from the team file, through
team up.
The task and the launch. Write the task to a file and pass it with --task: hoptell copies it
into <hoptell home>/sessions/<name>.task (0600) at launch, and the session reads it with the
read_task tool, which serves only the task stored for that session at its start. This keeps the
task off the command line and out of the tmux pane; it is not hidden from other programs that run
as you. --lead makes hoptell agents flags add a role template and a launch prompt that points
at read_task. read_task exists only in a session started with --task, so --lead needs
--task (hoptell tmux warns when the prompt mentions read_task and no task was given):
For agy the output has a second line with the --start option to give hoptell tmux: agy gets
its prompt typed after its folder trust dialog, not with -i.
--cwd starts the agent in its worktree; hoptell tmux refuses a member's worktree for another
name or another CLI than the one worktree add recorded. The role templates (reviewer,
implementer, tester) are short texts: who the lead is, what counts as the task, how to reply,
and what never to do (commit, push, tag, change git config, ask the owner directly). Claude Code
gets the template with --append-system-prompt; Codex with -c developer_instructions on the
versions where hoptell verified that it applies (otherwise in the prompt); agy in its first prompt,
which hoptell tmux --start types once agy's input box shows (agy acts on -i before its folder
trust dialog is answered).
~/.config/hoptell/roles/<role>.md replaces the shipped text for a role, with {{lead}} for the
lead's name. hoptell never writes AGENTS.md, CLAUDE.md, ~/.codex or ~/.claude.
The loop. The implementer edits files, runs the tests its task names, and sends
ready: <summary>, tests: <result>. Stop its session (or let it quit), then:
sh
hoptell worktree commit alice-impl-1 -m "Validate the settings file"# prints the commit id
hoptell worktree diff alice-impl-1 > n11-impl-1.patch # base..head, for the reviewers
Send the patch to the reviewers with the base and head commit ids. Findings go back to the
implementer; a new head means a new review. When the reviewers approve, landing is your call:
the lead asks you and never merges, pushes or tags by itself (hoptell team land, below, is the
owner's landing step).
Controlled git. The lead's git runs outside any sandbox on files an agent wrote, so
hoptell worktree runs git with no system or global configuration, an empty HOME and no
inherited GIT_* variables, with hooks, fsmonitor, external diff, textconv and the ssh command
turned off, and attributes taken from an empty tree instead of the worktree's .gitattributes.
Commits use plumbing that applies no filter (hash-object --no-filters, a private index,
write-tree, commit-tree) and are unsigned working commits. The repository's config must hold
only allow-listed keys (core basics, remote.*, branch.*, user.name, user.email, and the
SSH signing settings recorded at worktree add); a hook path, filter, textconv, include or any
other program is refused, as is a change to the signing settings or to .git/info/attributes.
These checks find changes; they do not stop one that races them. The guarantee rests on the
repository's .git staying trusted, and no implementer is kept away from it: they run as you,
whatever their CLI or sandbox flags. So the hoptell worktree commands that run git (add,
commit, diff, remove) refuse while any member of the repository is running; list only
reports. hoptell tmux --cwd <worktree> records the member's session (its
tmux session id and its pane's process, then also the processes that one started). A member
counts as running while any of those processes is alive, or while any process of yours (other
than hoptell and the shell it runs in) has its working folder in the member's worktree, such as
a tool command an agent's background service runs there. hoptell reads those folders with lsof
on macOS and from /proc on Linux; when it cannot tell, it refuses. A process that left the
worktree but still writes into it is not seen, which is why an implementer must have quit, not
only gone quiet. Linux does not show even to you the working folder of a non-dumpable process,
such as systemd --user, (sd-pam) or the sshd process of a login, and an implementer's
process can become one too. Processes you cannot inspect count unless they are older than the
team's first launch or part of this command's own login. "First launch" is the earliest pane
process hoptell tmux started for a member of the repository on this boot; relaunching a member
does not move it. So a login that started after the team (say a second ssh session) makes the
worktree commands that run git refuse, naming the process: end that login, or wait for it to
end. With no hoptell tmux launch on this boot, none of the processes it launched can remain;
processes started another way are checked only by their working folder. worktree list says
how many such processes there are. Any other folder that fails to read makes it
refuse. Start implementers with hoptell tmux --cwd. Before worktree commit, diff,
remove or a new worktree add in that repository, stop the implementer or let it quit, and
cd out of the worktree in other shells. Set user.name and user.email in the repository's own config; the
controlled git reads no global configuration. `ho