Configuration

Complete initech.yaml reference. This file lives in your project root and drives everything: which agents to launch, how they run, and how machines connect.

Project

Field	Type	Default	Description
project	string	required	Project name. Used as the TUI session name and displayed in the title bar.
root	string	required	Absolute path to the project root directory. Supports `~` expansion. All agent workspace directories live under this path.
repos	list	[]	Source code repositories. Each entry creates a git submodule in agent workspaces that need source access (eng, qa, shipper).

Each entry in repos has:

Field	Type	Description
url	string	Git remote URL (e.g., `github.com:you/repo.git`)
name	string	Local directory name for the submodule (appears as `src/` or `<name>/` in agent workspaces)

project: myproject
root: /Users/you/projects/myproject
repos:
    - url: github.com:you/myproject.git
      name: myproject

Beads Integration

Optional integration with the beads issue tracker. When enabled, agents can report bead assignments and the TUI displays bead status in the overlay.

Field	Type	Default	Description
beads.enabled	bool	true	Set to `false` to disable beads integration entirely. When disabled, `initech bead` and `initech standup` are no-ops.
beads.prefix	string	""	Bead ID prefix for this project (e.g., `ini` produces bead IDs like `ini-42`).

beads:
    enabled: true
    prefix: ini

Agent Command

These fields control what command runs in each agent pane. The resolution order is: per-role command (if set) overrides everything, then per-role claude_args, then global claude_args, then the role catalog default.

Field	Type	Default	Description
claude_command	list	["claude"]	Base command and initial arguments. Applied to all agents unless overridden per-role.
claude_args	list	[]	Additional arguments appended to the base command. Common: `["--continue", "--dangerously-skip-permissions"]`.

Arg resolution priority

For each agent, initech resolves the launch command in this order:

If role_overrides.<role>.command is set, use it as the complete command (nothing else is appended)
If role_overrides.<role>.claude_args is set (even if empty), use claude_command + those args
Otherwise, use claude_command + global claude_args
If nothing is configured, the role catalog default applies (autonomous roles get --dangerously-skip-permissions, supervised roles get nothing)

# Global: all agents run ccs work with continue + skip permissions
claude_command: ["ccs", "work"]
claude_args: ["--continue", "--dangerously-skip-permissions"]

# Per-role: super gets no extra args (supervised)
role_overrides:
    super:
        claude_args: []

Roles

Field	Type	Default	Description
roles	list	required	Agent names to launch. Each name becomes a TUI pane, a workspace directory, and a messaging target. Names must match `[a-zA-Z0-9_-]+`.
grid	list	same as roles	Subset and ordering of roles for the TUI grid. If omitted, all roles are displayed in the order listed in `roles`. Use this to control which agents appear in the grid and in what order.

Any name works. The 11 built-in roles (super, eng1, eng2, qa1, qa2, pm, pmm, arch, sec, shipper, writer, ops, growth) get tailored CLAUDE.md templates on initech init. Custom names get a generic template.

roles:
    - super
    - eng1
    - eng2
    - qa1
    - pm
    - shipper

Role Overrides

Per-role customization. Each key must match a name in the roles list.

Field	Type	Default	Description
command	list	-	Override the entire agent command. When set, `claude_command` and `claude_args` are ignored for this role. Use for non-Claude agents.
claude_args	list	-	Override global `claude_args` for this role. An empty list `[]` means no extra args (useful for supervised roles).
agent_type	string	"claude-code"	Agent runtime type. Affects input injection and readiness detection. Values: `claude-code`, `codex`, `opencode`, `generic`.
auto_approve	bool	false	Auto-approve matching permission prompts for this agent.
no_bracketed_paste	bool	false	Use character-by-character input injection instead of bracketed paste. Required for some non-Claude agents.
submit_key	string	"enter"	Key to submit input. `"enter"` or `"ctrl+enter"`.
tech_stack	string	""	Tech stack for CLAUDE.md template rendering (e.g., `"Go 1.25"`).
build_cmd	string	""	Build command for CLAUDE.md template (e.g., `"make build"`).
test_cmd	string	""	Test command for CLAUDE.md template (e.g., `"make test"`).
dir	string	""	Override the workspace directory for this role.
repo_name	string	""	Which repo from the `repos` list this role should use as its `src/` submodule.

role_overrides:
    # Claude Code agent with specific args
    eng1:
        command: ["ccs", "work", "--continue", "--dangerously-skip-permissions"]
        agent_type: claude-code

    # Codex agent with auto-approve
    growth:
        command: ["codex", "resume", "--last", "--full-auto"]
        agent_type: codex

    # Supervised role (no skip-permissions)
    super:
        claude_args: []

Resource Management

Field	Type	Default	Description
resource.auto_suspend	bool	false	Enable automatic agent suspension under memory pressure. The TUI monitors system memory and suspends the least-recently-active agents when pressure exceeds the threshold.
resource.pressure_threshold	int	85	RSS percentage (0-100) above which auto-suspend activates.

resource:
    auto_suspend: true
    pressure_threshold: 80

MCP Server

Exposes agent primitives as MCP tools over HTTP. Any MCP-compatible client (Claude in another session, Cursor, VS Code Copilot) can connect and observe or steer agents. See MCP docs for full details.

Field	Type	Default	Description
mcp_port	int	disabled	Port for the MCP HTTP server. Set to enable (e.g., `9200`). Omit or set to `0` to disable.
mcp_token	string	auto-generated	Bearer token for MCP authentication. If empty, a random 32-byte token is generated on startup and printed to the TUI. Also settable via `INITECH_MCP_TOKEN` env var.
mcp_bind	string	"0.0.0.0"	Bind address for the MCP server. Set to `"127.0.0.1"` to restrict to localhost.

mcp_port: 9200
mcp_token: your-secret-token-here
mcp_bind: 0.0.0.0

Cross-Machine

Run agents across multiple machines. The local TUI connects to remote headless daemons and renders all agents in one grid. See cross-machine docs for the full setup walkthrough.

Field	Type	Default	Description
peer_name	string	""	This instance's identity for cross-machine addressing. Used as the `host:` prefix in `host:agent` format. Names must match `[a-zA-Z0-9-]+` (no underscores or colons).
mode	string	"" (TUI)	Set to `"headless"` for daemon mode (`initech serve`). When omitted or empty, runs the normal TUI.
listen	string	""	TCP listen address for headless mode (e.g., `":7391"` or `"0.0.0.0:7391"`). A bare port binds to `127.0.0.1`.
token	string	""	Shared auth token for peer connections. Both sides must use the same token.
remotes	map	{}	Named remote peers to connect to on TUI startup.

Each entry in remotes has:

Field	Type	Description
addr	string	Host and port of the remote peer (e.g., `"192.168.1.100:7391"`)
token	string	Auth token for this specific remote. Overrides the project-level `token`.

# Local TUI config (laptop)
peer_name: laptop
remotes:
    workbench:
        addr: "192.168.1.100:7391"
        token: shared-secret

# Remote daemon config (workbench)
# peer_name: workbench
# mode: headless
# listen: ":7391"
# token: shared-secret

Environment Variables

initech sets these environment variables in each agent pane automatically:

Variable	Description	Example
INITECH_SOCKET	Path to the IPC Unix domain socket. Used by `initech send` and `initech peek` to communicate with the TUI.	`/path/to/project/.initech/initech.sock`
INITECH_AGENT	Name of the current agent. Used by `initech bead` for auto-detection.	`eng1`
BEADS_DIR	Path to the beads database directory. Set when beads integration is enabled.	`/path/to/project/.beads`
TERM	Terminal type. Always set to `xterm-256color`.	`xterm-256color`
LINES / COLUMNS	Terminal dimensions matching the pane size. Updated on resize.	`40` / `120`

Full Example

A complete initech.yaml showing all sections:

# Project identity
project: myproject
root: /Users/you/projects/myproject

# Source repositories (become git submodules in agent workspaces)
repos:
    - url: github.com:you/myproject.git
      name: myproject

# Beads issue tracker
beads:
    prefix: mp

# Cross-machine identity
peer_name: laptop

# Default agent command (all agents unless overridden)
claude_command: ["claude"]
claude_args: ["--continue", "--dangerously-skip-permissions"]

# Agents to launch
roles:
    - super
    - eng1
    - eng2
    - qa1
    - pm
    - shipper
    - growth

# Per-role customization
role_overrides:
    # Supervised: no auto-permissions
    super:
        claude_args: []
    shipper:
        claude_args: []

    # Non-Claude agent
    growth:
        command: ["codex", "resume", "--last", "--full-auto"]
        agent_type: codex

# Resource management
resource:
    auto_suspend: true
    pressure_threshold: 85

# MCP server (external tool integration)
mcp_port: 9200
mcp_token: your-secret-token

# Remote machine connections
remotes:
    workbench:
        addr: "192.168.1.100:7391"
        token: shared-secret

Commands

TUI

Last updated: April 2026