Agentmux

agentmux

Use agentmux as the supervision layer over tmux.

Core model:

• tmux keeps runtimes alive
• agentmux tracks durable agent identities, state, logs, and events
• prefer agentmux commands over raw tmux when the runtime should stay supervised

Default behavior:

• prefer shell harness for project managers and project workers unless the user explicitly wants opencode, claude, codex, pi, or custom
• use opencode harness only when the user specifically wants an OpenCode runtime inside the managed session
• if the user wants a plain terminal they can later attach to, use shell

Main commands:

agentmux ls
agentmux show <agent>
agentmux logs <agent>
agentmux attach <agent>
agentmux send <agent> "<text>"
agentmux stop <agent>
agentmux kill <agent>
agentmux resume <agent>
agentmux delete <agent> --force
agentmux events --session <agent>
agentmux watch
agentmux console
agentmux web --open

Project workflows:

• create a manager for a repo or lane:

agentmux project-sync <project> --workdir <repo-path> --harness shell

• create a project worker:

agentmux worker <project> <agent-name> --workdir <repo-path> --harness shell

• scope supervision to one project:

agentmux ls --project <project>
agentmux watch --project <project>
agentmux console --project <project>
agentmux events --project <project>

Import workflow:

• if a runtime already exists in tmux, adopt it instead of recreating it
• discover untracked sessions first:

agentmux discover

• import an existing session:

agentmux import --agent <name> --tmux-session <tmux-session> --harness <harness>

• for imported OpenCode sessions, include the native session id when known:

agentmux import --agent <name> --tmux-session <tmux-session> --harness opencode --session-id <ses_id>

Operator guidance:

• use agentmux console for terminal-first supervision with selection, logs, and prompt sending
• use agentmux web --open for browser-based project boards and per-project general-agent control
• use agentmux attach <agent> when the user wants direct terminal control of a runtime
• use agentmux send <agent> "..." for one-shot steering without attaching
• use agentmux logs <agent> or agentmux show <agent> before making assumptions about runtime state

Important details:

• local state lives in .agentmux/agentmux.db
• project manager and worker flows now default to shell; do not switch them to opencode unless requested
• agentmux runtime state is heuristic, so verify with show, logs, attach, or watch when status is unclear
• if tmux is missing, agentmux cannot operate

Opencode harness flags:

• --model provider/model — model override passed as --model to the opencode binary
• --session ses_xxx — resume an existing OpenCode session by passing -s ses_xxx to the opencode binary
• these flags only have effect on the opencode harness; other harnesses ignore them

Examples:

agentmux project-sync agentmux --workdir /absolute/path/to/agentmux --harness shell
agentmux worker agentmux researcher --workdir /absolute/path/to/agentmux --harness shell
agentmux send researcher "inspect the failing route and report back"
agentmux attach researcher
agentmux web --open

Autonomous explorer projects:

An "autonomous explorer" project gives an agent an open-ended goal and lets it self-direct. The manager monitors progress, unblocks when the agent needs human action, and updates the project tracker.

# Create project manager
agentmux project-sync my-project --workdir /absolute/path/to/project --harness shell

# Add autonomous explorer workers
agentmux worker my-project explorer-1 --workdir /absolute/path/to/repo1 --harness opencode
agentmux worker my-project explorer-2 --workdir /absolute/path/to/repo2 --harness codex

# Send initial mission
agentmux send explorer-1 "Read AGENTS.md. Start working toward the goal. Ask the human when you need external steps."

# Monitor
agentmux watch --project my-project
agentmux logs explorer-1

Workflow:

1. Create the project with project-sync
2. Add workers with worker
3. Send each worker its contract/mission as the initial prompt
4. Monitor via logs and watch — intervene only when stuck or needing human action
5. Kill and delete workers when the project is paused or killed