A cross-platform terminal aggregator with multi-workspace support and built-in AI agent integration
Manage multiple project terminals in one window, with built-in support for Claude Code, Gemini CLI, GitHub Copilot CLI, Codex CLI, and any custom CLI agent — all in a single Electron app. Includes a file browser, git viewer, snippet manager, remote access, and a supervisor mode for orchestrating multiple AI agents on the same project.
Claude Code Agent Panel — Built-in AI agent with permission controls, status line, and streaming output
Terminal — Run persistent terminals alongside your agent for long-running commands and monitoring
File Browser — Browse and preview project files without leaving the app
Git Viewer — View commit history and diffs at a glance
- Multi-Workspace — Organize terminals by project folders; each workspace binds to a directory
- Drag & Drop — Reorder workspaces freely in the sidebar
- Groups — Categorize workspaces into named groups with a filter dropdown
- Profiles — Save and switch between multiple workspace configurations (local or remote)
- Detachable Windows — Pop out individual workspaces to separate windows; auto-reattach on restart
- Per-Workspace Env Vars — Configure custom environment variables per workspace
- Activity Indicators — Visual dots showing which workspaces have active terminal processes
- Double-click to rename, right-click context menu for all workspace actions
- Split-panel layout — 70% main panel + 30% scrollable thumbnail bar showing all terminals
- Multiple terminals per workspace — Powered by xterm.js with full Unicode/CJK support
- Agent presets — Pre-configured terminal roles: Claude Code, Gemini CLI, Codex, GitHub Copilot, or plain terminal
- Custom CLI agents — Register any CLI tool as an agent from Settings (name, command, icon, color, sandbox/yolo mode)
- Supervisor mode — Designate one terminal as the project supervisor to monitor and send commands to other worker terminals (right-click → Set as Supervisor)
- Git worktree isolation — Spawn Claude agents in an isolated worktree to prevent destructive changes to your main working tree
- Tab navigation — Switch between Terminal, Files, and Git views per workspace
- File browser — Search, navigate, and preview files with syntax highlighting (highlight.js)
- Git integration — Commit log, diff viewer, branch display, untracked file list, GitHub link detection
- Snippet manager — Save, organize, search, and paste code snippets (SQLite-backed with categories and favorites)
- Built-in Claude Code via SDK — Runs the agent directly inside the app; no separate terminal needed
- Message streaming with extended thinking blocks (collapsible)
- Permission-based tool execution — Every tool call is intercepted; approve individually, or enable bypass/plan mode for auto-approval
- Subagent tracking — See spawned subagent tasks with progress indicators and stall detection
- Session resume — Persist conversations and resume them across app restarts
- Session fork — Branch off from any point in a conversation
- Rest/Wake sessions — Pause and resume agent sessions from the context menu to save resources
- Statusline — Live display of token usage, cost, context window %, model name, git branch, turn count, and session duration
- Usage monitoring — Track API rate limits (5-hour and 7-day windows) via Anthropic OAuth
- Context usage panel — Visualize token usage breakdown by category (code, conversation, tools, memory, etc.)
- Account switching —
/login,/logout,/whoamislash commands for managing Claude accounts - Prompt history — View and copy all previous user prompts from the statusline
- Image attachment — Drag-drop or use the attach button (up to 5 images per message)
- Clickable URLs — Markdown links and bare URLs open in the default browser
- Clickable file paths — Click any file path in agent output to preview it with syntax highlighting and search (Ctrl+F)
- Ctrl+P file picker — Fuzzy-search project files and attach them to the conversation context
- Update notifications — Automatic check for new releases on GitHub
| Shortcut | Action |
|---|---|
Ctrl+`` / `Cmd+ ` `` |
Toggle between Agent terminal and first regular terminal |
Ctrl+←/→ / Cmd+←/→ |
Cycle workspace tabs (Terminal / Files / Git) |
Ctrl+↑/↓ / Cmd+↑/↓ |
Switch to previous / next workspace |
Ctrl+P / Cmd+P |
File picker (search & attach files to agent context) |
Ctrl+N / Cmd+N |
Open new window |
Shift+Tab |
Switch between Terminal and Agent mode |
Enter |
Send message |
Shift+Enter |
Insert newline (multiline input) |
Escape |
Stop streaming / close modal |
Ctrl+Shift+C |
Copy selected text |
Ctrl+Shift+V |
Paste from clipboard |
Right-click |
Copy (if text selected) or Paste |
| Command | Description |
|---|---|
/resume |
Resume a previous Claude session from history |
/model |
Switch between available Claude models |
/new / /clear |
Reset session (clear conversation, fresh start) |
/snippet |
Show snippets to Claude for management |
/login |
Sign in to Claude (switch account) |
/logout |
Sign out of Claude |
/whoami |
Show current account info and usage |
brew tap tonyq-org/tap
brew install --cask better-agent-terminalchoco install better-agent-terminalPackage is currently pending review on Chocolatey.org.
Download from Releases for your platform:
| Platform | Format |
|---|---|
| Windows | NSIS installer, .zip |
| macOS | .dmg (universal binary) |
| Linux | .AppImage |
macOS DMG installation:
- Download the
.dmgfile from Releases - Double-click the
.dmgto mount it - Drag Better Agent Terminal into the Applications folder
- On first launch, macOS may block the app — go to System Settings > Privacy & Security, scroll down and click Open Anyway
- Make sure Claude Code CLI is installed (
npm install -g @anthropic-ai/claude-code)
Prerequisites:
- Node.js 18+
- Claude Code CLI installed and authenticated
git clone https://github.com/tony1223/better-agent-terminal.git
cd better-agent-terminal
npm installDevelopment mode:
npm run devBuild for production:
npm run buildRun the following command in your terminal (macOS, Linux, or Windows with Git Bash/MSYS2):
curl -fsSL https://raw.githubusercontent.com/tony1223/better-agent-terminal/main/install.sh | bashThis script will detect your OS and install the application to the standard location.
Native dependencies (node-pty, better-sqlite3) require Xcode Command Line Tools:
xcode-select --installThen:
npm install
npm run dev # Development
npm run build # Build .dmgbetter-agent-terminal/
├── electron/ # Main process (Node.js)
│ ├── main.ts # App entry, IPC handlers, window management
│ ├── preload.ts # Context bridge (window.electronAPI)
│ ├── pty-manager.ts # PTY process lifecycle, output batching, ring buffer
│ ├── claude-agent-manager.ts # Claude SDK session management
│ ├── worktree-manager.ts # Git worktree lifecycle (create, remove, rehydrate)
│ ├── agent-runtime/ # Universal agent runtime layer
│ │ ├── types.ts # AgentDefinition, AgentProvider, AgentCapabilities
│ │ ├── agent-registry.ts # Singleton registry with 9 built-in + custom CLI definitions
│ │ └── index.ts # Module barrel export
│ ├── logger.ts # Disk-based logger (enable with BAT_DEBUG=1)
│ ├── snippet-db.ts # SQLite snippet storage
│ ├── profile-manager.ts # Profile CRUD and persistence
│ ├── update-checker.ts # GitHub release update check
│ └── remote/
│ ├── protocol.ts # Proxied channel/event definitions
│ ├── handler-registry.ts # Unified IPC + remote handler registry
│ ├── broadcast-hub.ts # Event broadcasting to remote clients
│ ├── remote-server.ts # WebSocket server (host mode)
│ ├── remote-client.ts # WebSocket client (connect mode)
│ └── tunnel-manager.ts # IP detection, Tailscale, QR code info
├── src/ # Renderer process (React)
│ ├── App.tsx # Root component, layout, profile orchestration
│ ├── components/
│ │ ├── Sidebar.tsx # Workspace list, groups, drag-drop, context menu
│ │ ├── WorkspaceView.tsx # Per-workspace container with supervisor wiring
│ │ ├── WorkerPanel.tsx # Supervisor worker list with send-to-worker UI
│ │ ├── ClaudeAgentPanel.tsx # Claude agent chat UI and streaming
│ │ ├── TerminalPanel.tsx # xterm.js terminal wrapper (optimized rendering)
│ │ ├── ThumbnailBar.tsx # Scrollable terminal thumbnail strip
│ │ ├── MainPanel.tsx # Tab container (Terminal / Files / Git)
│ │ ├── TerminalThumbnail.tsx # Terminal thumbnail with supervisor badge + context menu
│ │ ├── GitPanel.tsx # Git log, diff, status viewer
│ │ ├── FileTree.tsx # In-app file browser
│ │ ├── PathLinker.tsx # Clickable file paths & URLs, preview modal
│ │ ├── SnippetPanel.tsx # Snippet manager sidebar
│ │ ├── PromptBox.tsx # Agent message input with image attach
│ │ ├── SettingsPanel.tsx # App settings UI + Custom CLI management
│ │ ├── ProfilePanel.tsx # Profile switcher
│ │ ├── EnvVarEditor.tsx # Per-workspace env var editor
│ │ └── UpdateNotification.tsx # Update banner
│ ├── stores/
│ │ ├── workspace-store.ts # Workspace + terminal state + supervisor methods
│ │ └── settings-store.ts # App settings persistence
│ ├── types/
│ │ ├── index.ts # Core types (Workspace, TerminalInstance w/ role, etc.)
│ │ ├── agent-runtime.ts # Frontend-side agent types + helpers
│ │ ├── claude-agent.ts # Claude message and tool call types
│ │ ├── agent-presets.ts # Agent preset definitions
│ │ └── electron.d.ts # window.electronAPI type declarations
│ └── styles/
│ ├── main.css
│ ├── claude-agent.css
│ └── path-linker.css
├── assets/ # App icons and screenshots
├── scripts/
│ └── build-version.js # Version string generator
└── package.json
- Frontend: React 18 + TypeScript
- Terminal: xterm.js + node-pty
- Framework: Electron 28
- AI: @anthropic-ai/claude-agent-sdk
- Build: Vite 5 + electron-builder
- Storage: better-sqlite3 (snippets, session data)
- Remote: ws (WebSocket) + qrcode
- Syntax Highlighting: highlight.js
BAT supports running multiple AI CLI agents simultaneously within the same workspace. Instead of being locked to a single agent, you can mix and match different AI tools for different tasks.
| Agent | Command | Capabilities |
|---|---|---|
| Claude Code (SDK) | Built-in SDK integration | Structured events, permission controls, session resume |
| Claude Code (CLI) | claude |
Full CLI experience in terminal |
| Gemini CLI | gemini |
Google's AI assistant, sandbox mode |
| GitHub Copilot CLI | github-copilot-cli |
GitHub's AI coding assistant |
| Codex CLI | codex |
OpenAI's coding agent, sandbox/yolo modes |
Add any CLI tool as an agent from Settings → Custom CLIs:
- Open Settings (gear icon in sidebar)
- Scroll to Custom CLI Management
- Fill in: Name, Command, Icon (emoji), Color (hex), and optional Sandbox/Yolo flags
- Click Add — the new agent appears in the "+" menu immediately
Custom CLIs are persisted to {userData}/custom-clis.json and survive app restarts.
The agent runtime layer exposes IPC methods for querying and managing agents:
| IPC Channel | Description |
|---|---|
agent:list-definitions |
List all registered agent definitions |
agent:get-definition |
Get a specific agent definition by ID |
agent:build-launch-command |
Build the CLI launch command with flags |
agent:register-custom-cli |
Register a new custom CLI agent |
agent:remove-custom-cli |
Remove a custom CLI agent |
Supervisor mode lets you designate one terminal as a project supervisor that can monitor and send commands to other worker terminals. This enables orchestration patterns where one AI agent oversees the work of others.
- Open multiple terminals with different agents (e.g., Claude as supervisor, Codex + Gemini as workers)
- Right-click any terminal thumbnail → "👁 Set as Supervisor"
- The supervisor terminal gets a golden border and 👁 badge
- A Worker Panel appears on the right side showing all other terminals with:
- Worker name, agent type, and alive/dead status
- Last few lines of each worker's output
- Quick-send input field to type commands into any worker
- Only one supervisor per workspace; setting a new one auto-demotes the previous
| IPC Channel | Description |
|---|---|
supervisor:list-workers |
List worker terminals with status and last output |
supervisor:send-to-worker |
Write text to a worker terminal's PTY input |
supervisor:get-worker-output |
Read last N lines from a worker's output buffer |
- Test-driven development: Claude monitors test results, tells Codex to fix failing tests
- Code review pipeline: Supervisor reviews changes, dispatches fixes to workers
- Parallel task execution: Assign different features to different agents, monitor progress from one place
BAT includes a built-in WebSocket server that allows other BAT instances or mobile devices to connect and control it remotely. This feature is currently experimental.
- The Host enables the WebSocket server in Settings → Remote Access (default port: 9876)
- On startup, the server generates a Connection Token (32-character hex string) used to authenticate connections
- The Client connects by entering the host IP, port, and token via a Remote Profile
- Once connected, the client can operate all terminals, Claude Agent sessions, workspaces, and other features on the host
On the client BAT instance:
- Open Settings → Profiles
- Create a new profile and set the type to Remote
- Enter the host IP, port (9876), and token
- Load the profile to connect to the remote host
On the host BAT instance:
- Open Settings → Remote Access → Generate QR Code
- If the server is not yet running, it will start automatically
- Scan the QR code with a mobile device to retrieve the connection info
- The QR code contains the WebSocket URL and token (in JSON format)
If the host and client are not on the same local network (e.g., connecting from home to an office machine), we recommend using Tailscale to establish a secure peer-to-peer VPN:
- Free plan supports up to 100 devices
- No port forwarding or additional server setup required
- Each device gets a stable
100.x.x.xIP address - BAT automatically detects Tailscale IPs and uses them preferentially
Installation:
| Platform | Install |
|---|---|
| macOS | Download or brew install tailscale |
| Windows | Download |
| iOS | App Store |
| Android | Google Play |
| Linux | Install Guide |
After installation, sign in with the same account on all devices and they will be able to communicate. BAT's QR code will automatically use the Tailscale IP.
Warning: Enabling the Remote Server opens a WebSocket connection. Any device with the token can fully control BAT on the host machine, including executing terminal commands, accessing the file system, and controlling Claude Agent sessions.
- Do not start the server on untrusted networks
- Do not share the token with untrusted parties
- Shut down the server when not in use
- Strongly recommended to use Tailscale to avoid direct exposure to the public internet
Workspaces, settings, and session data are saved to:
| Platform | Path |
|---|---|
| Windows | %APPDATA%/better-agent-terminal/ |
| macOS | ~/Library/Application Support/better-agent-terminal/ |
| Linux | ~/.config/better-agent-terminal/ |
Set the BAT_DEBUG=1 environment variable to enable disk-based debug logging. Logs are written to debug.log in the configuration directory.
Follows semantic versioning: vMAJOR.MINOR.PATCH (e.g., v2.1.21)
Pre-release versions use the -pre.N suffix (e.g., v2.1.21-pre.1). Tags containing -pre are automatically marked as pre-release on GitHub and do not update the Homebrew tap.
Push a tag to trigger builds for all platforms:
git tag v2.1.21
git push origin v2.1.21MIT License - see LICENSE for details.
TonyQ - @tony1223
- lmanchu - @lmanchu - macOS/Linux support, workspace roles
- bluewings1211 - @bluewings1211 - Shift+Enter newline, preserve workspace state, resizable panels
- Henry Hu - @ninedter - Key API discovery and valuable architectural feedback
- craze429 - @craze429 - Windows/Linux credential reading, permission fix, git parsing fix, async dialog
- Owen - @Owen0857 - Windows zombie process fix, terminal resize black screen fix, debug log cleanup
- MikeThai - @mikethai - macOS .dmg spawn ENOENT fix
- Luke Chang - @lukeme117 - Snippet sidebar and UI improvements
Built with Claude Code