# Prismattyc

> Prismattyc is a standalone terminal emulator and multiplexer for people and agents. `prismattyc-host` is the desktop app (tabs, split panes, named workspaces called Spaces). `pmux` manages sessions from a terminal or script, and `pmuxd` keeps sessions running when you detach. `pmux mail` and the `pmux-mcp` stdio MCP server let local agent sessions message each other and inspect Spaces.

This file is for agents. Full docs: https://prismattyc.com/llms-full.txt. Tool list: https://prismattyc.com/agents.json. Source: https://github.com/moonbase2090/Prismattyc (MIT).

## Prerequisites

- Linux x86_64 or ARM64 with glibc 2.28 or newer (Wayland or X11). On Ubuntu: `sudo apt install libfontconfig1 libxkbcommon0 libxkbcommon-x11-0 libegl1`.
- macOS, Apple silicon or Intel (universal, signed and notarized).
- Windows x86_64 (signed MSI or portable zip).
- From source: Rust 1.90 or newer.

## Install

Releases: https://github.com/moonbase2090/Prismattyc/releases (checksums in `SHA256SUMS`, `SHA256SUMS-macos`, `SHA256SUMS-windows`).

### macOS

Download `Prismattyc-vX.Y.Z-macos-universal.dmg`, open it, and move `Prismattyc.app` to `/Applications` or `~/Applications`. The app links its bundled `pmux` into `/usr/local/bin` when it can, otherwise `~/.local/bin`.

### Linux

```sh
mkdir prismattyc-release
tar -xzf prismattyc-x86_64-unknown-linux-gnu.tar.gz --strip-components=1 -C prismattyc-release   # or the aarch64 archive
./prismattyc-release/install.sh
~/.local/bin/prismattyc-host
```

Add `~/.local/bin` to PATH. The installer adds the pmux agent skill for detected agents; skip with `--no-agent-skills` or `PRISMATTYC_NO_AGENT_SKILLS=1`.

### Windows

Run `prismattyc-vX.Y.Z-x86_64-pc-windows-msvc.msi`. It prepends `%LOCALAPPDATA%\Programs\Prismattyc\cmd` to the user PATH, registers `pmuxd` at logon and starts it. Pass `ADDTOPATH=0` to leave PATH unchanged. Portable: extract `prismattyc-vX.Y.Z-x86_64-pc-windows-msvc.zip` and run `bin\prismattyc-host.exe`.

### Build from source

```sh
git clone https://github.com/moonbase2090/Prismattyc.git && cd Prismattyc
cargo build --workspace --release --locked
./target/release/prismattyc-host
```

Binaries in `target/release/`: `prismattyc-host`, `pmux`, `pmuxd`, `pmux-attach`, `pmux-mcp`, `prismattyc`.

### Update and uninstall

`pmux update --check`, `pmux update`, `pmux update --rollback`. `pmux uninstall --dry-run`, `pmux uninstall [--keep-data]`.

## Configuration

- Desktop config: `~/.config/prismattyc/config.toml` (override with `PRISMATTYC_CONFIG`). Most settings apply live, e.g. `font_px = 16.0`, `chrome_style = "classic"`, `automatic_update_checks = false`, `install_agent_skills = false`.
- `pmux config init [--merge]` writes `[mux]` keys into config.toml.
- Socket: `--instance NAME` selects `$XDG_RUNTIME_DIR/prismattyc/pmux-<NAME>.sock` (default `pmux.sock`); `--socket PATH` overrides.
- Mail identity: `--as <agent>`, else `$PMUX_AGENT`, else the agent bound to the current pane's session.
- MCP: `pmux-mcp` needs an identity (`--as <agent>` or `PMUX_AGENT`; no default). Use `--supervise` for hosts that do not respawn failed stdio servers. Example: `{"mcpServers": {"pmux": {"command": "pmux-mcp", "args": ["--supervise"], "env": {"PMUX_AGENT": "my-agent"}}}}`
- Agent skill: `pmux skills install --agent detected [--check] [--force]`.

## Tools

### MCP tools (`pmux-mcp`)

Each tool call reconnects to the pmux mail socket for one operation. Watching for mail is not a tool; use `pmux mail watch` from a shell.

- `pmux_alias` — Bind a shorthand alias to this process's agent. Params: `name` (required).
- `pmux_broadcast` — Send one letter to every bound agent except this agent. Single transaction. Params: `body`, `summary` (required).
- `pmux_claim` — Claim this agent's uncommitted letters. Open letters become held; already-held letters are re-listed. Commit or release next. Params: none. Example: `{}`
- `pmux_commit` — Commit held letters by id. They are gone for good. Params: `ids` (required). Example: `{"ids": ["<id from pmux_claim>"]}`
- `pmux_inbox` — Peek at mailbox depth without claiming. Returns open and held counts. Params: none.
- `pmux_release` — Return held letters to open by id, making them claimable again. Params: `ids` (required).
- `pmux_send` — Deliver a letter. to is an agent id (operator-id) or alias. Omitting body sends an empty body. Params: `body`, `summary` (required), `to` (required). Example: `{"to": "reviewer", "summary": "PR ready", "body": "Please review."}`
- `pmux_space_attention` — Resolve or snooze an exact attention request returned by Space details. Rechecks ownership and request revision. Leaves mail delivery unchanged. Params: `action` (required), `name` (required), `pane` (required), `revision` (required), `session` (required).
- `pmux_space_details` — Inspect a Space: session names, roles, live state, explicit attention requests, separate letter counts, and context links. Does not launch work or claim mail. Params: `name` (required). Example: `{"name": "my-space"}`
- `pmux_space_link` — Add a labeled context link to a Space. The target must be an HTTP(S) URL or absolute local path. Does not open it or modify external task state. Params: `label` (required), `name` (required), `target` (required).
- `pmux_space_result` — Read retained Space open results. These are historical operation results; use pmux_space_details for current liveness. Params: `name` (required).
- `pmux_space_role` — Set the displayed role of a session in its owning Space. Params: `name` (required), `role` (required), `session` (required).
- `pmux_template_create` — Create an independent Space from a previewed template. Requires explicit user intent. launch=false creates shells only; launch=true executes the previewed commands. Retry never blindly repeats a launch. Does not open a desktop view. Params: `launch`, `space` (required), `template` (required).
- `pmux_template_list` — List saved team templates without launching work. Params: none.
- `pmux_template_preview` — Preview the sessions, directories, programs, commands, and conflicts for a new team. Has no process or saved-Space side effects. Params: `space` (required), `template` (required). Example: `{"template": "my-team", "space": "my-space"}`
- `pmux_template_save` — Save a reusable team template from a Space definition. Does not create or stop sessions and does not execute commands. Params: `space` (required), `template` (required).
- `pmux_tutorial` — Get the pmux collaboration tutorial: identity, live presence, stored mail, intentional pane writes, authorized shell commands, and Space cleanup. Params: none. Example: `{}`
- `pmux_who` — List live agent-bound sessions (presence), including this process. Params: none. Example: `{}`

### CLI (`pmux [--instance NAME | --socket PATH] [--session NAME] <command>`)

Sessions:
- `pmux up [-- PROGRAM ARGS...]` — start the server (default `$SHELL -l`).
- `pmux new [--attach|--no-attach] [--headless] [--agent NAME|--no-agent] NAME [-- PROGRAM...]` — create a named session; `--agent` binds a mailbox (default: the session name). Example: `pmux new work --no-attach`
- `pmux attach [SESSION] [--watch] [--write TEXT] [--pane ID] [--json|--styled-json] [--read-only] [--fit]` — attach (interactive on a TTY, else a JSON dump). Detach with Ctrl+\ then d.
- `pmux ls` — sessions, windows and panes. `pmux whoami [--json]` — this pane's session, id, pane and agent.
- `pmux session name NAME [--session KEY]`, `pmux session clear [--all] [--keep NAME]`.
- `pmux status`, `pmux doctor [SESSION]`, `pmux render-status [--json]`, `pmux versions`, `pmux clients [SESSION] [--json]`.
- `pmux stop [SESSION]`, `pmux kick SESSION`, `pmux detach --other [SESSION]`, `pmux restart [--host|--daemon|--mcp|--all] [--plan]`.
- `pmux login <enable|disable|status|sync>` — start at login and restore the workspace.

Panes:
- `pmux send PANE TEXT [--enter] [--literal] [--force]` — write keys; refuses a busy pane unless `--force`.
- `pmux pane-write PANE --text TEXT [--submit auto|enter|none] [--json]` — intentional text to exactly one pane.
- `pmux save-buffer PANE|SESSION FILE [--history]` (`-` = stdout), `pmux pipe-pane PANE|SESSION (FILE | --exec CMD)`.
- `pmux rename-pane PANE|SESSION [TITLE]`, `pmux break-pane PANE`, `pmux join-pane PANE --to TAB [-h|-v]`.
- `pmux arrange SESSION main-vertical|main-horizontal|even-h|even-v|grid`, `pmux sync on|off|status [SESSION]`.
- `pmux status-set TEXT [--pane ID]` | `--clear`, `pmux attention SESSION [MESSAGE]`.

Tabs and Spaces:
- `pmux attach --all` — open the desktop host with sessions as panes in tabs.
- `pmux space open [NAME] [--add|--new-window]`, `pmux space <create|save|attach|ls|rm|clear|add|remove|move|rename> ...`.
- `pmux layout <save|apply|ls|rm>`.

Mail (`pmux mail [--as <agent>] <verb>`):
- `send <to> --summary S [--body B]` (body from stdin if omitted), `claim [--json|--ids]`, `commit <id>...`, `release <id>...`, `inbox`, `watch [--timeout SECS]` (default 300; exit 1 on timeout), `alias <name>`, `who`, `broadcast --summary S [--body B]`, `status`.

Other: `pmux tutorial [--play]`, `pmux skills install ...`, `pmux config init [--merge]`, `pmux update [--check|--rollback|--pre]`, `pmux uninstall [--dry-run] [--keep-data]`, `pmux completions <bash|zsh|fish>`, `pmux --version`. Manual: `man pmux`.

## Usage workflows

1. Start and use a session: `pmux up`, `pmux new work --no-attach`, `pmux attach work`, `pmux ls`.
2. Agent onboarding: `pmux tutorial` (or MCP `pmux_tutorial`), then `pmux whoami --json`.
3. Message another agent: `pmux mail send <agent> --summary "..." --body "..."`; the recipient runs `pmux mail claim --json`, then `pmux mail commit <id>` (or `release`). Watcher loop: `while pmux mail watch; do pmux mail claim --json; done`.
4. Inspect a Space from MCP: `pmux_space_details`, then `pmux_space_attention` to resolve or snooze a request.
5. Start a team from a template: `pmux_template_list`, `pmux_template_preview`, then `pmux_template_create` only with explicit user intent (`launch=false` creates shells only).
6. Script a pane: `pmux pane-write PANE --text "make test" --submit enter`, then `pmux save-buffer PANE -`.

## Troubleshooting

- `pmux-mcp: no identity`: pass `--as <agent>` or set `PMUX_AGENT`.
- `pmux` not found or the wrong one runs: put `~/.local/bin` (or `/usr/local/bin` on macOS) first on PATH.
- `send` refused: the pane is busy; use `pmux pane-write` or `--force` deliberately.
- `pmux mail watch` exits 1: it timed out with no mail, which is not a mux failure.
- Session problems: `pmux doctor [SESSION]`, `pmux status`, `pmux versions`.
- Linux host fails to open windows: `pmux attach --all` needs `WAYLAND_DISPLAY` or `DISPLAY`.
- SmartScreen warning on Windows: choose More info, then Run anyway.

## Links

- [Full agent docs](https://prismattyc.com/llms-full.txt)
- [agents.json](https://prismattyc.com/agents.json)
- [Source](https://github.com/moonbase2090/Prismattyc)
- [Releases](https://github.com/moonbase2090/Prismattyc/releases)
- [pmux command reference](https://github.com/moonbase2090/Prismattyc/blob/main/docs/mux-cli.md)
- [Configuration](https://github.com/moonbase2090/Prismattyc/blob/main/docs/config.md)
- [Update and uninstall](https://prismattyc.com/docs/update-and-uninstall.html)