{"id":51035426,"url":"https://github.com/byte5ai/claudeplex","last_synced_at":"2026-06-22T05:30:29.751Z","repository":{"id":365087392,"uuid":"1270478914","full_name":"byte5ai/claudeplex","owner":"byte5ai","description":"A terminal multiplexer \u0026 cockpit for Claude Code — monitor and orchestrate multiple Claude Max accounts from one TUI.","archived":false,"fork":false,"pushed_at":"2026-06-15T19:50:42.000Z","size":162,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T21:21:10.087Z","etag":null,"topics":["ai-agents","anthropic","bun","claude","claude-code","cli","dashboard","multiplexer","orchestrator","terminal","tui","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/byte5ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-15T18:49:48.000Z","updated_at":"2026-06-15T19:50:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/byte5ai/claudeplex","commit_stats":null,"previous_names":["byte5ai/claudeplex"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/byte5ai/claudeplex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byte5ai%2Fclaudeplex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byte5ai%2Fclaudeplex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byte5ai%2Fclaudeplex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byte5ai%2Fclaudeplex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/byte5ai","download_url":"https://codeload.github.com/byte5ai/claudeplex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byte5ai%2Fclaudeplex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34636427,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","anthropic","bun","claude","claude-code","cli","dashboard","multiplexer","orchestrator","terminal","tui","typescript"],"created_at":"2026-06-22T05:30:29.044Z","updated_at":"2026-06-22T05:30:29.733Z","avatar_url":"https://github.com/byte5ai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/claudeplex.svg\" alt=\"Claudeplex\" width=\"860\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eA terminal multiplexer \u0026amp; cockpit for \u003ca href=\"https://github.com/anthropics/claude-code\"\u003eClaude Code\u003c/a\u003e.\u003c/b\u003e\u003cbr\u003e\n  Monitor and orchestrate \u003ci\u003emultiple\u003c/i\u003e Claude Max accounts from one TUI — like \u003ccode\u003etmux\u003c/code\u003e, but for your Claudes.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"license\" src=\"https://img.shields.io/badge/license-MIT-ec4899\"\u003e\n  \u003cimg alt=\"runtime\" src=\"https://img.shields.io/badge/runtime-Bun-ec4899\"\u003e\n  \u003cimg alt=\"platform\" src=\"https://img.shields.io/badge/platform-macOS-ec4899\"\u003e\n\u003c/p\u003e\n\n## What is this?\n\nIf you run Claude Code across several accounts — a personal Max plan, a work account, a\nclient login, each under its own `CLAUDE_CONFIG_DIR` — you lose the overview fast. Which\naccount is burning through its 5-hour window? Which sessions are mid-task vs. waiting on you?\nWhere did that one agent run again?\n\n**Claudeplex** puts all of it in a single animated terminal dashboard:\n\n- **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.\n- **Every session at a glance** — running, waiting and recent sessions across all accounts, grouped by working folder, with live activity tails.\n- **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.\n- **Zero config** — it auto-discovers your Claude accounts; no aliases or setup files required.\n\nIt is **read-only** on your Claude config dirs (it never writes to them) and runs entirely on\nyour machine — see [Security \u0026amp; privacy](#security--privacy).\n\n## Features\n\n- 📊 **Multi-account load dashboard** — 5h / weekly usage, cost and reset countdowns per account.\n- 🖥️ **Session monitor** — live + recent sessions across all accounts, grouped by folder, with status (active / monitor / waiting / stale) and live output tails.\n- 🚀 **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.\n- 🎛️ **Agent cockpit** — message agents directly, attach clipboard images, restart, kill, and take over sessions that are waiting on you.\n- 📝 **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`.\n- 🔀 **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.\n- 🔎 **Auto-discovery** — finds every Claude account on the machine. No shell aliases needed.\n- 🌍 **Bilingual UI** — English / German, auto-detected from `$LANG`, toggle live.\n- 🧩 **Scriptable** — `--json` emits a machine-readable snapshot of all accounts/usage/sessions.\n\n## Requirements\n\n- **[Claude Code](https://github.com/anthropics/claude-code)** installed and **at least one account signed in** (`claude` → login). Claudeplex drives the real `claude` CLI.\n- **macOS** (primary target — fullscreen and clipboard use `osascript`/`pbpaste`). Linux mostly works; those niceties degrade gracefully.\n- **[Bun](https://bun.sh)** ≥ 1.1 — only to run from source. The prebuilt binaries bundle the runtime, so end users won't need it.\n\n## Install\n\n### Homebrew (macOS)\n\n```bash\nbrew install byte5ai/tap/claudeplex\n```\n\n### Install script (macOS / Linux)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/byte5ai/claudeplex/main/install.sh | sh\n```\n\nDownloads the standalone binary for your OS/arch from the latest GitHub Release into\n`/usr/local/bin` (or `~/.local/bin`). No Bun required.\n\n### From source\n\n```bash\ngit clone https://github.com/byte5ai/claudeplex.git\ncd claudeplex\nbun install\nbun start\n```\n\n## Quick start\n\n```bash\nclaudeplex          # the live dashboard (fullscreen TUI)\nclaudeplex --once   # render a single frame and exit\nclaudeplex --json   # machine-readable snapshot (no TTY needed)\n```\n\n\u003e Running from source? Use `bun start`, `bun run once`, `bun run json`.\n\nFirst run with no accounts detected? You'll get a friendly screen telling you to sign in with\n`claude`. Got several accounts? Just give each its own `CLAUDE_CONFIG_DIR` — Claudeplex finds\nthem automatically (next section).\n\n## How accounts are discovered\n\nClaude Code stores everything for an account (sessions, usage, login) under one directory\npointed to by `CLAUDE_CONFIG_DIR`. To run multiple accounts you give each its own dir, e.g.:\n\n```bash\n# ~/.zshrc — one alias per account\nalias c1='CLAUDE_CONFIG_DIR=~/.claude        claude'   # personal\nalias c2='CLAUDE_CONFIG_DIR=~/.claude-work   claude'   # work\nalias c3='CLAUDE_CONFIG_DIR=~/.claude-client claude'   # a client\n```\n\n**You do not need those aliases for Claudeplex.** At startup it builds the account list from\nthe union of three sources, de-duplicated by absolute path:\n\n1. **Filesystem scan** — every `~/.claude` and `~/.claude-*` directory that looks like a real\n   account (has a `.claude.json`, `projects/` or `sessions/`). Helper dirs like `~/.claude-mem`\n   are skipped.\n2. **Running processes** — any live `claude` process started with an explicit\n   `CLAUDE_CONFIG_DIR=…` (catches accounts living outside `$HOME`).\n3. **Environment** — `$CLAUDE_CONFIG_DIR`, if set.\n\nThe bare `~/.claude` is only shown when it actually holds its own login (otherwise it's just\nClaude Code's default config dir and would be noise). Each account's **label** is derived from\nits account metadata (organization name, else the email's local-part), its **color** from a\npalette, and its **key** (`c1`, `c2`, …) from a stable sort — so colors and keys don't reshuffle\nbetween runs.\n\n### Manual override (`~/.config/claudeplex/instances.json`)\n\nWant to pin labels, recolor, reorder, or hide an account? Drop an optional JSON file at\n**`~/.config/claudeplex/instances.json`**. It's an array of overrides matched to an account by\nits `configDir`; every field is optional:\n\n```jsonc\n[\n  // pin a friendly label + color for the personal account\n  { \"configDir\": \"/Users/you/.claude\",        \"key\": \"c1\", \"label\": \"personal\", \"color\": 213, \"order\": 0 },\n\n  // work account, force it to sort first\n  { \"configDir\": \"/Users/you/.claude-work\",   \"key\": \"wk\", \"label\": \"work\",     \"color\": 81,  \"order\": 1 },\n\n  // discovered, but you never want to see it\n  { \"configDir\": \"/Users/you/.claude-archive\", \"hide\": true }\n]\n```\n\n| Field | Meaning |\n|-------|---------|\n| `configDir` | **required** — absolute path of the account dir this override applies to |\n| `key` | short id shown in the UI (default `c1`, `c2`, …) |\n| `label` | human label (default: derived from account metadata) |\n| `color` | accent color as a 256-color code (default: from palette) |\n| `order` | explicit sort position (lower = earlier) |\n| `hide` | `true` to drop the account from the dashboard entirely |\n\nOverrides win over discovery; anything you leave out keeps its auto-derived value. Changes take\neffect on the next launch (or press `r` to rescan).\n\n## Keybindings\n\n**Grid (home)**\n\n| Key | Action |\n|-----|--------|\n| `↑/↓` | select account |\n| `→` / `⏎` | open account detail (sessions) |\n| `Tab` / `1`–`3` | switch region: ① cards · ② live output · ③ waiting/stale |\n| `c` | open the agent **cockpit** |\n| `n` | **new-agent wizard** (popup) |\n| `N` | quick-launch an agent on the selected account |\n| `A` | start an agent on every account |\n| `i` | **quick-issue** (popup) |\n| `p` | **PR-review** (popup) |\n| `L` | toggle language (EN/DE) |\n| `r` / `q` | rescan / quit |\n\n**New-agent wizard** — `↑/↓` move · `Tab` `→` next pane · `←` back · `^T` flip orientation (account↔folder) · `⏎` launch · `Esc` cancel\n\n**Quick-issue** — `↑/↓` pick repo · `Tab`/`→` description · type freely · `⏎` draft · on the draft: `⏎` create · `r` rewrite · `↑/↓` scroll · `Esc` cancel\n\n**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\n\n**Cockpit** — type to message the agent · `⏎` send · `^V` paste image · `Tab` open-questions list · `^N` new agent · `^R` restart · `^K` kill · `Esc` back\n\n**Detail / transcript** — `↑/↓` navigate · `→`/`⏎` open transcript · `PgUp/PgDn` scroll · `←`/`Esc` back\n\n**Waiting/stale region (③)** — `⏎` open in cockpit · `e` rename · `x` close (press twice to confirm)\n\n## Configuration (env vars)\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `CD_BUDGET_5H` | `20000000` | token budget used to scale the 5h load bar |\n| `CD_BUDGET_WEEK` | `300000000` | token budget for the weekly load bar |\n| `CD_ACTIVE_MINS` | `15` | a session counts as \"running\" if written within this window |\n| `CD_HISTORY_MINS` | `360` | also show recent non-running sessions for this long (`0` disables) |\n| `CD_CTX_MAX` | auto | override the context-window size used for the % meter |\n| `CD_NOTIFY` | off | set to enable a macOS notification when a session finishes its turn |\n| `CD_NO_FULLSCREEN` | off | set to skip forcing the terminal window fullscreen |\n| `CD_LANG` | auto | force UI language (`en` / `de`); otherwise detected from `$LANG` |\n\n## Scripting\n\n`claudeplex --json` prints a JSON snapshot — accounts, plan, status, per-window usage and the\nlive session list — for dashboards, alerts or cron jobs. No TTY required.\n\n## How it works\n\nClaudeplex is a small, dependency-free Bun/TypeScript TUI:\n\n- **`discover.ts`** finds the accounts (config dirs) and applies your overrides.\n- **`collect.ts`** reads each account's session transcripts (`projects/*.jsonl`), the live\n  process registry (`sessions/*.json`) and account metadata (`.claude.json`) — strictly\n  read-only — and aggregates usage, status and per-folder history.\n- **`agent.ts` / `agents.ts`** own the agents Claudeplex launches: each drives a real\n  interactive `claude` session over a Bun-native PTY, pinned to the right account's login (it\n  scrubs `ANTHROPIC_API_KEY` so it always uses the subscription). Interactive — not headless\n  `-p` — keeps work on the flat Pro/Max plan instead of the metered Agent-SDK credit pool.\n- **`issue.ts` / `pr.ts`** back the quick-issue and PR-review popups: a free account runs an\n  interactive one-shot to draft an issue or analyze a PR, and `gh` files the issue / posts the\n  review / merges. PR analysis returns a structured verdict (risk + mergeability + findings).\n- **`render.ts`** draws everything — the grid, the cockpit, transcripts, and the popup wizard,\n  issue and PR modals (composited over the dashboard with an ANSI-aware overlay).\n\n## Security \u0026amp; privacy\n\n- **Read-only** on your Claude config dirs — Claudeplex never writes to them.\n- **Local only** — no servers, no telemetry, no analytics. Your sessions, code and logins\n  never leave your machine.\n- Agents it launches run as your **existing Claude Code OAuth login** for that account; the\n  pay-per-use `ANTHROPIC_API_KEY` is scrubbed from their environment.\n\n## Building binaries\n\n```bash\nbun run build        # compiles standalone binaries for all targets into ./dist\n```\n\nCI builds and publishes these on every `v*` tag (see `.github/workflows/release.yml`).\n\n## Contributing\n\nIssues and PRs welcome. Keep it dependency-free, run `bun run typecheck` before pushing, and\nmatch the existing style (focused files, clear comments). Built with [Bun](https://bun.sh).\n\n## License\n\n[MIT](LICENSE) © byte5ai and Claudeplex contributors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyte5ai%2Fclaudeplex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbyte5ai%2Fclaudeplex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyte5ai%2Fclaudeplex/lists"}