> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.heard.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.heard.dev/_mcp/server.

# Multiple agents

When several sessions are active, Heard ranks events by importance. A blocked session or a decision waiting on you can speak before routine progress from another session, while background work is summarized.

## How routing works

Heard considers signals such as:

* A question or approval waiting on you
* A failed command or test
* A blocker that prevents the session from continuing
* A final result or completed task
* Routine progress that can wait for a later summary

Each active session can receive a distinct voice so you can identify it by ear, and Heard announces the project name when the speaker changes.

With **Spatial audio** enabled in [Settings](/settings), the background project also speaks slightly to the side on stereo output, so two parallel sessions separate in space as well as in voice.

## Follow sessions in the notch

In the managed app, [the notch](/the-notch) is the visual counterpart to routing: every active session is a lane with its own status mark, a question expands into a focused card you can answer in place, and a finished session pops its result. Click a lane to jump to that session's terminal.

## Pin a session (open source engine)

The open source engine's menu bar app lists sessions under **Active agents**. Click a session to pin it when it should have your full attention, and click it again to return to automatic ranking.

## Give a project a spoken name

Add a label to the project level `.heard.yaml` file when the folder name is unclear:

```yaml title=".heard.yaml"
label: Checkout service
```

Heard uses that label when it announces the project.

Focus mode pairs well with parallel work because routine progress stays quiet while decisions, blockers, and failures still reach you.