> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gascity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tutorial 04 - Agent-to-Agent Communication

> How agents coordinate through mail, slung work, and hooks — without direct connections.

Earlier tutorials had *you* talking to agents — peeking at output, nudging
sessions. This one covers how agents talk to *each other*. To follow along you
need `my-city` running with `my-project` rigged and agents for `mayor` and
`reviewer` (the setup from [Tutorial 03](https://docs.gascity.com/tutorials/03-sessions.md)).

## Agents coordinate only through the store

Agents never reference each other. No function calls, no shared memory, no
handles — each session is its own process with its own terminal, history, and
provider. They coordinate through two indirect channels: **mail** (messages) and
**slung work** — `gc sling` (delegated tasks). In both, the sender names a
destination and Gas City routes it; the sender never holds a reference to who
receives it.

![Three agents — mayor, reviewer, worker — drawn as disconnected boxes, each connected only to a central bead store. No arrow links two agents directly; mail is a bead and an inbox is a query for it.](https://mintcdn.com/gascityinc-5c0069dd/-7xr7u3wfBmX5XrM/diagrams/excalidraw-rendered/coordination-through-store.svg?fit=max\&auto=format\&n=-7xr7u3wfBmX5XrM\&q=85\&s=712e9f260fac9cee4120eda9e48f2b1d)

That indirection is the point. The mayor slings work to `my-project/reviewer`
without knowing whether one reviewer session exists or five, whether it runs on
Claude or Codex, or whether it's active or idle. Work and messages persist in the
store; sessions come and go independently — they can run, idle, restart, and
scale without breaking anyone's reference, because there are none.

## Mail is a persistent, tracked message

Mail creates a message the recipient picks up on its next turn. It contrasts
with nudge from Tutorial 03:

| | Mail | Nudge |
| - | - | - |
| Carrier | A bead in the store | Terminal input |
| Survives a crash | Yes | No |
| Subject line | Yes | No |
| Wakes the recipient | No by itself; `--notify` can request a managed wake | Yes |
| State | Stays unread until processed | Fire-and-forget |

Send mail to the mayor:

```shell theme={"dark"}
~/my-city
$ gc mail send mayor -s "Review needed" -m "Please have the my-project reviewer review hello.py"
Sent message gcg-9 to mayor
```

Your message ID will differ. `gc mail send` takes the recipient as a positional
argument and the subject/body via `-s`/`-m` flags. (You can also pass just `<to> <body>` with no subject.)

Mail does not create wake demand by itself. Add `--notify` to request a turn for
the recipient even when earlier mail is still unread. In a managed city, that
request can wake a non-running recipient; an unmanaged city queues the nudge for
later delivery; without a city store the nudge is skipped.

Check for unread mail:

```shell theme={"dark"}
~/my-city
$ gc mail check mayor
1 unread message(s) for mayor
```

See the inbox:

```shell theme={"dark"}
~/my-city
$ gc mail inbox mayor
ID     FROM   SUBJECT        BODY
gcg-9  human  Review needed  Please have the my-project reviewer review hello.py
```

`gc mail inbox` lists only unread messages, so there's no STATE column —
everything listed is unread by definition. (If the mayor has already taken a
turn since you sent the mail, it may have read the message, and these two
commands report no unread mail.)

If you want to see the mayor react right away in `peek` or `logs`, give it a
turn:

```shell theme={"dark"}
~/my-city
$ gc session nudge mayor "Check mail and hook status, then act accordingly"
Nudged mayor
```

(As in Tutorial 03, you may see a `Queued nudge for mayor ...` line instead —
both confirm the nudge is on its way.)

The nudge doesn't deliver the mail — it only starts a new turn. The delivery
happens via a hook: on each turn, `gc mail check --inject` runs and any unread
mail appears as a system reminder in the agent's context. So the mayor never
checks its inbox manually; the hook surfaces mail, and the nudge tells it to act
on what it finds.

## Slung work delegates a task without naming a session

Once the mayor takes a turn, it reads your mail, decides the reviewer should
handle it, and slings the work:

```shell theme={"dark"}
~/my-city
$ gc session peek mayor
[mayor] Got mail: "Review needed" — review hello.py in my-project
[mayor] Routing to my-project/reviewer...
[mayor] Running: gc sling my-project/reviewer "Review hello.py and report feedback"
```

(The above is illustrative — `peek` returns the actual terminal contents of the
session, a screenful of the provider's interface, so you'll see whatever the
agent has rendered, not Gas City–formatted lines. The mayor may phrase the task
differently or take a turn or two before slinging it; peek again to catch up.)

To confirm the hand-off, look for the reviewer's new session (it may already
have finished and shut down if the review was quick):

```shell theme={"dark"}
~/my-city
$ gc session list --template my-project/reviewer
```

The mayor slung a bead to the rig-scoped `my-project/reviewer` agent and Gas
City resolved the rest: it woke the reviewer if asleep, or routed to an
available session if several existed. The mayor describes the work and slings
it; routing is not its problem.

This is the pattern that scales: a human mails the mayor, the mayor plans and
slings tasks to agents, agents do the work and close their beads — every hop
through the store.

## Hooks wire a bare provider into Gas City

Without hooks, a session is just a provider process — Claude in a terminal, with
no awareness of Gas City. Hooks wire the provider's event system in so agents
receive mail, pick up slung work, and drain queued nudges automatically.

`gc init` wires Claude's hooks for you: it writes a managed `.gc/settings.json`
that Claude reads on every session start. No TOML in `pack.toml` or `city.toml`
is needed for the default behavior:

```shell theme={"dark"}
~/my-city
$ grep -rn install_agent_hooks --include='*.toml' .    # prints nothing

~/my-city
$ ls .gc/settings.json
.gc/settings.json
```

Claude is the only provider wired automatically. To run an agent on a different
provider — say you moved the mayor to Codex — list that provider in
`install_agent_hooks` on the agent, and Gas City installs its hook files into the
agent's working directory:

```toml theme={"dark"}
# agents/mayor/agent.toml — install hook files for this agent's provider
install_agent_hooks = ["codex"]
```

Agent-local overrides live in `agents/<name>/agent.toml`. (You can also set
`install_agent_hooks` under `[workspace]` in `city.toml` as a city-wide
default, but that spelling is deprecated — config load warns and points you
at the per-agent form — and an agent-level list replaces the workspace one
rather than adding to it.)

Either way, once a session starts Gas City installs the hook settings the
provider reads. For Claude that's `.gc/settings.json`, which fires Gas City
commands at key moments — session start, before each turn, and right before the
provider compacts its context. Those commands surface pending work, deliver
mail, drain queued nudges, and save a handoff before a context cycle. Without
them you'd run `gc mail check` and `gc prime` by hand on every agent.

## What's next

You've seen the two coordination mechanisms — mail for messages and slung beads
for work — and the hook infrastructure that wires it all together. From here:

* **[The six primitives](https://docs.gascity.com/getting-started/how-gas-city-works.md)** — the canonical model mail,
  slung work, and hooks build on
* **[Formulas](https://docs.gascity.com/tutorials/05-formulas.md)** — how multi-step work should be
  done: steps, dependencies, and variables
* **[Beads](https://docs.gascity.com/tutorials/06-beads.md)** — the work tracking system underneath it all


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.