Feature: headless mode (fire-and-forget prompt execution)

[craigsc]

Feature request

Allow cmux to run a prompt headlessly — create a worktree, start Claude Code with a prompt, and let it run to completion without an interactive session.

Example usage:

cmux new add-architecture-diagram -p "Add an architecture diagram and commit it"

This would create the worktree, run Claude Code non-interactively with the given prompt, and the agent would commit its work and exit — no interactive tmux session to attach to.

Source: Reddit comment on r/ClaudeCode

---

Maintainer notes

Interesting idea, but I'm not planning to implement this in the near term. A few reasons:

• We're most of the way there already — cmux new <branch> -p "prompt" and cmux start <branch> -p "prompt" already support passing an initial prompt that gets fed to Claude Code on session start. The only difference is that the session stays interactive in tmux rather than running headlessly.
• Scope creep — cmux is a worktree lifecycle manager, not a Claude Code orchestrator. True headless execution adds concerns (error handling, timeouts, output capture, completion notifications) that feel like a different tool's job.
• Supervision matters — fire-and-forget agent execution without review is risky for real codebases. The current model (prompt gets sent, but you can attach and watch/intervene) feels like a better default.

That said, I could be wrong! If you have a use case where the current -p flag doesn't cut it, or thoughts on what a headless mode should look like, I'd love to hear them.

Status: not planned — open for discussion