Skip to main content
Glama

toli — the telephone for AI agents ☎️

toli (टोली, "toh-lee") is Hindi for a band of people working together.

toli demo: Claude Code on a Mac and Codex on another machine work together through toli

With toli, your AI agents can work together no matter which harness they run in (Claude Code, Codex, OpenCode, OpenClaw, … or one you built yourself) or where they run, and with any agent that already speaks A2A. They can collaborate on one machine or across the internet with a teammate's agents, handing off tasks, asking each other questions and sending back results over the open A2A protocol.

It's not just for coding agents. Any agent with an MCP client can join, so a personal assistant can check with your coding agent before it answers you:

toli demo: an OpenClaw assistant on Telegram works out a delivery date with an OpenCode coding agent through toli

How it works

  • You run one toli daemon. Each of your agents gets a name and a token there, which it uses to reach toli over MCP, on localhost.

  • Each agent has peers: the other agents it's allowed to work with, on your daemon or someone else's. Only you can add peers, never the agent. Pairing exchanges a token in each direction.

  • Agents and their peers send each other tasks over A2A. They can delegate work, ask questions and send back results. When a task arrives, toli wakes your agent and notifies it.

  • You can watch and manage all their tasks in toli (a TUI), or with the CLI.

The toli TUI: an agent's peers and delegated tasks, and one task's conversation between two agents

Related MCP server: agent-network

Install

macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/arjunvlama/toli/main/install.sh | sh

Homebrew:

brew install arjunvlama/tap/toli

Windows (PowerShell):

irm https://raw.githubusercontent.com/arjunvlama/toli/main/install.ps1 | iex

With Go: go install github.com/arjunvlama/toli/cmd/toli@latest

Then start the daemon in the background:

toli daemon install
toli daemon status

toli daemon stop, start and uninstall manage it.

Agents on the same machine

A two-minute quickstart.

1. Add the agents, and connect them to toli. Run this in the folder where you start each agent: where you type claude or codex, or the folder you opened in your editor (its built-in terminal starts there). --connect names the agent's harness (all harnesses), and peers see the description when deciding what to send it.

cd ~/src/web-ui
toli agent add alice --description "Owns the web UI" --connect claude-code

cd ~/src/api
toli agent add bob --description "Owns the API" --connect codex

Each prints what it did:

✓ Added agent 'alice'.
card_url  http://127.0.0.1:7422/a2a/alice/.well-known/agent-card.json
✓ Connected Claude Code to agent 'alice' in ~/src/web-ui (~/.claude.json, .claude/settings.local.json).
Next: start a Claude Code session, or restart a running one (`claude --continue`).

Sessions only pick toli up when they start, so start one in each folder, or restart any that are already running. Then toli agent list shows each agent's harness, which means it's connected. (Some harnesses, like Codex, only show up once you've sent them a message after starting or restarting.)

2. Pair them. alice invites bob:

toli peer invite alice bob
✓ Created an invite for peer 'bob'. It works once, within 24 hours.

To accept it, run this where peer 'bob' runs:

    toli peer accept <agent> toli-invite:eyJ2IjoxLCJhZ2Vu…

Send it privately: whoever has it can pair with agent 'alice'.

bob accepts:

toli peer accept bob <invite>
✓ Paired agent 'bob' with peer 'alice'.

Check they're connected:

toli peer list alice
NAME  CONNECTED  HAS_TOKEN  URL                                                        LAST_ERROR
bob   true       true       http://127.0.0.1:7422/a2a/bob/.well-known/agent-card.json

3. Ask. In alice's session: "Ask bob what it's working on." bob is woken with the task. To watch them work together, run toli (the TUI), or toli task list alice.

Agents on different machines

The steps are the same as on one machine. The daemons just need to be able to reach each other over the network.

Making them reachable. toli doesn't handle networking itself. Your daemon listens for its peers on its A2A address (--a2a-listen, localhost by default), and tells them to reach it at its public URL (--public-url, the A2A address by default). Traffic between daemons is plain HTTP and carries tokens and task contents, so choose how they connect:

  • Tailscale (recommended). Traffic is encrypted, and there are no ports to open. Listen on the machine's Tailscale IP (tailscale ip -4 prints it) and give peers that same address:

    toli daemon install --a2a-listen <tailscale IP>:<port> --public-url http://<tailscale IP>:<port>

    Running toli daemon install again replaces the earlier setup.

  • A network you trust (home, office): do the same with the machine's local IP.

  • The public internet: only behind HTTPS. Keep the daemon listening locally, and put an HTTPS tunnel (Cloudflare Tunnel, ngrok) or reverse proxy in front of its A2A address. Use the tunnel's https:// address as your daemon's public URL. Never make the A2A address itself reachable from the internet.

Then pair them as in step 2. One of you creates the invite and sends it to the other privately, like a password; the other accepts it on their own daemon. To pair without an invite, use toli peer add and toli peer token (toli peer --help).

Connecting your agent to toli

toli connect <harness> <agent> [--scope project|user]

This gives your agent toli's tools (MCP) and notifications, so it's woken when work arrives. Harnesses: claude-code, codex, opencode, pi and openclaw. toli agent add --connect does the same when adding an agent.

  • Run it in the folder where you start the agent. It connects sessions started there; use --scope user to connect all your sessions.

  • It makes a new MCP URL for the agent, so a session still using the old one is disconnected. To use a URL you already have, pass --mcp-url <url> instead of the agent.

  • Then start a new session, or restart the ones already running. Sessions only pick toli up when they start. Once one has started, toli agent list shows its harness, which means it's connected:

    NAME   HARNESS      DISABLED  NOTIFY  CARD_URL
    alice  claude-code  false             http://127.0.0.1:7422/a2a/alice/.well-known/agent-card.json

    Some harnesses only register a session once you've sent it a first message, so if yours doesn't show up yet, say something to it.

  • toli disconnect <harness> undoes it.

Any other agent

Any agent with an MCP client can use toli. Point its MCP client at the agent's MCP URL, which toli agent new-token <agent> prints, to give it toli's tools.

To have it woken when work arrives, use one of these:

  • Pull if your agent is a program: it listens for notifications in the background (pull.py).

  • Push if your agent is a service with an API: toli calls a webhook or runs a program with each notification. Set it up with toli agent notify <agent> --webhook <url> (webhook.py).

See docs/custom-agents.md for how it works.

Security and trust

  • You decide who your agents talk to. Only you can add peers, with the CLI or TUI; an agent can't. Peers you add are trusted. If your agent's harness can be woken, a peer's task starts it working.

  • Tokens. Each agent has a token, in its MCP URL, for talking to the daemon. Each pairing has a token in each direction. toli agent new-token and toli peer new-token replace them.

  • The daemon's MCP server and admin API listen on localhost only. The admin API needs the admin token in ~/.toli.

  • Between machines, use Tailscale or HTTPS (see above). toli's A2A traffic is plain HTTP on its own.

  • Sandbox your agents. toli keeps out peers, browsers and other users, but not an agent running a shell as you, which could read ~/.toli or call the admin API. Run agents in a sandbox that can reach toli's MCP port only: deny ~/.toli/** and the admin API's port (7421 by default).

More

Contributing

For contributors, please see CONTRIBUTING.md, and for more context on the architecture, see ARCHITECTURE.md. We have a lot of ideas for expanding toli, so come chat with us on Discord, or start a thread in Discussions for any idea you have.

If you've found a security vulnerability, please don't open an issue. Report it privately instead, as described in SECURITY.md.

Status

toli is early, but it works. It's tested with Claude Code, Codex, OpenCode, OpenClaw and Pi, and the daemon runs on macOS, Linux and Windows.

toli is licensed under Apache-2.0.

Available Tools

13 tools
accept_taskA

Take on new work (see list_available_tasks). Returns the request and anything else the peer said. To decline instead, use update_task with rejected.

Inputs: task_id (required), message. Returns: state, request, task_id, version, +1 more

cancel_taskA

Stop a task you delegated. Returns canceled, or the final state it had already reached.

Inputs: task_id (required). Returns: state, answer, task_id, version

delegateA

Start a task on a peer (see list_peers). Returns its task_id, state, and version; if the peer answers right away, the answer is included. Use get_delegated_task_updates to follow it.

Inputs: peer (required), message (required), session_id, time_limit_minutes. Returns: state, answer, task_id, version

delete_sessionA

Done with a session: removes it and its tasks, and cancels any still running on their peers.

Inputs: session_id (required). Returns: deleted

get_delegated_task_updatesA

Where a task you delegated stands: its state, everything the peer said since your last message to it, and its outputs so far. With after_version (the version from the last result you saw), waits up to wait_seconds for something new; no need to if this session gets toli's notifications. For the whole conversation, use get_task_full.

Inputs: task_id (required), wait_seconds, after_version. Returns: peer, state, task_id, version, +5 more

get_task_fullB

Everything about a task, delegated or assigned to you: the whole conversation and all outputs. Use it to catch up, not to wait.

Inputs: task_id (required). Returns: peer, state, direct, task_id, +7 more

list_accepted_tasksA

Work you've accepted, newest first: by default what's still in progress, with how many of the peer's messages you haven't responded to.

Inputs: state. Returns: tasks

list_available_tasksA

New work peers sent you that you haven't accepted yet, newest first. With wait_seconds, waits for some if there's none.

Inputs: wait_seconds. Returns: tasks

list_delegated_tasksA

Find the tasks you delegated again, newest first, optionally only a session's or only one state (e.g. input-required).

Inputs: state, session_id. Returns: tasks

list_peersA

The peers you may delegate work to, with what each does and whether it's reachable.

Returns: peers

replyA

Message the peer on a task you delegated: answer its question (input-required) or tell it something while it works.

Inputs: message (required), task_id (required). Returns: state, answer, task_id, version

start_sessionA

Start a session to group related tasks (e.g. "users api"). Pass its session_id to delegate.

Inputs: title (required). Returns: title, session_id

update_taskA

Everything you tell the peer about work you accepted: post progress (working), ask (input-required: all questions in one message; one open question at a time; with wait_seconds, waits for the answer), finish (completed, with artifacts), or give up (failed). Also declines new work (rejected).

Inputs: state (required), task_id (required), message, artifacts, +1 more. Returns: state, answer, task_id, version

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools have distinct purposes, and the accepted-vs-delegated direction is well explained, especially for update_task versus reply. Minor overlap remains among get_delegated_task_updates, get_task_full, and list_delegated_tasks, but descriptions distinguish incremental waiting, full catch-up, and listing.

    Naming Consistency4/5

    The set mostly follows a predictable snake_case verb_noun pattern: accept_task, cancel_task, delete_session, get_*, list_*, start_session, update_task. The bare verbs reply and delegate are minor deviations but remain understandable.

    Tool Count5/5

    With 13 tools, the surface is well scoped for multi-agent task delegation, session management, and peer coordination. Each tool covers a distinct lifecycle or discovery operation, and the count stays within a reasonable range.

    Completeness4/5

    The set covers peer discovery, session creation/deletion, task delegation, acceptance, updates, messaging, cancellation, and completion/failure. Minor gaps exist around listing or inspecting sessions and possibly viewing task details before acceptance, but core workflows are covered.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      A local MCP server that connects AI coding agents (Claude Code, Codex, Cursor, etc.) on the same machine via a shared message bus, enabling them to chat, delegate tasks, and collaborate privately without cloud or internet.
      33 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Local-first shared memory and task coordination for AI coding agents. One Go binary, MCP server, markdown files you own. Hooks for Claude Code and Codex CLI (and their desktop apps).
      30
      6
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables multiple coding agents (Claude Code, Codex, Cursor) to discover each other's sessions, search transcripts, ask questions, and handoff tasks through a shared MCP server.
      5
      6 npm
      MIT