Gangline names, hitches, connects, and observes agents, delivers their messages with sender attribution, and coordinates context compaction. Its startup contract explains delivery and reporting. Your instructions define units of work, decisions, review, and acceptance; Gangline does not track tasks or claims.
An agent is a Claude Code or Codex process running in a named tmux window.
A team is the collection selected by --team, or by GANG_SESSION when
the flag is absent. gang up starts its
first agent with the lead role and attaches your terminal. The lead's brief
asks it to follow operator policy when assigning work to named agents.
Your instructions decide the work and staffing.
A registration records an agent with a fixed ID and a name you can change with
gang rename. Dropping and hitching the same name creates a new registration.
A failed agent keeps its name until it is dropped.
A native session is the conversation history owned by Claude Code or
Codex. It is separate from the tmux session that holds the team. A new
registration can resume a native session with --resume SESSION.
Agents send messages by name. Gangline wraps each message in an envelope
that identifies the sender and delivery attempt. A registered pane supplies
an observed agent name. A sender supplied with --from is marked
self-declared: because Gangline did not observe that identity.
A message forwarded by an enrolled peer host names its sender HOST:NAME for
an agent or HOST:registered:NAME for a registered sender, such as alpha:lead
or alpha:registered:relay. For dedicated peer-key ingress, HOST is bound by the
forced command that gang peer-authorize prints for that key.
gang peer-receive takes HOST from that command rather than from the request.
Its process-ancestry check screens for an sshd session; it cannot identify
the authenticated key or prove that a forced command supplied HOST. NAME and
its class are attributed by that host's Gangline; the receiving host trusts
that attribution. Agent names cannot contain :, so no local
sender can take that form.
The binding holds for that ingress only. Anyone with a shell as the receiving
account can still forge a peer label: a key authorized for the account without
a forced command can run gang peer-receive --peer naming any enrolled host
under sshd, and a local process of that user can write team state or type into
a pane directly. User-namespace processes can also satisfy the ancestry
screen with namespace-local root UIDs; the screen does not establish host-root
ownership across namespaces.
A system sender such as usage-band identifies a message emitted by Gangline. Text supplied
by the caller, such as an interrupt reason, still has an unverified author.
Text typed directly into a window is operator input without a teammate's
envelope.
The receipt tells you who holds the input:
| Receipt | Meaning |
|---|---|
queued |
Gangline holds the message until the recipient can take it. |
accepted |
The native input queue owns it. Do not resend. |
delivered |
The native submit hook confirmed the exact message. |
unverified |
Input may have been typed, but its receipt could not be confirmed. Inspect the pane before acting. |
failed |
The message was not delivered. |
When a message from an agent or the operator is abandoned before its submit
key, Gangline withdraws the paste from the composer with the collar's
compact_clear keys, the message fails, and the rest of the queue waits for a
later drain. Behind a native prompt, on a composer it cannot read, or for a
collar without those keys, the paste may stay in the composer and the message
stays unverified, as it does when something else emptied the composer first.
Gangline's own input, such as startup and notices, is never withdrawn.
None of these receipts means the agent read or acted on the message. A reply
is separate evidence. Queued messages wait while a recipient is alive;
dropping it fails pending messages. When a later operation, not the sending
command, ends a message failed or unverified, Gangline queues a notice naming
the message for the agent that sent it. When hook proof or gang hitch --recover later confirms an unverified message, the sender gets a
notice saying it was delivered, so it does not send the message again.
These later notices reach an agent on the recipient's host only. A sender on a
peer host keeps the receipt the peer returned and cannot inspect the
recipient's pane, so after unverified it asks the recipient whether the
message arrived before sending it again.
A role brief describes how an agent should work. The startup contract
explains messaging and reporting. Optional operator doctrine supplies your
own policy. Gangline combines these with the task supplied when you hitch the
agent.
An assignment envelope contains work to begin; a startup envelope without
a task supplies context only.
For collars that receive standing instructions as messages, the contract,
doctrine, and role senders each supply a separate startup envelope. The
assignment comes last under the hitcher's sender. These envelopes arrive as
one native submission, with their text retained for delivery recovery. A
collar with a role-prompt option receives standing instructions through that
option instead, keeping the assignment in its own envelope.
These instructions are read when the agent is hitched. Editing them does not change an agent that is already running. The reference lists their override files.
Context is the native harness's reported conversation usage. Gangline reports missing readings as unknown. A collar defines context bands by model; crossing one upward queues a notice. Nonfinal bands advise saving state and compacting at a suitable stopping point; the last orders compaction now.
Compaction requests wait for a native idle boundary. The resume note enters native input when compaction starts, ahead of later input, and runs when the harness takes it. Only a completion hook confirms that compaction finished; submitting the compact command or admitting the resume note does not.
A collar is a CUE file that tells Gangline how to launch and communicate with a particular harness. It is a declarative, schema-validated integration contract: the collar describes the connection, and Gangline implements the behavior. The bundled collars support Claude Code and Codex.
A hook is a native callback used to report an event such as message submission or turn completion. Hooks and native readings let Gangline distinguish what happened from what merely appeared on screen.
For package boundaries, state files, and delivery mechanics, see internals.