Claude Terminal

English • Français • Español • Bahasa Indonesia • 简体中文 • Português (Brasil)

Downloads Version Platform License Electron CI Status Contributors i18n French i18n Spanish i18n Indonesian i18n Simplified Chinese

A cross-platform desktop application for managing Claude Code projects with an integrated terminal environment, git workflows, plugin management, and more.

Website • Download • Twitter • Buy Me a Coffee

Claude Terminal - The missing desktop app for Claude Code developers | Product Hunt

Top language Languages count Code size

--- ## 📊 Project Health ### Contributors Contributors ### Activity [![Commit activity](https://img.shields.io/github/commit-activity/m/Sterll/claude-terminal?label=commits%2Fmonth)](https://github.com/Sterll/claude-terminal/graphs/commit-activity) [![Last commit](https://img.shields.io/github/last-commit/Sterll/claude-terminal)](https://github.com/Sterll/claude-terminal/commits/main) [![Issues](https://img.shields.io/github/issues/Sterll/claude-terminal)](https://github.com/Sterll/claude-terminal/issues) [![Pull Requests](https://img.shields.io/github/issues-pr/Sterll/claude-terminal)](https://github.com/Sterll/claude-terminal/pulls) ### Internationalization (i18n) | Language | Coverage | Keys | | --- | --- | --- | | 🇺🇸 English (base) | ![100%][i18n-en-badge] | 3641 / 3641 | | 🇫🇷 French | ![i18n fr][i18n-fr-badge] | 3641 / 3641 | | 🇪🇸 Spanish | ![i18n es][i18n-es-badge] | 3641 / 3641 | | 🇮🇩 Indonesian | ![i18n id][i18n-id-badge] | 3641 / 3641 | | 🇨🇳 Simplified Chinese | ![i18n zh-CN][i18n-zh-cn-badge] | 3641 / 3641 | > Coverage badges are updated automatically on every push to locale files. > See [`.github/i18n-coverage.md`](.github/i18n-coverage.md) for details and > instructions on how to add a new language. [i18n-en-badge]: https://img.shields.io/badge/i18n-100%25-brightgreen [i18n-fr-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Sterll/ec1241ea62520261790ef5a411b4b212/raw/i18n_fr.json [i18n-es-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Sterll/ec1241ea62520261790ef5a411b4b212/raw/i18n_es.json [i18n-id-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Sterll/ec1241ea62520261790ef5a411b4b212/raw/i18n_id.json [i18n-zh-cn-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Sterll/ec1241ea62520261790ef5a411b4b212/raw/i18n_zh-CN.json --- ## Table of Contents - [Prerequisites](#prerequisites) - [Installation](#installation) - [Features](#features) - [Usage](#usage) - [Building](#building) - [Testing](#testing) - [Keyboard Shortcuts](#keyboard-shortcuts) - [Architecture](#architecture) - [Contributing](#contributing) - [Security](#security) --- ## Prerequisites - [Node.js](https://nodejs.org/) 18+ - [Claude Code](https://github.com/anthropics/claude-code) installed globally - **Windows** 10 or 11 - **macOS** 12+ (Intel or Apple Silicon) - **Linux** Ubuntu 22.04+, Fedora 38+, or equivalent - AppImage requires `libfuse2` on Ubuntu 24.04+: `sudo apt install libfuse2` - GitHub token storage requires `libsecret`: `sudo apt install libsecret-1-dev gnome-keyring` ## Installation Download the latest installer from [Releases](https://github.com/Sterll/claude-terminal/releases). > [!IMPORTANT] > **macOS users:** If you see *"Claude Terminal is damaged and can't be opened"*, run this in Terminal: > ```bash > xattr -cr /Applications/Claude\ Terminal.app > ``` > This is needed because the app is not code-signed yet. Alternatively, right-click the app → Open. Or build from source: ```bash git clone https://github.com/Sterll/claude-terminal.git cd claude-terminal npm install ``` --- ## Features ### Chat UI (Claude Agent SDK) - Built-in chat interface powered by the Claude Agent SDK with streaming responses - Closing a chat tab cancels pending startup and closes its SDK session; delayed prompts cannot restart a closed tab. - **Rich markdown rendering**: mermaid diagrams, KaTeX math, syntax-highlighted code, file trees, kanban boards, diff blocks, HTML previews, and more - **Permission cards**: Allow, Always Allow, or Deny tool use requests; when one of your own `permissions.ask` rules triggers the prompt, the card names that rule and hides Always Allow so it can't be one-clicked away - **Plan mode**: review and approve/reject agent plans before execution - **Thinking blocks**: expandable sections showing Claude's reasoning - **Tool cards**: collapsible cards showing tool execution with formatted details, including MCP tool refresh, feedback submission, and skill proposal actions - **Subagent visualization**: nested task tracking for spawned agents, with each subagent's summary showing its git worktree branch and any mid-run model switch - **Todo widget**: persistent task list above the input, auto-dismisses on completion - **Attachments**: paste, drag-drop, or pick PNG/JPEG/GIF/WebP images (up to 20MB), plus text files and PDFs - **Slash commands**: auto-completing commands (/compact, /clear, /help, custom skills) - **Terminal handoff**: commands that act on the machine or the account rather than the conversation (/design-login, /login, /logout, /permissions, /plugin...) open a Claude terminal tab to run them, since the chat drives the CLI headless - **Inline @mentions**: rich contenteditable input field lets you type @mentions inline without leaving the message composition area - **File rewind**: revert chat context to an earlier file state via SDK checkpointing — useful for undoing unwanted edits mid-session - **Cost tracking**: model name, token count, and USD cost in the status bar - **1M context window**: extended context for larger codebases (API mode only) - **Dynamic model and effort switching**: the model picker is built live from the Claude CLI's own catalog, so newly released models (e.g. Fable 5.1) show up automatically; switch model and effort level (low, medium, high, xhigh) mid-conversation without starting a new session - **Per-conversation model, effort and permission mode**: every tab keeps its own settings, so a pick in one conversation never leaks into the next. The stored values are only the defaults a new tab starts from, changed through each menu's "Use for new conversations" row - **Permission modes**: switch between default, accept edits, plan and bypass permissions from the composer, mid-session - **Premium model tier**: models in the Fable family are flagged in violet with a "Premium" badge, a tag on the tab, and a notice when a new tab inherits one, because the family draws on its own usage limit - **Background tasks drawer**: a collapsible drawer scoped to the current session shows work Claude is running in the background, so you can keep chatting while it finishes - **Artifacts library & Documents tab**: files and snippets Claude generates are saved to a reusable artifact library and also surface in a per-conversation Documents tab for quick access, with a dedicated Artifacts panel listing everything published for the project - **Conversation search**: press Ctrl+F to search across the current conversation transcript - **Pin conversations**: keep important sessions at the top of the list - **Fork sessions**: branch from any message to explore alternative paths; Claude Terminal warns instead of discarding if a queued turn would be lost - **Follow-up suggestions**: context-aware suggestion chips appear after Claude responds to help guide the conversation - **Session recaps**: automatic AI-generated summaries of completed sessions - Type @project to attach README.md and file tree from any project as context - Type **@tab** to share your current terminal session or **@conversation** to reference another chat thread - Type **@context** to inject a context pack or **@prompt** to insert a saved prompt template directly into your message - **Prompt enhancement**: one-click AI rewrite of your message using Haiku for clearer instructions before sending - Interrupt streaming mid-turn, auto-generated tab names via haiku model - Compacting indicator shown during conversation compaction so you know when context is being compressed ### Terminals - Multiple Claude Code terminals per project with tabbed interface - GPU-accelerated rendering via xterm.js + WebGL (DOM fallback) - Switch between terminal and chat mode per tab - Tab drag-and-drop reordering, renaming, desktop notifications - Filter terminals by project - Adaptive ready detection with spinner status - Captured terminal output, so the terminal read tools and MCP tools can actually return what ran ### Navigation - Choose how you browse projects: a project tab bar across the top, or a classic projects column on the side - Asked once in the first-launch setup wizard, and switchable anytime from Settings ### Files - A dedicated Files screen shows every file touched in a session, with per-session diffs rendered GitHub-style - Quickly review what Claude changed without leaving the chat context - Or keep the project tree docked beside the conversation, the way it was before the Files screen ### Accounts - Bind a separate Claude account to each project, with its own isolated credential store - Switch projects without switching accounts by hand, and without one project's login affecting another's - Per-account usage shown in Settings, and a usage-limit switch that carries the conversation over ### Claude Remote Control (claude.ai & mobile) - Put a chat session on [claude.ai/code](https://claude.ai/code) and the Claude mobile app, so you can follow it or drive it from your phone - Decided **per conversation**, never globally: a session joins when you ask for it in that tab, via the footer button or the `/remote-control` command - Read-only mirror or full driving, your choice; prompts, interrupts and permission answers all route back to the desktop - Optional `--rc` in terminal tabs so CLI sessions join too - A **Connectivity → claude.ai** tab lists every shared conversation with a way back to each tab - Honours Claude Code's `disableRemoteControl` managed-settings kill switch, so an org policy can't be lifted from the app ### Claude in Chrome - Let chat sessions drive your browser through the Claude Chrome extension - Adds the `claude-in-chrome` MCP server and its 22 browser tools to the session - Opt-in, and it adopts Claude Code's existing native messaging host instead of overwriting it ### Voice - Dictate messages to the chat input by microphone (Groq transcription) - Verbatim dictation mode with focused-tab routing so your words land in the right conversation - Hands-free session profile for fully voice-driven sessions - Speaks project names the way you'd say them, so @mentions by voice resolve correctly ### Project Management - Organize projects in nested folders with drag-and-drop - Customize each project with colors and emoji icons - Quick Actions toolbar: configurable one-click commands per project (build, test, deploy, custom scripts...) - Built-in file explorer with tree view, multi-select, search, git status indicators, and inline rename; right-click any file to attach it as context in the current chat - Modular project type system (standard, FiveM, webapp, Python, API, Minecraft, Discord bot) - Per-project settings modal ### Git Integration - **Branches**: switch, create, delete with tree view of local/remote branches - **Sync**: pull (rebase), push, merge with conflict detection and resolution - **Changes panel**: view staged/unstaged/untracked files, stage/unstage and commit - **Commit history**: IntelliJ-style commit graph with SVG rendering, branch/author filtering, infinite scroll - **Cherry-pick & revert**: advanced commit operations from history - **Worktree management**: create, switch, and delete Git worktrees with quick-switch badge in the toolbar - **Stash management**: save, apply, pop, and inspect stashes - **History search**: full-text search across commit history - **Discard changes**: quickly discard unstaged edits per file - **Amend commits**: edit the last commit message or staged content before pushing - **AI commit messages**: auto-generate conventional commit messages via GitHub Models API - **Pull Requests**: create and view PRs directly from the app ### GitHub Integration - OAuth Device Flow authentication (secure, no token copy-paste) - **GitHub Enterprise support**: connect to self-hosted GitHub Enterprise instances - **Repository search in clone wizard**: search GitHub repos by name without leaving the app - **CI/CD status pill**: live inline status of the latest workflow run shown directly in the terminal header bar, with a Fix-it button to jump straight to a failing step - View CI/CD workflow runs per repository - View, create, and review pull requests from the app; multi-forge support (GitHub, GitLab) - Token stored securely via keytar (Windows Credential Manager, macOS Keychain, Linux libsecret) ### Control Tower - Real-time overview of all active Claude agents across every project - See what each agent is doing (tools it's running, current status, last activity) - Grid view: one card per open session, grouped per project, with live terminal thumbnails, model badge, and per-project new-session buttons - Filters and sorting: by project, by status, text search, ordered by your last interaction - Focus view: maximize any session inside the panel with a filmstrip of the project's other sessions, editable session titles, and one-click jump to the Claude view - Finished sessions stay highlighted until you've seen them, so completed work never slips by - Interrupt any running session directly from the panel - Reply to AskUserQuestion prompts without switching to the chat tab - MCP tools for agent monitoring and remote interrupt ### Parallel Tasks - Decompose a feature into parallel subtasks and run them simultaneously as separate Claude agents - Each task runs in its own Git worktree and branch, keeping work isolated - Auto mode lets Claude decide the optimal number of parallel tasks - Collapsible task cards with per-task diff viewer and terminal access - Auto-merge agent: Claude reviews and merges completed branches into your main branch - Full run state persisted to disk and restored on app restart ### Session Replay - Browse past Claude Code sessions and replay them step by step - Timeline view shows all prompts, tool calls, and responses in chronological order - Video-player-style scrubber to jump to any point in a session - Q&A cards highlight question-and-answer exchanges for easy review ### Dashboard - Open the selected project directly from the topbar; actions and cached data appear immediately while Git, code statistics and GitHub data load progressively - **Weekly briefing**: both the project page and the overview open on this week's cost, time and commits, your last Claude sessions with a Resume button, and what's waiting (uncommitted files, commits to push or pull, failing CI, open PRs, TODO count), plus a 14-day chart of cost against commits - **Cost tab**: API-equivalent Claude spend by account, project, model and day, for this week, last week, 7/30 days, this month or all time; a weekly-limit card splits a shared account's usage between this machine's share and everyone else's - Three sub-views: **Overview**, **Kanban** and **Timeline** - Overview: current branch, commits ahead/behind, recent commits, contributors - Code statistics: lines of code by language, file count, commit count - Active terminals count - Claude API usage monitoring with auto-refresh - **Project timeline**: every record the app already keeps, merged into one chronological view — commits, Claude sessions, tracked time, workflow runs, parallel runs and artifacts — filterable by period and by kind, so "what happened to this project" is one screen instead of six ### Time Tracking - Automatic session detection per project (15-min idle timeout, sleep/wake detection) - Separate lightweight storage (`timetracking.json`) with monthly archives - View by period: today, this week, this month, custom range - Stats: daily average, longest streak, evolution charts, recent sessions - Midnight rollover and periodic checkpoints ### Hooks - Integrates with Claude Code CLI hooks for real-time activity tracking - One-click install into `~/.claude/settings.json` (non-destructive, preserves user hooks) - Hook types: PreToolUse, PostToolUse, Notification, SessionStart, Stop, DirectoryAdded (fires on `/add-dir`), and more - Event bus with normalized events for session, tool, and subagent tracking - Fallback terminal scraping when hooks are unavailable ### Plugins - Browse and discover plugins from configured marketplaces - Install plugins directly from the app (via Claude CLI) - Add community marketplaces by GitHub URL - Category filtering and search - View plugin details and README ### Skill Marketplace - Search and browse available skills - One-click install and uninstall - **Update checking**: see which installed skills and plugins have new versions available - View skill README and details - Local cache for fast browsing ### Library - Manage reusable **context packs** (documents, snippets, file contents) and **prompt templates** - Inject context packs or prompt templates directly into the chat via @context and @prompt mentions - Insert prompt templates into any terminal with one click from the toolbar - Generate skills and agents in the background using the Agent SDK ### Skills & Agents - Browse and manage Claude Code skills and agents - **Compact cards with a filter**: each card shows the name, the opening line of the description and, for agents, up to four tools as chips; a filter above the list matches name, description and tool names - View SKILL.md and agent configuration files - **Syntax-highlighted editor**: edit skill and agent files with line numbers and full highlight.js code highlighting - Load skills from `~/.claude/skills`, plugins, and bundled resources ### MCP Servers - Configure, start and stop MCP servers - Environment variable configuration - **MCP Registry**: browse and search the public MCP server registry ### Sessions - View Claude Code sessions per project - Browse session history with timestamps and metadata - Pin sessions to the top and rename them inline from the resume dialog - Modernized session resume modal with search and pinned sessions - Sessions show their real conversation title instead of a timestamp, and are searchable by id - **Move a session to another project**: relocate a conversation without losing its history - Custom tab names are locked and no longer get silently overwritten by auto-naming ### Memory & Global Knowledge - Edit global, settings and project-specific CLAUDE.md files - Template insertion for common patterns - **Global Knowledge**: a cross-project store of facts, conventions and preferences, one markdown entry each, available in every session - Pin, enable/disable and search entries; enabled ones are synced into a marked block in `~/.claude/CLAUDE.md`, with a preview of the block before it's written - MCP tools (`knowledge_list`, `knowledge_write`, `knowledge_search`...) so Claude can read and write them itself ### Kanban - A kanban board per project, with custom columns, drag-and-drop between them, and archiving - Priority levels, due dates, tags and assignees on cards - Filter, search and per-column stats - Full MCP tool set, so Claude can create and move cards while it works, and a `kanban_create_card` workflow node ### Error Log - Centralized log of every error the app catches: IPC failures, service errors, uncaught exceptions and rejections - Filter by level and by domain, with automatic pattern detection to group repeated failures - **AI diagnosis** of an entry, and export for a bug report - `critical` means the app actually broke (an uncaught exception or rejection), not merely that something logged - MCP tools so Claude can read the log while debugging ### Settings - Accent color theming (preset palettes + custom hex) - Terminal font size (10 to 24 px), applied live to open terminals - Per-agent and per-tool color customization for chat tool cards - Language: English, French, Spanish, Indonesian, and Simplified Chinese with auto-detection - Editor integration: VS Code, Cursor, WebStorm, IntelliJ IDEA - Customizable keyboard shortcuts - Desktop notification preferences - Close behavior (ask, minimize to tray, or quit) - Launch at startup toggle - Auto-updates with background download and install banner, followed by a **What's new** panel on the next start that leads with anything that moved and then gives the full release notes - **Discord Rich Presence**: show the project you're working on in your Discord status (VSCode-style), with an option to hide the project name for privacy; toggle on/off in Settings - **Telemetry is opt-in and off by default**: nothing anonymous or otherwise is collected unless you turn it on in Settings ### Workflow Automation - **Automations**: a simple, no-graph mode for common tasks — describe what Claude should do and when in a plain form, no node editor or cron syntax required, with six starter presets - Automations can trigger on events instead of a schedule: git activity, a file change, a command finishing, a Claude session ending, Claude replying (with an optional text filter), or opening a project — each event watches its own chosen project, independent of where Claude runs - Visual node-based workflow editor with custom canvas engine (Blueprint-style) - **31 node types**: shell, git, HTTP, Claude (prompt/agent/skill), condition, loop, transform, switch, subworkflow, database, file, project, time, variable, get variable, trigger, code (run a JavaScript snippet), template (build strings from variables), terminal, quick action, notify, Discord notify, log, wait, retry, error handler, webhook, parallel spawn, session recap, kanban card, workspace doc - Typed data pins with visual data flow between nodes - AI assistant panel for real-time graph editing and node creation - Undo/redo, copy/paste, snap-to-grid, minimap, comments - Run history with live loop progress and step output inspection - Workflow community hub for sharing and importing workflows - **12 trigger types**: manual, cron, hook, webhook, on-workflow, chat message, file change, git event, project opened, terminal exit code, Claude session start, Claude session end - MCP tools for full workflow control from Claude Code ### Connectivity (Remote & Cloud) - Database secrets stay in the OS keychain. MCP environment variables and authorization headers remain local to each machine during sync. - Imports and clones reject existing projects, prepare content in temporary directories, and enforce archive extraction limits. - Unified **Connectivity tab** combining local remote access and cloud sync in one place - Self-hosted Docker relay server for remote project access - Project upload and auto-sync with file watcher and conflict resolution - **Per-entity sync toggles**: choose exactly which data syncs (projects, settings, skills, agents, MCP configs, keybindings, memory, hooks, archives) - **Session resume from cloud**: pick up any session from another machine - **Cross-machine notifications**: get notified on your desktop when a cloud session finishes - Headless Claude sessions running in a personal cloud instance (one user per container and dedicated volumes); disable `CLOUD_ENABLED` for a multi-user relay/sync without agent execution - Diff modal for local vs cloud file comparison - User profiles and session management - Automated install script with Docker, reverse proxy, and SSL setup ### Remote SSH Projects - Open a project that lives on another machine over SSH, IntelliJ Gateway style: the app stays the UI, while terminals, Claude chat, git and files run on the host - Uses the system OpenSSH client, so `~/.ssh/config`, keys, `ssh-agent`, ProxyJump and agent forwarding work exactly as in a terminal. The app stores no password and no key: a password is typed into OpenSSH's own prompt, never saved - **Open Remote Project**: pick a saved host profile, browse its folders, then open one, create one, `git init` it or clone a repository into it - A host badge on every remote project shows its connection state. A dropped connection reconnects on its own, and terminal and chat tabs pick up where they were (inside tmux if you enable it) - Claude Code runs on the host (it has to be installed there, and the app tells you when it is not), and session history is read from the host - The Git panel, dashboard, file explorer, Files screen, file tabs and diffs work on the host. VS Code, Cursor and Windsurf open remote files through their Remote-SSH extension - Nothing is installed on the host: no agent, no daemon, just one `sh` session per connection - Features that only make sense locally (project-type dashboards, parallel tasks, workflow nodes that run on this machine, account binding, cloud upload, Open in Explorer) are shown disabled, with the reason as a tooltip ### Database Panel - Multi-driver support: SQLite, MySQL, MariaDB, PostgreSQL, MongoDB - **Redis browser**: tree-view key explorer with type-aware value inspection - Split-pane data browser with inline editing - SQL query editor with syntax highlighting, templates, and multi-statement execution - Insert/delete rows, search filter - Custom database picker for quick connection switching - Connection pooling with idle eviction ### Workspace - **Cross-project** knowledge hubs: group related projects together with a shared knowledge base, so context that spans several repos has somewhere to live - Markdown KB documents with tags and full-text search across the whole workspace - **Concept links**: record relationships between entities (`Web App depends-on API Service`) and see them as a graph - **Advisor chat**: ask questions about your workspace and get answers based on your knowledge base content - **@workspace mention**: type @workspace in chat to inject your workspace knowledge base as context - MCP tools for reading and writing workspace content from Claude Code ### MCP Server (claude-terminal) A unified MCP server, auto-configured by the app, exposing Claude Terminal itself to Claude Code. **23 tool modules**, loaded dynamically — dropping a new `.js` file into `resources/mcp-servers/tools/` registers it. | Module | What it gives Claude | | --- | --- | | `projects` | List projects, project info, TODO/FIXME scanning | | `timetracking` | Today, this week, per-project and summary stats | | `sessions` | List, replay, cross-project keyword search, session recap | | `workflow` | Create, edit, run, cancel, diagnose, run logs, variables | | `automation` | List, view, create, update, enable/disable, delete Automations | | `parallel` | Start, list, inspect, cancel, merge and clean up parallel runs | | `kanban` | Columns and cards: add, move, update, filter, stats | | `knowledge` | Cross-project facts: list, get, search, write, delete | | `workspace` | List, info, read/write KB docs, search, concept links | | `artifacts` | List, get, search, versions, stats, delete | | `database` | Query, list/describe tables, full schema, stats, export | | `terminal` | Create, list, send a command, read output, close | | `tabs` | Tab orchestration with permission control | | `sidebar` | `ui_navigate` and `ui_state` to drive and read the visible panel | | `control-tower` | List active agents, interrupt one remotely | | `errorlog` | Entries, stats, patterns, export, clear | | `usage` | Read and refresh Claude usage | | `settings` | Get and set app settings | | `marketplace` / `plugins` | Search, install and uninstall skills and plugins | | `webapp` / `fivem` / `discord` | Per-project-type tools | A specialized `database-mcp-server.js` is also shipped for database-only use. ### WebApp Preview - Live preview with Chromium webview (replaces iframe) - Visual feedback with multi-pin annotations per page - Responsive breakpoint checker - Auto-detect visual problems scanner - Ruler spacing measurement tool - Accessibility audit panel with axe-core ### Remote Control (self-hosted PWA) - Mobile PWA for remote control from phone or browser, served by the app itself - Cloud relay for access outside your local network (via self-hosted server) - Real-time session monitoring, chat interaction, and project switching - 6-digit PIN authentication with QR code - Fully translated, ships with its own content-security-policy, and its transcript survives more than one turn > [!NOTE] > This is the **self-hosted** remote, distinct from [Claude Remote Control](#claude-remote-control-claudeai--mobile), which puts a session on claude.ai and the official Claude mobile app. You can use either, or both. ### Sidebar Customization - Drag and drop sidebar tabs to reorder them to your workflow - Pin frequently-used tabs; less-used tabs collapse into a More overflow menu - Customize via a modal or directly by dragging ### Command Palette - Unified command palette (Ctrl+P) with fuzzy search across projects, commands, and quick actions - Smart launcher with shimmer skeleton loading and match highlighting - Navigate to any panel or trigger any action without touching the mouse ### Auto CLAUDE.md Updates - After a session ends, Claude analyzes the conversation and proposes relevant additions to your project's CLAUDE.md - Review and accept suggestions in a diff-style modal before they're applied ### Other - **Session restore**: save and restore full workspace sessions across restarts - **File viewers**: integrated .md viewer, PDF viewer, and 3D model viewer (.glb, .gltf, .obj) in the terminal panel - **Dashboard insights**: project health badges and commit heatmap - **File explorer watcher**: automatic tree updates on filesystem changes - **Tab context menus**: right-click on any tab for quick actions - **Window state persistence**: remember position, size, and maximized state - First-launch setup wizard with optional hooks installation - System tray integration with accent-colored icon - Custom toast notifications with stacking, click-through transparency, and action buttons - Global shortcuts (`Ctrl+Shift+P` / `Cmd+Shift+P` quick picker, `Ctrl+Shift+T` / `Cmd+Shift+T` new terminal) - Single instance lock - Custom NSIS installer with branded images (Windows), DMG (macOS), AppImage (Linux), Snapcraft, Flatpak - FiveM server management (launch, integrated console, resource scanning, resource creator wizard) - Minecraft project type with Java plugin generator and platform-aware launch scripts - Web app management with framework auto-detection and scaffold templates - Python project detection (version, venv, dependencies, entry point) - API project type with integrated route tester, variables, and console - **Discord bot project type**: visual embed and component builder with live preview ## Usage ```bash # Install dependencies once npm install # Build renderer and run the app npm start # Run with DevTools open npm run start:dev # Build renderer in watch mode (for development) npm run watch ``` > [!TIP] > If you modify files under `src/renderer/`, `src/project-types/`, or `renderer.js`, run `npm run build:renderer` before packaging or opening a PR. ## Building ```bash # Build for current platform npm run build # Build for a specific platform npm run build:win # Windows (NSIS installer) npm run build:mac # macOS (DMG) npm run build:linux # Linux (AppImage) ``` The installer will be generated in the `build/` directory. ## Testing ```bash # Run the test suite (149 Jest suites, jsdom) npm test # Watch tests during development npm run test:watch # ESLint over main, renderer, shared, MCP servers and scripts npm run lint npm run lint:fix # Fail if CLAUDE.md has drifted from the tree it describes npm run check:docs # Playwright smoke test against the real Electron app npm run test:e2e ``` CI runs three jobs on every push and PR: `lint` (fast, fails first), `test` (Node 18 and 20 across Windows, Linux and macOS) and `e2e` (Ubuntu under `xvfb-run`). The E2E job is **blocking**: it opens the real app, walks every sidebar tab, and fails on any renderer console error or main-process crash. `npm run test:e2e` is kept out of `npm test` because it needs a display and a built renderer bundle. Running it locally also needs the native modules built against Electron's ABI (`npm run postinstall`). --- ## Keyboard Shortcuts | Shortcut | Action | | --- | --- | | `Ctrl+Shift+P` | Quick project picker (global) | | `Ctrl+Shift+T` | New terminal in current project (global) | | `Ctrl+Shift+W` | New worktree (global) | | `Ctrl+Shift+E` | Sessions panel | | `Ctrl+T` | Create terminal | | `Ctrl+W` | Close terminal | | `Ctrl+N` | New project | | `Ctrl+E` | Toggle file explorer | | `Ctrl+P` | Quick picker | | `Ctrl+,` | Settings | | `Ctrl+←` / `Ctrl+→` | Switch terminal (left/right) | | `Ctrl+↑` / `Ctrl+↓` | Switch project (up/down) | | `Ctrl+F` | Search the current conversation transcript | | `Escape` | Close dialogs | Shortcuts are customizable in Settings. --- ## Architecture Claude Terminal is plain CommonJS JavaScript with JSDoc types. No TypeScript, no frontend framework: the renderer is bundled by esbuild into ESM with code splitting. ``` claude-terminal/ ├── main.js # Electron entry point, lifecycle, single-instance lock ├── renderer.js # Renderer entry (bundled to dist/renderer.bundle.js) ├── index.html # Main window UI ├── notification.html # Custom toast notification window ├── quick-picker.html # Command palette window ├── setup-wizard.html # First-launch wizard ├── styles/ # 30 modular CSS files, @imported by index.css ├── src/ │ ├── main/ # ── Main process (Node.js) ── │ │ ├── preload.js # Context bridge (window.electron_api) │ │ ├── preload-quickpicker.js # Preload for the quick picker window │ │ ├── ipc/ # 34 IPC files, 322 handlers │ │ │ ├── index.js # Orchestrator, registers every handler │ │ │ ├── git.ipc.js # 69 handlers, the largest │ │ │ ├── chat.ipc.js # Agent SDK streaming sessions │ │ │ ├── github.ipc.js # OAuth device flow, PRs, CI runs │ │ │ └── ... # terminal, dialog, workflow, remote, database, │ │ │ # accounts, knowledge, artifacts, workspace, │ │ │ # parallel, cloud-*, errorLog, voice, chrome... │ │ ├── services/ # 35 services │ │ │ ├── ChatService.js # Claude Agent SDK bridge │ │ │ ├── TerminalService.js # node-pty, adaptive output batching │ │ │ ├── AccountManager.js # Multiple Claude accounts │ │ │ ├── RemoteControlService.js # claude.ai / mobile bridge │ │ │ ├── ChromeBridgeService.js # Claude in Chrome │ │ │ ├── WorkflowService.js # + Runner, Scheduler, Storage │ │ │ ├── ParallelTaskService.js # Worktree-per-subtask orchestration │ │ │ ├── KnowledgeService.js # Global knowledge base │ │ │ ├── ErrorLogService.js # Centralized error collection │ │ │ └── ... │ │ ├── windows/ # MainWindow, QuickPicker, SetupWizard, Tray, Notification │ │ ├── utils/ # paths, git, shell, fileLock, claudeBridge, sdkCli... │ │ └── workflow-nodes/ # 31 node types, one *.node.js each, auto-registered │ ├── renderer/ # ── Renderer process (Browser) ── │ │ ├── index.js # Module loader & init sequence │ │ ├── core/ # DI container, BaseService/Component/Panel, ApiProvider │ │ ├── state/ # 17 observable state modules (State.js base class) │ │ ├── services/ # 28 services │ │ │ ├── MarkdownRenderer.js # + markdown/ subsystem (configure, streaming, │ │ │ │ # postProcess, interactivity, blocks) │ │ │ ├── WorkflowGraphEngine.js # Custom canvas node editor (no LiteGraph) │ │ │ ├── DiffRenderer.js # GitHub-style unified diffs │ │ │ ├── ProjectTimeline.js # Merges six record sets into one timeline │ │ │ ├── VoiceCaptureService.js │ │ │ └── mention-sources/ # Pluggable @mention and palette sources │ │ ├── ui/ │ │ │ ├── components/ # 18 components (ChatView, TerminalManager, │ │ │ │ # FileExplorer, ProjectList, ProjectBar, Modal...) │ │ │ ├── panels/ # 25 panels (Settings, GitChanges, ControlTower, │ │ │ │ # ParallelTask, Workspace, Database, Kanban, │ │ │ │ # ErrorLog, Files, Artifacts, Connectivity...) │ │ │ └── themes/ # terminal-themes.js │ │ ├── features/ # KeyboardShortcuts, QuickPicker, DragDrop │ │ ├── events/ # ClaudeEventBus + Hooks / Scraping providers │ │ ├── workflow-fields/ # 13 custom UI fields for workflow nodes │ │ ├── workflow-triggers/ # 12 trigger types (definition + configurator) │ │ ├── viewers/ # PDF viewer, 3D viewer (three.js) — ESM, lazy-loaded │ │ ├── i18n/locales/ # en, fr, es, id, zh-CN (3641 keys each, kept in sync) │ │ └── utils/ # dom, color, format, paths, fileIcons, syntaxHighlight │ ├── shared/ # 12 modules shared by main, renderer and the MCP server │ │ ├── artifact-store.js # Used verbatim by the MCP server process │ │ ├── model-options.js # Premium tier definition │ │ ├── permission-modes.js # SDK modes <-> legacy executionMode spellings │ │ └── simple-task.js # Compiles an Automation into a workflow graph │ └── project-types/ # Pluggable type system (base-type.js + registry.js) │ ├── general/ api/ webapp/ python/ minecraft/ fivem/ discord/ │ └── ... # each: main/ service+ipc, renderer/ dashboard+wizard, i18n/ ├── resources/ │ ├── mcp-servers/ # Shipped MCP servers │ │ ├── claude-terminal-mcp.js # Unified server │ │ ├── database-mcp-server.js # Database-only server │ │ └── tools/ # 23 auto-registered tool modules │ ├── bundled-skills/ # create-skill, create-agents │ └── hooks/ # Hook handler script, POSTs events over HTTP ├── remote-ui/ # Mobile PWA, bundled as extraResources ├── tests/ # 149 Jest suites + a Playwright E2E smoke test ├── scripts/build-renderer.js # esbuild bundler └── website/ # Landing page, changelog, legal ``` > `cloud/` (the relay) and `hub-worker/` (a Cloudflare Worker) are separate packages > with their own `package.json`. Neither is bundled into the desktop app. ### Boundaries The main/renderer split is enforced by ESLint, not just by convention: - The renderer never gets `child_process`, `fs`, `net` or `electron` directly. It talks to main through `window.electron_api` only. **`child_process` is deliberately never exposed** — the renderer displays model-authored markdown, so a bridge to process spawning would turn any HTML injection into code execution. - `contextIsolation: true` and `nodeIntegration: false` in all five windows. - The CSP in `index.html` has no `'unsafe-inline'`, so HTML injected into the chat cannot execute script. All user-rendered markdown goes through `dompurify`. If a boundary rule fires, the fix is a new IPC handler, not an `eslint-disable`. --- ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. For translation contributions, see the [Translations (i18n) section](CONTRIBUTING.md#translations-i18n). To contribute translations, see our [i18n guide](.github/i18n-coverage.md). ## Security See [SECURITY.md](SECURITY.md) for reporting vulnerabilities. ## License [GPL-3.0](LICENSE) See [runtime, data protection and recovery notes](RUNTIME_RELIABILITY.md) for deployment constraints and validation commands.