Tutorial 4: Pick Your Agent

Each project remembers its agent. The dashboard, daemon, and session dispatch all follow that choice.

ccmux — pick agent

At project-creation time

When you press n on the Projects screen, the form has an Agent row. Use ← / → to cycle through the agents ccmux finds on this machine: Claude Code, Codex, Cursor, and more. If it finds none, the row offers all of them.

Antigravity CLI (antigravity, which runs agy) and Gemini CLI (gemini) are separate agents, each with its own settings and history. Antigravity is Google’s successor to Gemini CLI; Gemini CLI still works for Code Assist Standard/Enterprise and paid API users.

Press Enter to create the project with that agent.

CLI equivalent.

ccmux new my-service                 # the default agent (Claude unless you set one)
ccmux new my-service --agent codex

The agent is stored at <project>/.ccmux/agent — edit that file directly to change it.

Change an existing project’s agent

In the TUI, select the project on the Projects screen and press a to move it to the next installed agent.

The agent sidecar is a single-line text file:

echo "codex" > ~/Projects/my-service/.ccmux/agent

The value is an agent ID, the same one --agent takes: claude, codex, cursor and so on. ccmux new --help lists every ID. Antigravity’s is antigravity, not agy.

The next session you start from ccmux for that project uses the updated agent.

Set a machine-wide default

To change which agent the new-project form pre-selects on this machine:

# ~/.config/ccmux/config.toml
[agents]
default = "codex"

Edit inline from the TUI: press 6 (Settings), navigate to the default agent row, and press Enter to cycle through options.

Agents screen

Press 5 in the TUI to open the Agents screen, with a sub-tab for each agent whose config ccmux can show; tab moves between them. Claude’s covers the model, effort and ~/.claude/CLAUDE.md. Codex’s toggles effort and YOLO mode, and saving keeps your comments in ~/.codex/config.toml. Agents that manage their own config, like pi and Grok, just tell you where it lives. The rest have no tab: ccmux launches and watches them, and they read the shared AGENTS.md.

Spotted an error or something out of date? Open an issue on GitHub.