https://github.com/byte5ai/claudeplex-desktop
Claudeplex Desktop — Electron cockpit for monitoring & orchestrating multiple Claude Code (Max/Team) accounts
https://github.com/byte5ai/claudeplex-desktop
Last synced: 6 days ago
JSON representation
Claudeplex Desktop — Electron cockpit for monitoring & orchestrating multiple Claude Code (Max/Team) accounts
- Host: GitHub
- URL: https://github.com/byte5ai/claudeplex-desktop
- Owner: byte5ai
- Created: 2026-06-18T07:04:37.000Z (10 days ago)
- Default Branch: main
- Last Pushed: 2026-06-18T10:26:26.000Z (10 days ago)
- Last Synced: 2026-06-18T12:11:09.075Z (10 days ago)
- Language: TypeScript
- Size: 150 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Claudeplex Desktop
> An Electron cockpit for monitoring and orchestrating your Claude Code accounts — usage budgets, live sessions, transcripts, agent orchestration, and GitHub triage in one window.
Claudeplex Desktop reads your local Claude Code state **read-only** and turns it into a live dashboard. It discovers every Claude account/config directory on your machine, tracks 5-hour and weekly usage budgets, surfaces running sessions and their transcripts, and lets you spin up and drive interactive `claude` agents — all without ever writing to Claude's own config.
---
## Features
- **Overview cockpit** — a full-width landing screen summarizing every discovered account at a glance.
- **Accounts + usage budgets** — per-account 5-hour and weekly budget tracking with live refresh and flashing transitions.
- **Sessions + transcripts** — browse active sessions and render their `.jsonl` transcripts as readable Markdown.
- **Agent orchestration** — launch interactive `claude` PTY sessions from a new-agent wizard (`n`) and drive them in an embedded xterm terminal that replays history on reopen.
- **GitHub workflows** — quick issue creation, AI-assisted issue triage, and PR review, scoped to GitHub repositories only.
- **Command palette** — `⌘K` / `Ctrl+K` for fast navigation.
The dashboard layer is strictly **read-only** against your Claude config directories. Only the agent layer launches processes — and it does so as ordinary `claude` PTY sessions.
---
## Requirements
- [Bun](https://bun.sh) `≥ 1.3`
- macOS (primary target; other platforms are untested)
- [Claude Code](https://github.com/anthropics/claude-code) installed and at least one account configured
- A C/C++ toolchain for the native `node-pty` rebuild (Xcode Command Line Tools on macOS)
---
## Quick start
```bash
bun install # installs deps and rebuilds node-pty against Electron
bun run dev # launches the app
```
That's it — everything runs from the repository root.
---
## Build a native macOS app
The dev server (`bun run dev`) is convenient for iteration but runs an unbundled
React dev build — for a fast, native-feeling app, package it with
[electron-builder](https://electron.build):
```bash
# Build a standalone Claudeplex.app (fastest — no installer)
bun run pack:mac
open release/mac-arm64/Claudeplex.app
# …or build a distributable .dmg installer
bun run dist:mac # → release/Claudeplex--arm64.dmg
```
The build rebuilds `node-pty` for the target Electron ABI and unpacks it from the
asar archive (a native module can't be `dlopen`'d from inside asar).
**Gatekeeper:** local builds are unsigned, so on first launch macOS warns about an
unidentified developer — right-click the app → **Open** → **Open**. For real
distribution, provide an Apple Developer signing identity via the `CSC_*`
environment variables.
---
## Scripts
| Script | Description |
|--------|-------------|
| `bun run dev` | Start the app in development with hot reload (`electron-vite dev`). |
| `bun run build` | Produce a production bundle in `out/` (`electron-vite build`). |
| `bun run start` | Preview the production build (`electron-vite preview`). |
| `bun run pack:mac` | Build a standalone macOS `.app` into `release/` (no installer). |
| `bun run dist:mac` | Build a distributable macOS `.dmg` installer into `release/`. |
| `bun run typecheck` | Type-check the project with `tsc --noEmit`. |
| `bun test` | Run the core library test suite. |
| `bun run rebuild:native` | Rebuild the `node-pty` native module against Electron's ABI. |
---
## Project structure
```
claudeplex-desktop/
├── package.json # single root package — install & run from here
├── electron.vite.config.ts # main / preload / renderer build config + aliases
├── tsconfig.json # one root tsconfig with path aliases
├── index.html # renderer entry
├── tailwind.config.ts
├── postcss.config.js
├── electron/ # Electron main process (Node side)
│ ├── main.ts # window, IPC wiring, snapshot loop
│ ├── preload.ts # contextBridge surface
│ ├── pty.ts · agent*.ts # interactive claude agent orchestration
│ ├── github*.ts # GitHub issue/PR features
│ └── watcher.ts · usage.ts # filesystem watch + usage accounting
├── src/ # React renderer (browser side)
│ ├── core/ # framework-free, read-only data logic
│ ├── shell/ # app frame: Header, ActivityBar, StatusBar, Shell
│ ├── views/ # Overview, Accounts, Sessions, Cockpit, Settings, github/
│ ├── components/ # AgentTerminal, SessionRow, …
│ └── store/ # zustand state
└── test/ # core library tests (bun:test)
```
### Module aliases
| Alias | Resolves to |
|-------|-------------|
| `@claudeplex/core` | `src/core/index.ts` — the read-only data layer (account discovery, usage accounting, transcript parsing, i18n, git identity). |
| `@/…` | `src/…` — renderer source root. |
Both aliases are defined once in `tsconfig.json` (`paths`) and `electron.vite.config.ts` (`resolve.alias`).
---
## How it works
**`src/core`** is a framework-free, Node-runtime-safe library ported from a Bun CLI. It discovers accounts, collects snapshots, parses and renders transcripts, and computes usage budgets. It only ever **reads** Claude's config directories.
**`electron/main.ts`** runs the Node side: it drives a snapshot loop over `core`, watches the filesystem for changes, and forwards live updates to the renderer over IPC. It also hosts the agent registry that launches interactive `claude` PTY sessions and the GitHub feature handlers.
**`src/` (renderer)** is a React + Tailwind UI backed by a zustand store, rendering the cockpit, accounts, sessions, transcripts, and agent terminals.
`node-pty` is a native module and is intentionally **externalized** from the main/preload bundles so it loads against Electron's ABI at runtime (rebuilt automatically on `bun install`).
---
## Configuration
- Claudeplex auto-discovers Claude accounts from the standard config locations and respects `CLAUDE_CONFIG_DIR`.
- To pin or override discovered instances, create `~/.config/claudeplex/instances.json`.
---
## Development
```bash
bun run dev # iterate with hot reload
bun run typecheck # tsc --noEmit, must be clean
bun test # core test suite (bun:test)
bun run build # verify the full production bundle
```
If you change `node-pty` or upgrade Electron, run `bun run rebuild:native`.
---
## License
Private / unpublished.