# Parallel Agent Coordination (https://jackin.tailrocks.com/guides/parallel-agent-coordination/)



When you run multiple agent tabs inside the same jackin' Capsule session — all pointing at the same workdir and branch — each tab gets a unique, stable codename automatically. This page explains what that codename is, how to query the agent registry from inside the container, and how to use both surfaces to coordinate parallel work.

## Agent codenames [#agent-codenames]

Every tab opened in a Capsule session is assigned a unique single-word codename at creation time (for example, `badger`, `falcon`, or `crater`). The codename is:

* **Injected as `JACKIN_AGENT_CODENAME`** into every process spawned in the tab: the primary agent session, any split-pane sessions inside the same tab, and shell sessions.
* **Stable across process restarts.** If the agent's context window fills and the process restarts, the new process inherits the same `JACKIN_AGENT_CODENAME` — it is a tab property, not a process property.
* **Never reused.** Once a codename is assigned to any tab, it is permanently retired for the container's lifetime. Even after the tab is closed, that codename is never given to a new tab. This means an agent reading `badger` in a shared file can never confuse a new tab for the old one.

An agent can read its own codename at any time:

```bash
echo $JACKIN_AGENT_CODENAME
```

## Querying the agent registry [#querying-the-agent-registry]

`jackin-capsule agents` prints the full session registry for the current container: every tab ever opened, including tabs that have since been closed.

```
jackin' agent registry

You are: badger (claude · anthropic)

  codename   agent     provider      started    exited     status
  ───────────────────────────────────────────────────────────────
  badger     claude    anthropic     10:15:02   —          active  ← you
  falcon     claude    anthropic     10:32:15   —          active
  reef       codex     openai        10:17:45   —          active
  crater     claude    anthropic     10:12:00   10:40:11   exited
```

The `← you` annotation marks the calling agent's own row. Active agents appear first, sorted by start time; exited agents follow.

For scripting and tool use, add `--format json`:

```bash
jackin-capsule agents --format json
```

```json
[
  {"codename": "badger", "agent": "claude", "provider": "anthropic", "started_at": "2026-06-04T10:15:02Z", "exited_at": null, "status": "active", "is_self": true},
  {"codename": "falcon", "agent": "claude", "provider": "anthropic", "started_at": "2026-06-04T10:32:15Z", "exited_at": null, "status": "active", "is_self": false},
  {"codename": "reef",   "agent": "codex",  "provider": "openai",    "started_at": "2026-06-04T10:17:45Z", "exited_at": null, "status": "active", "is_self": false},
  {"codename": "crater", "agent": "claude", "provider": "anthropic", "started_at": "2026-06-04T10:12:00Z", "exited_at": "2026-06-04T10:40:11Z", "status": "exited", "is_self": false}
]
```

The registry is **read-only** from the agent's perspective. The capsule daemon is the sole authority on which tabs exist, which codenames are assigned, and when tabs exit. Agents can read the registry but cannot write to it.

## Using codenames to coordinate [#using-codenames-to-coordinate]

The codename and registry give agents the identity infrastructure to self-organize. How they use it is up to you and your role author — jackin' does not prescribe a coordination format or communication pattern.

A common approach is a shared coordination file in the workdir that agents read and update to divide work. Each agent uses its `JACKIN_AGENT_CODENAME` as its identifier in the file, runs `jackin-capsule agents` to understand who else is active, and claims tasks by writing its codename into the shared record.

### Example: file-based task coordination [#example-file-based-task-coordination]

Create a `COORDINATION.md` in the workdir with a task list. A typical structure:

```markdown
# COORDINATION.md

## Tasks

| id       | status      | claimed_by | title                               |
|----------|-------------|------------|-------------------------------------|
| task-001 | done        | badger     | Add auth module skeleton            |
| task-003 | in_progress | badger     | Implement JWT validation middleware |
| task-007 | in_progress | crater     | Write unit tests for validator      |
| task-009 | pending     |            | Integration test end-to-end         |
```

Before claiming a task, an agent should:

1. Run `jackin-capsule agents` to see who is active and who has exited — this helps avoid claiming work that an active agent is already doing.
2. Acquire an exclusive `flock` on `COORDINATION.md`.
3. Re-read the file inside the lock (another agent may have claimed between the read and the lock).
4. Write the claim with its own codename.
5. Release the lock.

The re-read inside the lock is the critical safety step. On a local overlay filesystem inside Docker, `flock(2)` is kernel-enforced and reliable.

### Bootstrap prompt for role authors [#bootstrap-prompt-for-role-authors]

If you want agents to use this coordination pattern automatically, include an instruction in the agent's bootstrap prompt. For example:

```
Your codename for this session is $JACKIN_AGENT_CODENAME.
Before starting work, run `jackin-capsule agents` to see who else is active.
Check COORDINATION.md in the workdir for the task list.
Claim your tasks by writing your codename into the `claimed_by` column.
Always acquire a flock lock before writing to COORDINATION.md, and re-read the file inside the lock.
Update your `last_seen` timestamp every five minutes while working.
```

### Gitignoring the coordination file [#gitignoring-the-coordination-file]

`COORDINATION.md` is session state, not project state. Add it to `.gitignore` so it does not appear in commits:

```
# Agent coordination file — session-scoped, not tracked
COORDINATION.md
```

## Viewing codenames from the host [#viewing-codenames-from-the-host]

The Capsule tab strip shows the agent type and provider for each tab. The codename for a tab is visible in the **hover tooltip** — move your mouse cursor over a tab cell to see the codename as a coloured label directly below the tab strip.

From the host CLI, `jackin status <workspace> <instance-id>` shows the full per-agent table including codenames for every running and exited tab in that instance.

## Codename properties [#codename-properties]

| Property   | Behaviour                                                                                   |
| ---------- | ------------------------------------------------------------------------------------------- |
| Scope      | One container lifetime. Resets when the container restarts.                                 |
| Uniqueness | Globally unique within one container, across all tabs ever opened.                          |
| Reuse      | Never. A retired codename is not reassigned even after the tab closes.                      |
| Stability  | Persists across agent process restarts and context-window resets inside the same tab.       |
| Wordlist   | \~150 words from three semantic families: animals, landforms, weather/celestial.            |
| Fallback   | When all bare words are exhausted, the daemon appends `-2`, `-3`, … to maintain uniqueness. |