Tutorial 1: Your First Project

The core loop: create a project → agent session boots → attach → work → detach.

ccmux — new project

1. Create a project in the TUI

Open ccmux:

ccmux

Press 2 to go to the Projects screen, then n to open the new-project form.

Fill in:

• Name — the project directory name (e.g. api-service)
• Host — which machine to run it on (defaults to local)
• Agent — Claude, Codex, Antigravity, Cursor, pi, or Grok; use ←/→ to cycle

Press Enter to create the directory and boot the session. ccmux switches back to the Home screen where the new session appears immediately.

CLI shortcut. If you prefer the command line:

ccmux new api-service

Same result — directory created under projects.root, tmux session started with the default agent (or the one stored in <project>/.ccmux/agent).

2. Attach to the session

On the Home screen, navigate to the session with j / k and press Enter to attach.

You’re now inside the tmux session running your agent. When you’re done:

• Ctrl-b d — detach; ccmux TUI resumes automatically
• The session keeps running in the background

3. Check status without attaching

You can read the session’s state from the dashboard without interrupting the agent. The needs_input indicator (red) is the one to watch — it means the agent is waiting for your response.

To list sessions from the shell:

ccmux list

4. Project notes

Press 4 in the TUI to open the Notes tab for this project. Every .md file in the project tree appears in a folder-grouped list; selecting one renders it with Glamour.

Press / to search across all notes with ripgrep.

Detaching leaves the session running in tmux while the host stays awake. The default macOS sleep protection works on AC power and does not override lid-close sleep. Review the sleep settings before leaving a laptop unattended.

Spotted an error or something out of date? Edit this page on GitHub.