{
  "markdown": "**[日本語](README.ja.md)** | English\n\n![using-cmux](banner.jpeg)\n\n# using-cmux\n\nA Claude Code skill package for AI-driven cmux terminal operations.\n\n## Motivation\n\nClaude Code's built-in `Agent` tool is convenient, but what happens inside is opaque. It's difficult to inspect sub-agent output or intervene mid-task, making debugging and quality control challenging.\n\n**With cmux, everything is visible.** By launching sub-agents on cmux — a terminal multiplexer — you can monitor each agent's I/O in real time and intervene at any point.\n\nThe existing [hashangit/cmux-skill](https://github.com/hashangit/cmux-skill) dedicates roughly 50% of its content to browser automation, burying the most critical use case: sub-agent operations. This package restructures that content, **putting sub-agent operation patterns front and center**.\n\n## What's Included\n\n| Category | Description |\n|----------|-------------|\n| **Basic operations** | Pane splitting, workspace management, command sending, screen reading |\n| **Newline rules for `send`** | The most important rule — when to use `\\n` vs. `send-key return` |\n| **Sub-agent launch pattern** | Full lifecycle: launch → trust detection → prompt → completion detection → result collection |\n| **`read-screen` troubleshooting** | Fixes for empty/stale output, `refresh-surfaces`, etc. |\n| **Notifications** | `cmux notify` (in-app) vs. `osascript` (macOS Notification Center) |\n| **Status & progress** | Sidebar status and progress bar control |\n\n## Relationship with cmux-team\n\n![Architecture](architecture.jpeg)\n\n- **using-cmux**: General-purpose cmux CLI operations. Covers the full lifecycle of a single sub-agent\n- **cmux-team**: Multi-agent orchestration. Handles team composition, task distribution, and synchronization. Built on top of using-cmux\n\n## Prerequisites\n\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed\n- [cmux](https://cmux.dev) installed, with Claude Code running inside a cmux session\n- macOS or Linux. Windows is not supported (the `bin/` wrappers are POSIX shell scripts and rely on `jq`, `cmux` CLI behavior tested only on macOS/Linux).\n\n## Installation\n\n### Option 1: Plugin (recommended)\n\n```\n/plugin marketplace add hummer98/using-cmux\n/plugin install using-cmux\n```\n\nSkills, commands, and hooks are installed together.\n\n**To update:**\n\n```\n/plugin update using-cmux\n/reload-plugins\n```\n\n> Note: To pick up changes in the `bin/` wrapper scripts (`cmux-read` etc.), you must restart the cmux session. The plugin's `bin/` path is baked into PATH at session start.\n\n### Option 2: Agent Skills (skills only)\n\n```bash\nnpx skills add hummer98/using-cmux\n```\n\n> Note: Commands (`/cmux`) and wrapper scripts (`cmux-read` etc.) are not included in Agent Skills distribution. Use Option 1 for full functionality.\n\n## Usage\n\n### Auto-trigger\n\nWhen Claude Code starts inside a cmux session, it detects the `CMUX_SOCKET_PATH` environment variable and automatically loads the skill. No manual setup required.\n\nWhen Claude Code receives cmux-related instructions, it follows the patterns in SKILL.md to perform pane splitting, command sending, sub-agent launching, and more.\n\n### `/cmux` Command\n\nDisplay the quick reference:\n\n```\n/cmux\n```\n\nUseful for quickly checking available commands and basic usage.\n\n## Security\n\nThe `bin/` wrapper scripts (`cmux-send`, `cmux-send-key`, `cmux-read`) are thin wrappers around the `cmux` CLI. They:\n\n- Take a `--surface` reference, look up the matching workspace via `cmux tree --json`, and forward the call to `cmux send` / `cmux read` / `cmux send-key`\n- Do **not** evaluate, interpolate, or modify the user-supplied payload — strings are passed verbatim to `cmux`\n- Run with the user's own permissions; they do not elevate privileges or write outside `cmux`\n- Have no network access of their own\n\nBecause these wrappers send keystrokes to a chosen cmux surface, an agent that can call `cmux-send` can in principle execute arbitrary commands inside the target surface (this is by design — that is what cmux is for). Treat installation of this plugin as granting the agent the same capability as a user typing into your terminal panes.\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 4181,
  "sha": "c26c4b3a92702a3b7fd9990d60a4eb8e4439369372ea2d578e9af8d79e7b6dc1",
  "repo_slug": "hummer98/using-cmux",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_hummer98_using_cmux_using_cmux_ae56a411/readme"
}