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

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:

echo $JACKIN_AGENT_CODENAME

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:

jackin-capsule agents --format 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

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

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

# 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

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

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

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