Communication

Agents talk to each other through initech's IPC layer. Messages are delivered synchronously with a guarantee: if the command returns, the target received it.

The Three Primitives

All three work from inside the TUI (agents calling them) and from external terminals while the TUI is running. They communicate with the TUI process through a Unix domain socket at .initech/initech.sock.

send

The primary communication tool. Injects text into an agent's PTY exactly as if someone typed it.

# Send a task to an engineer
$ initech send eng1 "fix the auth bug in middleware.go"

# Send without pressing Enter (partial input)
$ initech send eng1 "I think the issue is" --no-enter

# Send to a remote agent
$ initech send workbench:eng1 "run the full test suite"

Delivery guarantee: initech send is synchronous. It writes bytes to the target PTY and waits for confirmation. If the command exits successfully, the text was delivered. If the agent is stopped or doesn't exist, the command returns an error. No silent drops.

This is the fundamental difference from tmux's send-keys, which fires and forgets. A dropped message in a multi-agent workflow can stall the entire pipeline because the coordinator never learns that an agent finished.

peek

Read-only observation. Captures what's visible in an agent's terminal pane without disturbing them.

# Last 10 lines from eng1
$ initech peek eng1 -n 10

# All visible content
$ initech peek eng1

Peek is non-intrusive. The target agent has no idea they're being observed. Use it before sending to check whether an agent is in the middle of something.

patrol

Peek at everyone in one command. Prints each agent's output with headers showing their name and activity state.

# All agents, 20 lines each (default)
$ initech patrol

# Only agents that are currently active
$ initech patrol --active

# Specific agents, 5 lines each
$ initech patrol --agent eng1 --agent eng2 -n 5

When to Peek vs Send

A message sent to a busy agent interrupts their current work. Peek first to check state:

Dispatch Patterns

When the super agent (or the operator) dispatches work to another agent, the message follows a consistent structure:

# Dispatch work to an engineer
$ initech send eng1 "[from super] You have work: Add retry logic (ini-42). Claim with: bd update ini-42 --claim --actor eng1. initech send super when done."

The dispatch includes:

• Sender identity: [from super] so the agent knows who sent it
• Task title and ID: what to do and how to track it
• Claim instruction: the exact command to mark the work as in-progress
• Callback instruction: how to report back when done

Role-specific dispatch additions

Response Patterns

When an agent finishes work, they report back to super (or whoever dispatched):

# Engineer completion report
$ initech send super "[from eng1] Add retry logic (ini-42) complete. Tests pass. Pushed commit abc123."

# QA verdict
$ initech send super "[from qa1] Add retry logic (ini-42): PASS. All acceptance criteria verified."

# Blocker escalation
$ initech send super "[from eng1] BLOCKED on ini-42: the API endpoint returns 403. Need auth token config."

The pattern is consistent: [from <agent>] prefix, task reference, then the status or verdict. This structure lets the coordinator (super or the operator) quickly scan messages and understand state.

Cross-Machine Addressing

When agents run on multiple machines via cross-machine coordination, use host:agent format to send messages across machine boundaries:

# Local laptop sends to remote workbench agent
$ initech send workbench:eng1 "fix the auth bug"

# Remote agent sends back to local super
$ initech send laptop:super "[from eng1] ini-42: ready for QA"

# Peek at a remote agent
$ initech peek workbench:eng2 -n 10

Bare names (without host:) resolve to local agents only. The peer names come from peer_name in each machine's initech.yaml. Use initech peers to see all connected machines and their agents.

Scheduled Messages

initech at schedules a message for future delivery. Useful for check-ins, reminders, and timed task triggers.

# Check on eng1 in 30 minutes
$ initech at eng1 "status update please" --in 30m

# Schedule a deploy for 2pm
$ initech at shipper "start the release" --at 14:00

# List pending timers
$ initech at --list

# Cancel a timer
$ initech at --cancel at-1

Scheduled messages are stored in the TUI process. They survive agent restarts but not TUI restarts. See the commands reference for all initech at flags.

How It Works Under the Hood

The TUI process opens a Unix domain socket at .initech/initech.sock when it starts. Every agent's environment includes INITECH_SOCKET pointing to it.

When you run initech send eng1 "hello", the CLI:

• Connects to the socket
• Sends a JSON request: {"action":"send","target":"eng1","text":"hello","enter":true}
• Receives a JSON response: {"ok":true}
• Exits with code 0 (success) or non-zero (failure)

The text is injected into the target pane's PTY character by character through the terminal emulator's key input path. This ensures the target application receives properly encoded input regardless of terminal mode. A brief pause before Enter lets the text settle.

Last updated: April 2026