Tutorial 1: Your First Project

The core loop: scaffold → talk to Claude → take notes → commit.

1. Create the project

ccmux new auth-redesign -d "rebuild the login flow with passkeys"

This single command:

  1. Creates ~/Projects/auth-redesign/ with docs/01_Specs/, docs/02_Architecture/, docs/03_Agent_Logs/
  2. Writes a starter README.md + .gitignore, runs git init, makes the first commit
  3. Opens a tmux session named c-auth-redesign, starts your AI agent inside it
  4. Types your description as the first prompt — the agent reads it, asks 2–3 clarifying questions, and writes docs/01_Specs/00_Initial_Concept.md from your answers

Everything stays local.

Pick a different agent. The CLI form defaults to Claude. To use Codex or Gemini, open the TUI (ccmux), press 3 for Projects, press n to open the new-project form, and use ←/→ on the agent row to pick. The choice is stored at <project>/.ccmux/agent and persists across sessions. Switch later with a on the project in the Projects list.

2. Watch and check in

To check on the session without joining the conversation:

ccmux list

To attach:

ccmux attach auth-redesign

Detach from the tmux session with Ctrl-b d — the session keeps running.

3. Push to GitHub when ready

cd ~/Projects/auth-redesign
gh repo create --private --source=. --remote=origin --push

4. Notes

Press 4 in the TUI to open the Notes tab for this project — you’ll see the docs/ tree rendered with Glamour markdown. Quick-actions: n for new Agent Log (today’s, auto-templated), s for new Spec, a for new ADR.

The session keeps running after you detach. On AC power, the daemon holds a caffeinate -s lock — close the lid and the agent keeps thinking.

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