PR #36411 - manaflow-ai/cmux

Leo-ask: ask-a933b133a7
Leo-Ask-Trace: ask-a933b133a7

Leo, 2026-11-05, looking at the Claude Code desktop app's task list, proposed-session cards, session links and wrap-up box: "presumably specifically in the claude code desktop there are a few skills/system prompts that let you guys know about them... cmux-next should add a few and we can think about extending them as well and letting other users define stuff too!"

Design and audit of what agents were told before: plans/cmux-next/agent-guidance-DESIGN.md.

What every agent cmux runs now gets

Five pieces of guidance, each tied to a tool cmux already has and saying when it applies:

Piece	Applies when	Tool
Plan list	a task with more than one step	Claude Code `TodoWrite`, Codex `update_plan` (drawn as the chat's checklist)
Side sessions	the person asked for parallel work; otherwise offer it	`start_session`, `offer_session`, `suggest_tasks`, `app_agent_open`
Session links	mentioning another session	a session name or agent link in inline code (drawn as a chip)
Closing recap	a turn that changed files or ran commands	the reply's last lines
Editing cmux live	asked to change how cmux looks or behaves	`cmux-live`, `cmux-customization` skills

Each harness gets it through its own mechanism:

Claude Code: a new skill cmux:cmux-chat in the session plugin (only its description is in the prompt), plus a short first-turn pointer so the plan and recap rules hold before the skill is read.
Codex and other harnesses: the compact guidance in the first-turn context, the same user-role channel Codex uses for AGENTS.md. Nothing is written to the person's CODEX_HOME or repo.

The guidance is its own context part (cmux-guidance), so a person's Context viewer override of the default rule keeps it. The Context viewer lists it with its tokens.

The person's layer

Skills in ~/.config/cmux/skills/<name>/SKILL.md (standard SKILL.md frontmatter). Claude Code gets them as a second session plugin, cmux-user:<name> (regular files only, no symlinks, size and count limits, written once per content hash). Other harnesses get an index (name, description, path) and read the file when it applies.
Switches, all on by default, user-only (agents may not set them): agents.guidance.claude, agents.guidance.codex, agents.guidance.otherAgents, agents.guidance.userSkills, in Settings > Agents > Guidance and Skills, the palette, cmux settings, and MCP settings_get. They apply to new chats.

Verification

Fleet Rust at 0ccb29e (run 42006331368): cargo fmt --check, cargo test -p acpmux --lib (agent_guidance, context_inventory, agent_tools, prompt_line_tests: 41 passed), --test tool_inventory, --test hub_integration prompt_context, cargo clippy -p acpmux --all-targets -D warnings: all pass.
Fleet Swift: AgentGuidanceSettingsTests pass. SettingsSchemaExportTests.exportIsFresh fails only because settings-schema.json is generated; base autofix regenerates it (never hand-edited).
Real Codex session (codex-cli 0.164.0, an acpmux built at this branch, its own daemon home, one user skill whose body holds a canary word): asked to quote any cmux guidance, state the end-of-turn rule and follow a matching skill, it answered "cmux chat guidance (cmux defaults; the person's own instructions win).", A two-or-three-sentence recap covering what is true, verified, unfinished, and any decision needed. and PELICAN-42: Tag the commit, then write the notes. The canary is only in the user skill, so the skill index reached Codex and it read the skill.
Real Claude Code session: started with cmux:cmux-chat and cmux-user:release-checklist attached (session tool rows), but no turn completed: the model gateway returned repeated 529 Overloaded on one host, and the Claude login on the other is at its weekly limit. Not yet shown in use.

Observed / Not run

Observed: the runs above. Not run: a tagged app build (the palette row, cmux settings get|set agents.guidance.codex, MCP settings_get), and a completed Claude Code turn.

Changelog

Added: agents in cmux chats keep a checklist plan, link other sessions and end with a recap; your own skills in ~/.config/cmux/skills reach every chat; Settings > Agents > Guidance and Skills.

acpmux owner (PL-acpmux) notice: plans/cmux-next/acpmux-audit.md. Sibling work this builds beside: the plan rendering ("Agent plans in cmux chats") and the Live Web Reload PR that adds the cmux-live skill.

Agent session: agent session

🤖 Generated with Claude Code

^{Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.}

Summary by cubic

Agents in cmux chats now know how cmux shows their work, and the person's own skills reach every chat.

Built-in guidance

A new cmux:cmux-chat skill tells Claude Code to keep a plan checklist, start sub-sessions only when asked (offer them otherwise), link sessions in inline code, and end changed turns with a recap. A short first-turn pointer says when to read it, and side-session tools are named only when cmux lists them, so the pointer stays around 95 tokens.
Codex and other harnesses get the same guidance as first-turn context via the channel Codex uses for AGENTS.md; nothing is written to the person's CODEX_HOME or repo.
The guidance is its own first-turn context part reviewed in the Context viewer, kept beside the folder-instructions part from the base branch in new sessions and fresh forks.

The person's layer

Skills in ~/.config/cmux/skills/<name>/SKILL.md reach every chat: a cmux-user plugin for Claude Code (regular files only, with SKILL.md files copied first under a 32 MiB overall budget and per-file limits so a stray huge folder is not copied on each session start; a symlinked SKILL.md is refused), and an index for other agents whose descriptions are cut at 300 characters.
New user-only switches agents.guidance.{claude,codex,otherAgents,userSkills} (on by default) in Settings > Agents > Guidance and Skills apply to chats created after the change; turning off the Claude switch also leaves cmux-chat out of the plugin.