muxac

Multiplexer for Agentic Coding tools

Overview

muxac provides four primitive features to manage sessions of Agentic Coding tools:

• muxac new: Creating a new session
• muxac list: Listing all sessions with their status
• muxac attach: Attaching to an existing session
• muxac remove: Removing an existing session

Using these primitives, you can also build your own tools like a dashboard or UI on top of muxac.

For example, the creator of muxac uses it with fzf and Neovim to switch between sessions of Claude Code while previewing them as shown below:

Usage

# Create a new Agentic Coding session for the current directory with an Agentic Coding tool command like `claude`.
# (You can use arbitrary arguments or options for the command as usual.)
$ muxac new claude

# You can detach from the session by pressing `Ctrl+b d`.

# List all sessions with their status.
$ muxac list

DIRECTORY               NAME     STATUS
/path/to/workspace-1    default  running
/path/to/workspace-2    foo      waiting
/path/to/workspace-3    bar      idle

# Attach to an existing session for the current directory.
$ muxac attach

Status	Description
running	The agent is actively processing
waiting	The agent is waiting for a user response
idle	The agent is idle

Installation

Download the binary from the release page.

Prerequisites

• tmux

Setup

Claude Code

Add the following hook configuration to your Claude Code settings file (e.g. ~/.claude/settings.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "muxac hook"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "muxac hook"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "muxac hook"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "muxac hook"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "muxac hook"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "muxac hook"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "muxac hook"
          }
        ]
      }
    ]
  }
}

Codex

Add the following hook configuration to your Codex settings file (e.g. ~/.codex/config.toml):

[[hooks.SessionStart]]
[[hooks.SessionStart.hooks]]
type = "command"
command = "muxac hook"

[[hooks.UserPromptSubmit]]
[[hooks.UserPromptSubmit.hooks]]
type = "command"
command = "muxac hook"

[[hooks.PreToolUse]]
[[hooks.PreToolUse.hooks]]
type = "command"
command = "muxac hook"

[[hooks.PostToolUse]]
[[hooks.PostToolUse.hooks]]
type = "command"
command = "muxac hook"

[[hooks.PermissionRequest]]
[[hooks.PermissionRequest.hooks]]
type = "command"
command = "muxac hook"

[[hooks.Stop]]
[[hooks.Stop.hooks]]
type = "command"
command = "muxac hook"

Note: Codex requires you to trust each command hook before it will run. Open Codex once and run the /hooks slash command to review and trust the new muxac hook entries. Until trusted, the hooks are skipped and status monitoring will not work.

Gemini CLI

Add the following hook configuration to your Gemini CLI settings file (e.g. ~/.gemini/settings.json):

{
  "hooks": {
    "BeforeAgent": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "muxac hook"
          }
        ]
      }
    ],
    "BeforeTool": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "muxac hook"
          }
        ]
      }
    ],
    "AfterAgent": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "muxac hook"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "muxac hook"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "muxac hook"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "muxac hook"
          }
        ]
      }
    ]
  }
}

GitHub Copilot CLI (Not yet supported, coming soon...)

OpenCode (Not yet supported, coming soon...)

Command Reference

muxac new

Creates a new session and launches the specified agentic coding tool.

$ muxac new [--name <name>] [--dir <path>] [--env KEY=VALUE ...] [--tmux-conf <path>] <command>

Flag	Description
--name <name>	Session name (default: default)
--dir <path>	Working directory (default: current directory)
--env KEY=VALUE	Environment variables to pass to the session (can be specified multiple times)
--tmux-conf <path>	Path to a tmux config file to source after session creation

muxac list

Lists all muxac sessions with their status.

$ muxac list [--no-header] [--json]

Flag	Description
--no-header	Omit the header row
--json	Output in JSON format

$ muxac list
DIRECTORY          NAME     STATUS
/home/user/myapp   default  running
/home/user/api     backend  waiting

muxac attach

Attaches to an existing session.

$ muxac attach [--name <name>] [--dir <path>]

Flag	Description
--name <name>	Session name (default: default)
--dir <path>	Working directory (default: current directory)

muxac remove

Removes an existing session.

$ muxac remove [--name <name>] [--dir <path>]

Flag	Description
--name <name>	Session name (default: default)
--dir <path>	Working directory (default: current directory)