Agent harness setup

Run your preferred agent CLI in a named pmux session. Install the pmux skill so the agent can find the session, mail, and intentional-input commands.

Install the pmux agent skill

Install Prismattyc and your chosen agent CLI first. Preview the destinations for detected agents, then install:

pmux skills install --agent detected --check
pmux skills install --agent detected

Supported destinations include Codex, Claude, Cursor, Muse, and Kiro. --agent detected selects agents whose CLI or configuration directory is present. The default selection without --agent is all. Existing files stay in place unless you explicitly use --force.

The macOS app also installs the skill for detected agents once per app version. Set install_agent_skills = false in the host configuration, or PRISMATTYC_NO_AGENT_SKILLS=1, to opt out.

Give the agent a named session

pmux new editor --no-attach
pmux attach editor

Start your agent CLI in that attached shell. Run pmux whoami in the pane to inspect its live identity; the bound agent name is the mailbox address. Use a descriptive session name rather than saving a numeric pane ID for later.

The agent can read pmux mail inbox, claim with pmux mail claim --json, and acknowledge handled letters with pmux mail commit LETTER_ID. Sending a letter does not wake an idle agent. The agent or its launcher must check for mail.

Optional MCP integration

pmux-mcp is a stdio MCP server for mail and Space tools. It needs an explicit identity through --as or PMUX_AGENT. For clients that accept an mcpServers configuration, use this shape and adapt it to the client's format:

{
  "mcpServers": {
    "pmux": {
      "command": "pmux-mcp",
      "args": ["--as", "editor", "--supervise"]
    }
  }
}

Ensure the client can find pmux-mcp on PATH. --supervise is useful for clients that do not respawn failed stdio servers. MCP connects to the existing session server; you do not need a separate daemon for each agent or desktop window.

Separate messages from actions

• Use mail for requests, replies, and handoffs.
• Use pane-write only when you intend to deliver input to a particular pane.
• Read live IDs with pmux ls before targeting a pane.
• Use the agent's normal tool permissions and approval rules for commands that affect files or external systems.

The CLI mail reference covers claim, commit, release, and identity selection.