Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/byte5ai/claudeplex

A terminal multiplexer & cockpit for Claude Code — monitor and orchestrate multiple Claude Max accounts from one TUI.
https://github.com/byte5ai/claudeplex

ai-agents anthropic bun claude claude-code cli dashboard multiplexer orchestrator terminal tui typescript

Last synced: 1 day ago
JSON representation

A terminal multiplexer & cockpit for Claude Code — monitor and orchestrate multiple Claude Max accounts from one TUI.

Awesome Lists containing this project

README 

          


  Claudeplex






  A terminal multiplexer & cockpit for Claude Code.


  Monitor and orchestrate multiple Claude Max accounts from one TUI — like tmux, but for your Claudes.






  license

  runtime

  platform




## What is this?



If you run Claude Code across several accounts — a personal Max plan, a work account, a

client login, each under its own `CLAUDE_CONFIG_DIR` — you lose the overview fast. Which

account is burning through its 5-hour window? Which sessions are mid-task vs. waiting on you?

Where did that one agent run again?



**Claudeplex** puts all of it in a single animated terminal dashboard:



- **Live load per account** — 5-hour and weekly token usage, cost and reset timers, heat-colored so you can see at a glance who has headroom.

- **Every session at a glance** — running, waiting and recent sessions across all accounts, grouped by working folder, with live activity tails.

- **A cockpit to drive agents** — launch headless Claude agents, talk to them, paste images, restart them to pick up new plugins/MCP, and adopt sessions that are waiting for input.

- **Zero config** — it auto-discovers your Claude accounts; no aliases or setup files required.



It is **read-only** on your Claude config dirs (it never writes to them) and runs entirely on

your machine — see [Security & privacy](#security--privacy).



## Features



- 📊 **Multi-account load dashboard** — 5h / weekly usage, cost and reset countdowns per account.

- 🖥️ **Session monitor** — live + recent sessions across all accounts, grouped by folder, with status (active / monitor / waiting / stale) and live output tails.

- 🚀 **New-agent wizard** — a popup to launch a fresh agent: pick an account (by spare capacity) → pick a working folder, or flip it the other way (folder → account). Spans your full project history.

- 🎛️ **Agent cockpit** — message agents directly, attach clipboard images, restart, kill, and take over sessions that are waiting on you.

- 📝 **Quick-issue** — pick a repo, describe the problem; a free account drafts a clean, code-grounded English GitHub issue, you review/rewrite, then it files it via `gh`.

- 🔀 **PR-review** — list a repo's open PRs, have a free account analyze one against the code (risk level, mergeability, categorized findings), then approve / comment / request changes / merge — or launch a session to keep working on it.

- 🔎 **Auto-discovery** — finds every Claude account on the machine. No shell aliases needed.

- 🌍 **Bilingual UI** — English / German, auto-detected from `$LANG`, toggle live.

- 🧩 **Scriptable** — `--json` emits a machine-readable snapshot of all accounts/usage/sessions.



## Requirements



- **[Claude Code](https://github.com/anthropics/claude-code)** installed and **at least one account signed in** (`claude` → login). Claudeplex drives the real `claude` CLI.

- **macOS** (primary target — fullscreen and clipboard use `osascript`/`pbpaste`). Linux mostly works; those niceties degrade gracefully.

- **[Bun](https://bun.sh)** ≥ 1.1 — only to run from source. The prebuilt binaries bundle the runtime, so end users won't need it.



## Install



### Homebrew (macOS)



```bash

brew install byte5ai/tap/claudeplex

```



### Install script (macOS / Linux)



```bash

curl -fsSL https://raw.githubusercontent.com/byte5ai/claudeplex/main/install.sh | sh

```



Downloads the standalone binary for your OS/arch from the latest GitHub Release into

`/usr/local/bin` (or `~/.local/bin`). No Bun required.



### From source



```bash

git clone https://github.com/byte5ai/claudeplex.git

cd claudeplex

bun install

bun start

```



## Quick start



```bash

claudeplex          # the live dashboard (fullscreen TUI)

claudeplex --once   # render a single frame and exit

claudeplex --json   # machine-readable snapshot (no TTY needed)

```



> Running from source? Use `bun start`, `bun run once`, `bun run json`.



First run with no accounts detected? You'll get a friendly screen telling you to sign in with

`claude`. Got several accounts? Just give each its own `CLAUDE_CONFIG_DIR` — Claudeplex finds

them automatically (next section).



## How accounts are discovered



Claude Code stores everything for an account (sessions, usage, login) under one directory

pointed to by `CLAUDE_CONFIG_DIR`. To run multiple accounts you give each its own dir, e.g.:



```bash

# ~/.zshrc — one alias per account

alias c1='CLAUDE_CONFIG_DIR=~/.claude        claude'   # personal

alias c2='CLAUDE_CONFIG_DIR=~/.claude-work   claude'   # work

alias c3='CLAUDE_CONFIG_DIR=~/.claude-client claude'   # a client

```



**You do not need those aliases for Claudeplex.** At startup it builds the account list from

the union of three sources, de-duplicated by absolute path:



1. **Filesystem scan** — every `~/.claude` and `~/.claude-*` directory that looks like a real

   account (has a `.claude.json`, `projects/` or `sessions/`). Helper dirs like `~/.claude-mem`

   are skipped.

2. **Running processes** — any live `claude` process started with an explicit

   `CLAUDE_CONFIG_DIR=…` (catches accounts living outside `$HOME`).

3. **Environment** — `$CLAUDE_CONFIG_DIR`, if set.



The bare `~/.claude` is only shown when it actually holds its own login (otherwise it's just

Claude Code's default config dir and would be noise). Each account's **label** is derived from

its account metadata (organization name, else the email's local-part), its **color** from a

palette, and its **key** (`c1`, `c2`, …) from a stable sort — so colors and keys don't reshuffle

between runs.



### Manual override (`~/.config/claudeplex/instances.json`)



Want to pin labels, recolor, reorder, or hide an account? Drop an optional JSON file at

**`~/.config/claudeplex/instances.json`**. It's an array of overrides matched to an account by

its `configDir`; every field is optional:



```jsonc

[

  // pin a friendly label + color for the personal account

  { "configDir": "/Users/you/.claude",        "key": "c1", "label": "personal", "color": 213, "order": 0 },



  // work account, force it to sort first

  { "configDir": "/Users/you/.claude-work",   "key": "wk", "label": "work",     "color": 81,  "order": 1 },



  // discovered, but you never want to see it

  { "configDir": "/Users/you/.claude-archive", "hide": true }

]

```



| Field | Meaning |

|-------|---------|

| `configDir` | **required** — absolute path of the account dir this override applies to |

| `key` | short id shown in the UI (default `c1`, `c2`, …) |

| `label` | human label (default: derived from account metadata) |

| `color` | accent color as a 256-color code (default: from palette) |

| `order` | explicit sort position (lower = earlier) |

| `hide` | `true` to drop the account from the dashboard entirely |



Overrides win over discovery; anything you leave out keeps its auto-derived value. Changes take

effect on the next launch (or press `r` to rescan).



## Keybindings



**Grid (home)**



| Key | Action |

|-----|--------|

| `↑/↓` | select account |

| `→` / `⏎` | open account detail (sessions) |

| `Tab` / `1`–`3` | switch region: ① cards · ② live output · ③ waiting/stale |

| `c` | open the agent **cockpit** |

| `n` | **new-agent wizard** (popup) |

| `N` | quick-launch an agent on the selected account |

| `A` | start an agent on every account |

| `i` | **quick-issue** (popup) |

| `p` | **PR-review** (popup) |

| `L` | toggle language (EN/DE) |

| `r` / `q` | rescan / quit |



**New-agent wizard** — `↑/↓` move · `Tab` `→` next pane · `←` back · `^T` flip orientation (account↔folder) · `⏎` launch · `Esc` cancel



**Quick-issue** — `↑/↓` pick repo · `Tab`/`→` description · type freely · `⏎` draft · on the draft: `⏎` create · `r` rewrite · `↑/↓` scroll · `Esc` cancel



**PR-review** — `↑/↓` pick repo / PR · `Tab` switch pane · `⏎` analyze · on the verdict: `a` approve · `c` comment · `r` request changes · `m` merge · `s` start a session on the PR · `↑/↓` scroll · `Esc` close



**Cockpit** — type to message the agent · `⏎` send · `^V` paste image · `Tab` open-questions list · `^N` new agent · `^R` restart · `^K` kill · `Esc` back



**Detail / transcript** — `↑/↓` navigate · `→`/`⏎` open transcript · `PgUp/PgDn` scroll · `←`/`Esc` back



**Waiting/stale region (③)** — `⏎` open in cockpit · `e` rename · `x` close (press twice to confirm)



## Configuration (env vars)



| Variable | Default | Purpose |

|----------|---------|---------|

| `CD_BUDGET_5H` | `20000000` | token budget used to scale the 5h load bar |

| `CD_BUDGET_WEEK` | `300000000` | token budget for the weekly load bar |

| `CD_ACTIVE_MINS` | `15` | a session counts as "running" if written within this window |

| `CD_HISTORY_MINS` | `360` | also show recent non-running sessions for this long (`0` disables) |

| `CD_CTX_MAX` | auto | override the context-window size used for the % meter |

| `CD_NOTIFY` | off | set to enable a macOS notification when a session finishes its turn |

| `CD_NO_FULLSCREEN` | off | set to skip forcing the terminal window fullscreen |

| `CD_LANG` | auto | force UI language (`en` / `de`); otherwise detected from `$LANG` |



## Scripting



`claudeplex --json` prints a JSON snapshot — accounts, plan, status, per-window usage and the

live session list — for dashboards, alerts or cron jobs. No TTY required.



## How it works



Claudeplex is a small, dependency-free Bun/TypeScript TUI:



- **`discover.ts`** finds the accounts (config dirs) and applies your overrides.

- **`collect.ts`** reads each account's session transcripts (`projects/*.jsonl`), the live

  process registry (`sessions/*.json`) and account metadata (`.claude.json`) — strictly

  read-only — and aggregates usage, status and per-folder history.

- **`agent.ts` / `agents.ts`** own the agents Claudeplex launches: each drives a real

  interactive `claude` session over a Bun-native PTY, pinned to the right account's login (it

  scrubs `ANTHROPIC_API_KEY` so it always uses the subscription). Interactive — not headless

  `-p` — keeps work on the flat Pro/Max plan instead of the metered Agent-SDK credit pool.

- **`issue.ts` / `pr.ts`** back the quick-issue and PR-review popups: a free account runs an

  interactive one-shot to draft an issue or analyze a PR, and `gh` files the issue / posts the

  review / merges. PR analysis returns a structured verdict (risk + mergeability + findings).

- **`render.ts`** draws everything — the grid, the cockpit, transcripts, and the popup wizard,

  issue and PR modals (composited over the dashboard with an ANSI-aware overlay).



## Security & privacy



- **Read-only** on your Claude config dirs — Claudeplex never writes to them.

- **Local only** — no servers, no telemetry, no analytics. Your sessions, code and logins

  never leave your machine.

- Agents it launches run as your **existing Claude Code OAuth login** for that account; the

  pay-per-use `ANTHROPIC_API_KEY` is scrubbed from their environment.



## Building binaries



```bash

bun run build        # compiles standalone binaries for all targets into ./dist

```



CI builds and publishes these on every `v*` tag (see `.github/workflows/release.yml`).



## Contributing



Issues and PRs welcome. Keep it dependency-free, run `bun run typecheck` before pushing, and

match the existing style (focused files, clear comments). Built with [Bun](https://bun.sh).



## License



[MIT](LICENSE) © byte5ai and Claudeplex contributors.