tongs-agents documentation

[!WARNING] v0.10.0 is an experimental release. Some features have not yet been validated against real harnesses: OpenShell sandboxes, Codex PreToolUse handling and Pi chat delivery, each harness refreshing its tool list when a chat grant changes, and claude mcp add and pi mcp add against the real CLIs. Expect rough edges, check the support matrix for what is live, and report problems at github.com/andre-motta/tongs-agents/issues.

tongs-agents runs your AI coding agents (Claude Code, Codex, Pi or any command) as panes of one Zellij or tmux session, with a sidebar that shows which one needs you. These pages are grouped by what you want to do:

• Tutorials teach by doing. Follow one from the top on a fresh machine.
• How-to guides answer one question each, for when you know what you want.
• Reference pages list every option, file and exit code.
• Background pages explain why things work the way they do.

New here? Start with your first workspace.

Tutorials

1. Your first workspace: install from PyPI, profiles for two Claude Code config dirs, Codex and Pi, install, doctor, workspace and the sidebar.
2. Any command as a pane: profiles with harness other, and status from scripts with tongs-agents notify.
3. One dotfiles directory for every harness: instructions, skills and MCP servers with config status, apply and capture.
4. Driving agents: send, read and wait on a free shell pane, then opt-in MCP agent control.
5. Agent chat and web watching: grants, mentions and wake; watching the workspace read-only from a phone.
6. Sandboxed agents with OpenShell: the setup wizard, a sandboxed profile in the workspace, the sandbox commands, and approving or rejecting access requests in the sidebar (unvalidated against a live gateway).
7. tmux instead of Zellij: the same workspace on tmux, and what differs.

How-to guides

Task	Page
Install tongs-agents from PyPI or a clone, and see what install changes in harness files	Installing
Define agents with their own config dir, cwd, env or model	Agent profiles
Report status from a script or an agent without hooks	Reporting state from any command
Open, reopen or resurrect a workspace	Agent workspace
Resume sessions open in other terminals, or closed long ago, in the workspace	Resume your sessions in the workspace
Set defaults for the workspace, the sidebar and the monitor; pick a theme	App settings
Keep instructions, skills and MCP servers in one dotfiles directory	Config layer
Send prompts to agents from a script	Driving agent panes
Let an agent start and prompt other agents	MCP agent control
Talk to agents and let them talk to each other	Agent chat
Watch the workspace from a browser or phone	Web watching
Run an agent in an NVIDIA OpenShell sandbox	Sandboxed profiles, tutorial
Use Pi	Pi lifecycle integration
Install a pinned Zellij build	Zellij pins and the managed download
Move from claude-fleet-monitor	Upgrading from claude-fleet-monitor

Reference

Topic	Page
Every config.toml section and key	Profiles, app settings, control, dotfiles path, sandbox
workspace options and runtime files	Agent workspace
send, read, wait, agent-status and their exit codes	Driving agent panes
config verbs, entry states and exit codes	Config layer
chat verbs, MCP chat tools, limits and storage	Agent chat
web verbs	Web watching
sandbox commands, the setup wizard and access requests	Sandboxed profiles
Session records, readers and cleanup	Session store
What is supported, with the evidence for each claim	Support matrix
The Zellij pin table	Zellij pins

Every command also prints its options with --help, for example tongs-agents workspace --help.

Background

• Support matrix: what “live”, “instrumented”, “mocked”, “inspected” and “unvalidated” mean, and which label each feature has.
• Harness adapter guide: how a harness reports status, for contributors adding one.
• Session store: why there is no daemon, and who may change the store.
• Agent chat: why chat text is data, not instructions.

The design records under work/ are the project’s internal history (plans, decisions and evidence). They are not user documentation and may describe earlier states of the code.