Agent Manager TUI

workflow deprecated no always-loaded rules -- loads on demand updated 2026-08-04

[DEPRECATED] Go-based terminal UI for managing Claude Code agent processes via tmux panes. Unmaintained and no longer offered for new installs; a GUI-based replacement is being pursued instead. Kept in-repo for existing users.

README

Agent Manager TUI

Status: DEPRECATED (unmaintained)

This module is deprecated and no longer offered for new installs — it does not appear in the installer's module list and is not bundled in any preset. It remains in the repository for existing users who already have it installed. Development is paused in favor of a GUI-based replacement. The instructions below are retained for reference; no further updates are planned.

A terminal UI for managing Claude Code agent processes across multi-clone repos. Built with Go and Bubble Tea.

What It Does

The agent manager gives you a live view of all running Claude Code agents: their status, resource usage, log output, and session info. From a single pane you can launch new agents, stop or restart hanging ones, tail their logs, and export session data.

┌─ Agents ─────────────────────────────────────────┐ ┌─ Detail ──────────────────────┐
│ ● habitpro-ai-w0-c0   running  03:42  issue #204 │ │ Agent: habitpro-ai-w0-c0      │
│ ● habitpro-ai-w0-c1   running  01:15  issue #206 │ │ PID:   91234                  │
│ ○ habitpro-ai-w0-c2   stopped  --:--             │ │ Dir:   ~/code/habitpro-ai-... │
│ ⚠ habitpro-ai-w0-c3   hanging  08:01  issue #201 │ │ Issue: #204                   │
└──────────────────────────────────────────────────┘ └───────────────────────────────┘
┌─ Logs: habitpro-ai-w0-c0 ─────────────────────────────────────────────────────────┐
│ [14:32:01] Reading CLAUDE.md...                                                    │
│ [14:32:03] Checking open PRs...                                                    │
│ [14:32:05] Creating branch 204-habit-streaks from origin/main                      │
└────────────────────────────────────────────────────────────────────────────────────┘

Installation

This module is deprecated and is not offered in the installer's module list, so there is no installer-driven setup path. The CCGM installer also has no post-install hook mechanism — the postInstall.sh script in this directory is never run automatically. Install the binary manually using either the script or the steps below.

Binary install via script

Run the bundled script directly. It downloads the correct platform binary, verifies its checksum, and installs it to ~/.ccgm/bin/:

bash modules/agent-manager/postInstall.sh

Manual Installation

Download the binary from GitHub Releases:

# macOS Apple Silicon
curl -fsSL https://github.com/lucasmccomb/ccgm/releases/latest/download/ccgm-agents_darwin_arm64.tar.gz | tar -xz
# macOS Intel
curl -fsSL https://github.com/lucasmccomb/ccgm/releases/latest/download/ccgm-agents_darwin_amd64.tar.gz | tar -xz
# Linux amd64
curl -fsSL https://github.com/lucasmccomb/ccgm/releases/latest/download/ccgm-agents_linux_amd64.tar.gz | tar -xz

Move the binary to ~/.ccgm/bin/:

mkdir -p ~/.ccgm/bin
mv ccgm-agents ~/.ccgm/bin/
chmod +x ~/.ccgm/bin/ccgm-agents

Add ~/.ccgm/bin to your PATH (if not already present):

echo 'export PATH="${HOME}/.ccgm/bin:${PATH}"' >> ~/.zshrc
source ~/.zshrc

Copy the slash command to your Claude commands directory:

mkdir -p ~/.claude/commands
cp modules/agent-manager/commands/agents.md ~/.claude/commands/agents.md

Usage

Launch the TUI:

ccgm-agents

Or from within a Claude Code session:

/agents

Keybindings

Key	Action
`j` / `↓`	Move down
`k` / `↑`	Move up
`enter`	Select / open detail panel
`/`	Filter agents by name or status
`esc`	Back / close detail panel
`n`	Launch new agent in current repo
`s`	Stop agent (graceful SIGTERM)
`r`	Restart agent
`x`	Kill agent (force SIGKILL)
`tab`	Switch between panels
`e`	Export agent logs to file
`pgup` / `pgdn`	Scroll log viewer
`?`	Toggle help overlay
`q` / `ctrl+c`	Quit

Configuration

The agent manager reads ~/.ccgm/agent-manager/config.json. If the file does not exist, defaults are used and the file is created on first run.

{
  "data_dir": "~/.ccgm/agent-manager",
  "health_check_interval": "2s",
  "hanging_timeout": "60s",
  "log_max_size": 52428800,
  "log_retention_days": 7
}

Field	Default	Description
`data_dir`	`~/.ccgm/agent-manager`	Directory for agent state and logs
`health_check_interval`	`2s`	How often to poll agent status
`hanging_timeout`	`60s`	Time before an agent is marked as hanging
`log_max_size`	`52428800` (50 MB)	Maximum log file size before rotation
`log_retention_days`	`7`	Days to retain rotated logs

Agent Lifecycle

The agent manager tracks these states:

running - Agent process is active and responding
stopped - Agent exited cleanly (zero exit code)
hanging - Agent has not produced output for longer than hanging_timeout
failed - Agent exited with a non-zero exit code

From the TUI, use s to stop, r to restart, or x to force-kill any agent.

Session Management

Agent sessions are persisted to ~/.ccgm/agent-manager/sessions/. Each session records:

Start and end time
Working directory and clone identity
Issue number (if claimed)
Exit code and final status
Log file path

Use e to export the current agent's log to a timestamped file.

Building from Source

Requirements: Go 1.21+

cd modules/agent-manager/src
go build -o ccgm-agents ./cmd/ccgm-agents
# Or use make:
make build
# Cross-compile for all platforms:
make build-all
# Install to ~/.ccgm/bin/:
make install

Dependencies

This module requires the multi-agent module (for multi-clone directory conventions). It is listed as a dependency and the installer enforces this.

Platform Support

Platform	Supported
macOS (Apple Silicon)	Yes
macOS (Intel)	Yes
Linux amd64	Yes
Linux arm64	No
Windows	No

Will install

Path	Action	Target	Type
`commands/agents.md`	→	`commands/agents.md`	command

Dependencies

multi-agent

Required by

No other module depends on this one.

Included in presets

Not included in any preset.

Manual step after install

This module requires a manual follow-up step after installing: run postInstall.sh.

#!/usr/bin/env bash
# postInstall.sh - Download and install the ccgm-agents binary.
#
# NOTE: The CCGM installer has no post-install hook mechanism; the `postInstall`
# key in module.json is advisory metadata and is NOT executed automatically.
# Run this script manually to install the binary.
#
# Downloads the correct platform binary from GitHub Releases, verifies the
# SHA-256 checksum, and installs it to ~/.ccgm/bin/ccgm-agents.
set -euo pipefail

INSTALL_DIR="${HOME}/.ccgm/bin"
BINARY_NAME="ccgm-agents"
REPO="lucasmccomb/ccgm"
RELEASES_URL="https://github.com/${REPO}/releases/latest/download"

# ---- Detect platform --------------------------------------------------------

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)

case "${ARCH}" in
  x86_64)          ARCH="amd64" ;;
  aarch64|arm64)   ARCH="arm64" ;;
  *)
    echo "ERROR: Unsupported architecture: ${ARCH}" >&2
    exit 1
    ;;
esac

case "${OS}" in
  darwin|linux) ;;
  *)
    echo "ERROR: Unsupported OS: ${OS}" >&2
    exit 1
    ;;
esac

if [[ "${OS}" == "linux" && "${ARCH}" == "arm64" ]]; then
  echo "ERROR: Linux arm64 is not supported. Supported platforms: darwin-arm64, darwin-amd64, linux-amd64" >&2
  exit 1
fi

# Goreleaser archive naming: ccgm-agents_VERSION_OS_ARCH.tar.gz
# The archive contains the binary at the top level.
ARCHIVE_NAME="${BINARY_NAME}_${OS}_${ARCH}.tar.gz"
CHECKSUMS_NAME="checksums.txt"

# ---- Skip if already installed ----------------------------------------------

if [[ -x "${INSTALL_DIR}/${BINARY_NAME}" ]]; then
  echo "ccgm-agents is already installed at ${INSTALL_DIR}/${BINARY_NAME}"
  echo "To upgrade, remove the existing binary and re-run this script."
  exit 0
fi

# ---- Require download tool --------------------------------------------------

if command -v curl &>/dev/null; then
  DOWNLOAD="curl -fsSL --retry 3 --retry-delay 2"
elif command -v wget &>/dev/null; then
  DOWNLOAD="wget -qO-"
else
  echo "ERROR: Neither curl nor wget found. Install one and re-run." >&2
  exit 1
fi

# ---- Create install directory -----------------------------------------------

mkdir -p "${INSTALL_DIR}"

# ---- Download to temp directory ---------------------------------------------

TMP_DIR=$(mktemp -d)
trap 'rm -rf "${TMP_DIR}"' EXIT

ARCHIVE_PATH="${TMP_DIR}/${ARCHIVE_NAME}"
CHECKSUMS_PATH="${TMP_DIR}/${CHECKSUMS_NAME}"

echo "Downloading ccgm-agents for ${OS}/${ARCH}..."

if ! ${DOWNLOAD} "${RELEASES_URL}/${ARCHIVE_NAME}" -o "${ARCHIVE_PATH}" 2>/dev/null; then
  echo "ERROR: Failed to download ${RELEASES_URL}/${ARCHIVE_NAME}" >&2
  echo "Check your network connection or visit https://github.com/${REPO}/releases to download manually." >&2
  exit 1
fi

if ! ${DOWNLOAD} "${RELEASES_URL}/${CHECKSUMS_NAME}" -o "${CHECKSUMS_PATH}" 2>/dev/null; then
  echo "ERROR: Failed to download checksums from ${RELEASES_URL}/${CHECKSUMS_NAME}" >&2
  exit 1
fi

# ---- Verify SHA-256 checksum ------------------------------------------------

echo "Verifying checksum..."

EXPECTED_CHECKSUM=$(grep "${ARCHIVE_NAME}" "${CHECKSUMS_PATH}" | awk '{print $1}')
if [[ -z "${EXPECTED_CHECKSUM}" ]]; then
  echo "ERROR: Could not find checksum for ${ARCHIVE_NAME} in checksums.txt" >&2
  exit 1
fi

if command -v sha256sum &>/dev/null; then
  ACTUAL_CHECKSUM=$(sha256sum "${ARCHIVE_PATH}" | awk '{print $1}')
elif command -v shasum &>/dev/null; then
  ACTUAL_CHECKSUM=$(shasum -a 256 "${ARCHIVE_PATH}" | awk '{print $1}')
else
  echo "ERROR: Neither sha256sum nor shasum found. Cannot verify checksum." >&2
  exit 1
fi

if [[ "${EXPECTED_CHECKSUM}" != "${ACTUAL_CHECKSUM}" ]]; then
  echo "ERROR: Checksum mismatch!" >&2
  echo "  Expected: ${EXPECTED_CHECKSUM}" >&2
  echo "  Actual:   ${ACTUAL_CHECKSUM}" >&2
  echo "The downloaded file may be corrupted or tampered with." >&2
  exit 1
fi

echo "Checksum verified."

# ---- Extract and install ----------------------------------------------------

tar -xzf "${ARCHIVE_PATH}" -C "${TMP_DIR}" "${BINARY_NAME}"
chmod +x "${TMP_DIR}/${BINARY_NAME}"
mv "${TMP_DIR}/${BINARY_NAME}" "${INSTALL_DIR}/${BINARY_NAME}"

echo "Installed ccgm-agents to ${INSTALL_DIR}/${BINARY_NAME}"

# ---- PATH reminder ----------------------------------------------------------

if ! echo "${PATH}" | grep -q "${INSTALL_DIR}"; then
  echo ""
  echo "NOTE: ${INSTALL_DIR} is not in your PATH."
  echo "Add this to your shell profile (.zshrc, .bashrc, etc.):"
  echo "  export PATH=\"\${HOME}/.ccgm/bin:\${PATH}\""
fi

echo "Run 'ccgm-agents' or use the /agents command to launch the TUI."

View source on GitHub

Install this module

Install anyway

Agent prompt

Recommended for agent users -- hands the whole install off to your assistant.

Fetch https://cd23a9be.ccgm-site.pages.dev/modules/agent-manager.md and install this module into my Claude Code setup.

Native plugin marketplace

One command via the native plugin marketplace -- additive, does not merge settings.json.

claude plugin install agent-manager@ccgm

The marketplace path is additive, not a replacement: it installs commands, agents, and skills as native plugin components, but it does not perform the bash installer's deep settings.json merge, and it does not write the always-loaded global CLAUDE.md context. Rules are only injected via an opt-in SessionStart hook rather than being auto-loaded. Use the bash installer when those pieces matter to you.

Manual, per file

Full control -- copy exactly the files you want from the sections below.

Files

command (1)

commands/agents.md

---
description: Launch the CCGM Agent Manager TUI for managing Claude Code agent processes
allowed-tools: Bash
---

# /agents - Agent Manager

Launch the CCGM Agent Manager TUI to monitor and control Claude Code agent processes across multi-clone repos.

## Usage

```
$ARGUMENTS
```

## Instructions

Run the agent manager binary:

```bash
~/.ccgm/bin/ccgm-agents
```

If the binary is not found at `~/.ccgm/bin/ccgm-agents`, inform the user that the binary has not been installed. The CCGM installer does not install it automatically — they need to run `postInstall.sh` from `modules/agent-manager/` manually (or follow the manual steps in the module's README).

## Keybindings Reference

| Key | Action |
|-----|--------|
| `j` / `↓` | Move down |
| `k` / `↑` | Move up |
| `enter` | Select / open detail |
| `/` | Filter agents |
| `esc` | Back / close |
| `n` | Launch new agent |
| `s` | Stop agent |
| `r` | Restart agent |
| `x` | Kill agent (force) |
| `tab` | Switch panel |
| `e` | Export logs |
| `pgup` / `pgdn` | Scroll log viewer |
| `?` | Toggle help |
| `q` / `ctrl+c` | Quit |

## Configuration

The agent manager reads its configuration from `~/.ccgm/agent-manager/config.json`. If this file does not exist, sensible defaults are used:

- **Data directory**: `~/.ccgm/agent-manager/`
- **Health check interval**: 2 seconds
- **Hanging timeout**: 60 seconds
- **Log max size**: 50 MB
- **Log retention**: 7 days

View source on GitHub

Agent Manager TUI

Unmaintained module

Tags

README

Agent Manager TUI

What It Does

Installation

Binary install via script

Manual Installation

Usage

Keybindings

Configuration

Agent Lifecycle

Session Management

Building from Source

Dependencies

Platform Support

Will install

Dependencies

Required by

Included in presets

Manual step after install

Install this module

Agent prompt

Native plugin marketplace

Manual, per file

Files

commands/agents.md