tongs-agents

tongs-agents is one workspace for the AI coding agents you run side by side. It starts Claude Code, Codex, Pi or any other command as real panes of a Zellij (or tmux) session, puts a sidebar next to them that shows which agent is working, done or waiting for you, and takes you to that pane.

It reads status from each harness's own hooks, so it does not care which harness an agent runs in. There is no daemon and no telemetry: hooks write small JSON records, and the sidebar, the monitor view and the MCP tools read them.

tongs-agents is a standalone companion app in the tongs family. It runs on its own; tongs is an optional neighbour tab in the workspace, and the [tongs] extra adds an Agents screen to tongs.

Formerly claude-fleet-monitor; see Upgrading from claude-fleet-monitor.

Quick start

You need Python 3.11 or newer. The workspace needs Zellij 0.44.2 or newer on Linux (tongs-agents can download a pinned build for you) or tmux 3.2 or newer.

Install tongs-agents from PyPI as a tool:

pipx install tongs-agents        # or: uv tool install tongs-agents

pip install tongs-agents into a virtual environment works too. For the Agents screen in tongs, install the [tongs] extra into the environment tongs runs from (pip install "tongs-agents[tongs]", or pipx inject tongs tongs-agents when tongs came from pipx). The hooks and MCP registrations that tongs-agents install writes point at the environment you installed into, so run tongs-agents install again if you move or recreate it. Contributors install from a clone instead; see Contributing.

Describe the agents you use as profiles in ~/.config/tongs-agents/config.toml. A profile is a template (harness, config dir, model, environment); you pick the folder and any extra arguments each time you start one:

[profiles.claude-main]
command = ["claude"]

[profiles.claude-alt]
command = ["claude"]
config_dir = "~/.claude-alt"     # a second Claude Code config dir

[profiles.codex-review]
command = ["codex"]

[profiles.pi-local]
command = ["pi", "--provider", "ollama", "--model", "qwen3-coder"]

Then install the hooks, check the setup, start the workspace and add agents:

tongs-agents install             # hooks for Claude Code, Codex and every profile's config dir
tongs-agents doctor              # what is missing, and how to fix it
tongs-agents doctor --fix zellij # only if doctor says Zellij is missing (Linux x86_64)
tongs-agents                     # open the workspace: only the sidebar, no agents yet

The workspace starts empty. Add agents from a shell in it, or from any other terminal:

tongs-agents run claude-main ~/src/app                  # Claude Code in ~/src/app
tongs-agents run codex-review ~/src/api -- resume --last # extra arguments after --
tongs-agents run claude-alt -- --resume                 # in the current directory

In the sidebar, + (or Ctrl+P, then Add agent…) does the same with a profile picker, a folder field with path completion and an arguments field. The sidebar lists each pane with its status. Enter jumps to the selected agent, n jumps to the next one that needs you. In Codex, review and trust the new hooks once with /hooks. tongs-agents --version prints the installed version.

The first workspace tutorial walks through all of this step by step.

What you can do

Everything that acts on your agents is opt-in. MCP agent control needs [control] mcp_enabled = true plus mcp_control = true on each profile; chat needs a grant per pane; web watching starts only with web enable and binds 127.0.0.1 only.

Sandboxed profiles have instrumented evidence only: every OpenShell call has been checked against a fake CLI, and the live run on a real gateway is pending. The sandbox tutorial walks through setup, and sandboxed profiles is the reference.

Support

Evidence for each claim, and what is not validated yet, is in the support matrix. Some harness behaviours that chat and the sandbox rely on are read from harness documentation and binaries but not observed live; those pages say so where it matters.

Documentation

Start at the documentation index. It has tutorials, how-to guides, reference pages and background, grouped by what you want to do.

MCP tools

tongs-agents install registers the tongs-agents MCP server with Claude Code (claude mcp add --scope user) and Codex (a [mcp_servers.tongs-agents] table in its config.toml) when those CLIs are on PATH. These read-only tools are always available:

The agents_* control tools and the chat_* tools appear only when you turn them on; see MCP agent control and agent chat.

Upgrading from claude-fleet-monitor

Install tongs-agents, then run tongs-agents install (add --agent all if you used Pi). It removes the claude-fleet-monitor hooks, its fleet MCP entries and its Pi extension, and keeps everything else. Then run pip uninstall claude-fleet-monitor and tongs-agents doctor, which reports anything left over, including the old ~/.claude/fleet/ directory and the command to remove it. Old session records are not migrated. See the migration guide.

Uninstall

tongs-agents uninstall              # hooks, MCP entries and session records
tongs-agents uninstall --keep-data  # keep the sessions directory
tongs-agents uninstall --agent pi   # only the Pi extension
pipx uninstall tongs-agents         # or uv tool uninstall, or pip uninstall, matching how you installed it

Session records are kept while the Pi extension is still installed. The <name>.tongs-agents.bak copies that install kept of your settings.json and hooks.json stay; delete them yourself when you no longer need them.

Contributing

To work on tongs-agents, install it editable from a clone:

git clone https://github.com/andre-motta/tongs-agents.git
cd tongs-agents
python3 -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"          # add ,tongs for the tongs plugin tests

Hooks installed from this checkout point at its .venv. See CONTRIBUTING.md for development setup and the PR process. Harness contributors should follow the adapter author guide. Agent-led initiatives follow the SDLC profile.

License

MIT