ChatCMD

Turn web-based AI into a local worker through the Model Context Protocol.

[!CAUTION] If the pre-built versions from GitHub fail to open, please download the entire project repository and open it using https://www.jetbrains.com/rust/. The issue may stem from the GitHub Actions compiler malfunctioning on certain machines.

ChatCMD is a self-hosted bridge between MCP-compatible AI clients and your computer. It combines a Rust server, a permission-scoped machine runtime, SQLite persistence, a React management console, and an optional Chromium extension for working with ChatGPT in the browser.

The core application runs on your machine. It has no ChatCMD account, subscription, payment, quota, or hosted authentication dependency. Optional features can still make outbound connections—for example to ChatGPT, a Git repository used to install a skill, a Google Font, or a tunnel address that you configure.

Download the latest release

View release notes and SHA-256 checksums.

The automated macOS packages are ad-hoc signed and are not Apple-notarized.

[!CAUTION] ChatCMD can expose terminals, files, Git repositories, and local processes to an AI client. Start with the smallest tool allowlist, keep approval mode enabled, review every public endpoint, and never publish a tokenized MCP URL.

Why ChatCMD

• Local-first runtime: the server, management UI, task history, settings, and SQLite database stay on your device.
• MCP access profiles: create multiple plugin profiles, grant tools per profile, disable access without deleting the profile, and rotate secret URLs.
• Real machine tools: persistent PTY terminals, bounded file operations, Git commands, process inspection, task artifacts, and skill discovery.
• Live supervision: follow progress, tool calls, file changes, terminals, sub-agents, approvals, and final responses in real time.
• ChatGPT web bridge: optionally send, continue, queue, and stop ChatGPT browser conversations through a Manifest V3 extension.
• Cross-platform codebase: Windows, macOS, and Linux development/runtime support; release packaging scripts are included for Windows and macOS.
• No vendor lock-in: the server uses MCP Streamable HTTP and a documented local API rather than a proprietary hosted control plane.

Features

MCP and permissions

• Tokenized Streamable HTTP endpoints in the form http://127.0.0.1:8080/mcp/.
• Separate access profiles for different AI clients or jobs.
• Per-tool allowlists, grouped permission controls, and a non-destructive preset.
• Enable, disable, edit, delete, and rotate access profiles.
• Origin and host validation, one-time local profile secrets hashed at rest, URL-token redaction in built-in HTTP traces, and rejection of query-string credentials.
• User-managed public domains, reverse proxies, IP addresses, and tunnels with a connectivity test before they are saved.

Local tool catalog

The authoritative method-by-method reference is in docs/mcp_method.md.

Sub-Agent orchestration

Sub-Agents let a coordinator split a larger task into smaller delegated jobs that can run independently and, when useful, in parallel. Each Sub-Agent is represented by its own child task, while remaining attached to the parent task and root turn so ChatCMD can supervise the entire delegation tree from one workflow.

How it works:

1. Delegate a focused job. The parent creates or reuses a child through agent_subagent_start, providing a name, request, and optional constraints such as allowed files, allowed effects, dependencies, acceptance criteria, project context, and a bounded safe-read approval grant.
2. Reserve and claim a child task. ChatCMD creates a deterministic child task and Sub-Agent run, prevents duplicate workers for the same delegation, and enforces the global Sub-Agent concurrency limit configured under Settings > Execution.
3. Run with the same safety boundaries. Delegation can only narrow server policy. A child does not receive unrestricted tool access: normal tool authorization and approval rules still apply. An optional approvalGrant can inherit only a bounded portion of an already approved parent safe-read grant; Git, process, write, and agent-lifecycle operations continue through their normal approval path.
4. Support nested delegation without deadlocking the tree. A child can create its own Sub-Agent, so parent → child → grandchild workflows are supported. All descendants share the same global concurrency budget; when a nested child cannot acquire a slot, it must continue that delegated work locally instead of waiting indefinitely.
5. Supervise lifecycle and failures. Sub-Agent runs move through pending/running/terminal states, publish live status to the task timeline, refresh leases with heartbeats, and are cleaned up by watchdog logic if a worker restarts, stops heartbeating, or exceeds its runtime deadline. The ChatGPT browser extension can also act as a fallback worker when native delegation is unavailable.
6. Return durable results to the coordinator. agent_subagent_wait waits on the whole descendant tree and reads persisted final reports from SQLite, including grandchildren. Reports carry the final content plus normalized work outcome, blockers, limitations, child verification metadata, and evidence references. Lifecycle completion is kept separate from proof that the delegated objective actually succeeded, so the parent remains responsible for integrating and verifying child work before finalizing.

This makes Sub-Agents useful for parallel code inspection, splitting research across components, delegating focused implementation or review work, and building multi-level agent workflows without losing task history, permission boundaries, or final-result traceability. See docs/subagent-reports.md and docs/subagent-approval-grants.md for the detailed report and permission model.

Follow-up messages: queue or send immediately

While ChatGPT is still working, ChatCMD lets you prepare the next instruction without waiting for the current response to finish. The task composer exposes two different delivery modes:

• Queue another message: adds the message to the task’s persistent ChatGPT queue. ChatCMD keeps it waiting until the current conversation is idle, the browser bridge is connected, the exact ChatGPT tab is open, and the UI is ready for another prompt; it then sends the first queued message automatically.
• Send immediate message: marks the message as immediate, allowing the AI to receive it on its next MCP call in the same conversation instead of waiting for the normal browser-send window. If the active turn ends before that happens, the message remains available as a normal queued follow-up rather than being lost.

Queued follow-ups are manageable directly from the task UI: messages can be reordered, edited, deleted, promoted from queued to immediate, or demoted back to normal queue mode. Realtime queue events keep the panel synchronized when messages are consumed, and automatic sending is paused while compact/resume, bridge synchronization, another send, or an edit is in progress.

This is useful when you already know the next step: you can line up several follow-up instructions for sequential execution, or inject a higher-priority instruction into the current MCP-driven workflow without manually waiting for each ChatGPT turn to become ready.

Compact & resume now

Long ChatGPT conversations eventually become harder to continue reliably as their usable context fills up. Compact & resume now creates a durable handoff from the current ChatGPT conversation into a fresh one while keeping the same ChatCMD task, project, permissions, timeline, queued messages, and local task identity.

How it works:

1. Confirm before anything is sent. Selecting Compact & resume now opens a confirmation dialog. The optional Continue work after compaction checkbox starts unchecked on every opening; leave it unchecked to transfer context only, or opt in to automatically continue the working request after the replacement chat has been attached.
2. Freeze the task at a safe boundary. ChatCMD fences new local MCP operations for the compacting task, waits for already-admitted operations to finish, and stops the current ChatGPT generation before asking the source conversation to produce its handoff. Existing drafts and queued follow-up messages are preserved rather than overwritten.
3. Write and persist the handoff first. The source ChatGPT conversation receives a structured handoff request covering requirements, corrections, completed versus planned work, bug/fix/evidence chains, delegated work, environment details, blockers, and remaining tasks. The resulting public answer is saved durably in SQLite before ChatCMD is allowed to open or commit a replacement conversation.
4. Bootstrap a fresh ChatGPT conversation. ChatCMD opens a new conversation and sends a no-tools resume/bootstrap message containing the saved handoff. It waits until the destination’s real canonical ChatGPT conversation identity and resume marker are observed before changing the task’s active conversation binding.
5. Keep the same ChatCMD task. Completion archives the old ChatGPT URL and conversation metadata, retires obsolete bridge bindings, and points the existing task at the new conversation. The task ID, title, project folder, permission state, timeline, drafts, and queued messages stay with the original task instead of creating a second ChatCMD task.
6. Optionally continue the work. Only when the saved opt-in is enabled does ChatCMD enqueue the deterministic post-handoff continuation request. Repeated resume calls are idempotent, so recovery or retries do not create duplicate working messages.
7. Retire the source tab conservatively. After the new conversation is safely attached, ChatCMD attempts to close only the exact recorded source tab. If tab identity, draft state, generation state, or dispatch ownership is ambiguous, it leaves the tab open rather than risking closure of the wrong conversation.

The UI shows live phases for preparing, writing the handoff, saving it, and opening the new chat. Compact state is persisted independently of the browser worker, so extension reloads, closed/reopened tabs, delayed Send availability, or lost responses can be reconciled from SQLite plus browser dispatch metadata instead of blindly repeating prompts. Completed compactions remain available in Context compaction history, including references to the archived source and replacement conversation.

Compact & resume is intentionally fail-closed: if ChatCMD cannot prove which prompt was sent, which conversation produced the handoff, or which destination owns the resume marker, it pauses with a recoverable state instead of silently dropping context or binding the task to the wrong chat. See docs/COMPACT_RESUME.md for the full persistence, identity, recovery, and dispatch model.

Management console

• Runtime dashboard for app, database, MCP listener, task, terminal, approval, and client health.
• Project-aware task rail with search, pagination, rename, delete, unread counters, and workspace grouping.
• Rich task timeline with Markdown, tool output, syntax highlighting, file-change summaries, side-by-side diffs, sub-agent status, and stop controls.
• Conversation, activity, and plan-question approval queues.
• Interactive xterm.js terminal views with live output, input, resize, process ID, CPU, and memory information.
• Skill discovery, enable/disable controls, configurable skill options, GitHub repository preview, installation, and removal.
• English and Vietnamese UI, light/dark/system themes, configurable Google Fonts, task font scaling, and event sounds.
• SQLite diagnostics, application logs, extension logs, configurable data retention, and selective user-data cleanup.
• Windows/macOS system tray behavior and an optional elevated restart flow.

ChatGPT browser bridge

The optional chatgpt-extension/ package can use an already signed-in chatgpt.com tab to:

• start or continue a browser conversation from ChatCMD;
• choose a visible ChatGPT model label;
• queue, reorder, edit, send immediately, or delete follow-up messages;
• stop an active generation;
• relay final responses and conversation identity back to the local task;
• show local conversation, tool, and plan-question approvals in ChatGPT;
• provide a browser fallback for sub-agent work.

This extension is an unofficial DOM bridge, not the OpenAI API. ChatGPT UI changes may require selector updates. See chatgpt-extension/README.md for its security model and limitations.

ChatCMD is an independent project and is not affiliated with or endorsed by OpenAI, ChatGPT, Cloudflare, or other third-party service providers. Their names and trademarks belong to their respective owners, and use of their services remains subject to their terms.

Architecture

flowchart LR
    AI["MCP client / web AI"] -->|"tokenized MCP URL"| MCP["Rust MCP server"]
    GPT["ChatGPT tab"]  EXT["Optional browser extension"]
    EXT  API["Encrypted local API + WebSocket"]
    UI["React management console"]  API
    MCP --> RT["Bounded local runtime"]
    API --> RT
    RT --> OS["PTY · files · Git · processes · skills"]
    MCP --> DB[("SQLite")]
    API --> DB

For component boundaries, data flow, and security assumptions, read docs/ARCHITECTURE.md.

Requirements

• Rust 1.85 or newer with Cargo.
• Node.js 20.19 or newer, or 22.12 or newer, and npm (matching the checked-in Vite engine requirement).
• Git.
• A supported local shell: PowerShell or cmd.exe on Windows; bash or zsh on macOS/Linux.
• Platform build tools:
  • Windows: Visual Studio Build Tools with the MSVC C++ workload.
  • macOS: Xcode Command Line Tools.
  • Linux: a C/C++ toolchain and the platform packages required by winit/tray-icon dependencies when building desktop targets.

Quick start from source

git clone https://github.com/int04/ChatCmd.git
cd ChatCmd/web
npm ci
npm run build
cd ..
cargo run

Open . The first start creates and migrates the local SQLite database automatically.

For frontend hot reload, run the backend and Vite separately:

# Terminal 1, repository root
cargo run

# Terminal 2
cd web
npm ci
npm run dev

Then open . Vite proxies /api and /ws to the Rust server on port 8080.

Connect an MCP client

1. Open Plugin list in ChatCMD and select Create new Plugin connection.
2. Give the profile a recognizable name.
3. Select only the tool groups required for that client, then save the profile.
4. For a local MCP client, choose Create new access code from the profile menu and save the one-time endpoint immediately.
5. Add that URL as a Streamable HTTP MCP server in the client. No Authorization header is required; the secret is the final URL path segment.

To connect a web-hosted AI through your own public endpoint, follow docs/PLUGIN_SETUP.md. It covers tunnel/reverse-proxy setup, the ChatGPT developer-mode flow, and installation of the optional browser extension.

Configuration

Default database locations:

• Windows: %LOCALAPPDATA%\ChatCmdClient\data\chatcmd.db
• macOS: ~/Library/Application Support/ChatCmdClient/chatcmd.db
• Linux: $XDG_DATA_HOME/chatcmd-client/chatcmd.db, or ~/.local/share/chatcmd-client/chatcmd.db

Startup is idempotent. After a restart, stale running tasks and terminal sessions are marked interrupted.

Build release artifacts

Create a standalone binary with the frontend embedded:

cd web
npm ci
npm run build
cd ..
cargo build --release --features embedded-web

Maintainers can use the packaging scripts:

# Windows x64 and x86
.\scripts\build-windows.ps1 -Version 0.1.0

# macOS Apple Silicon and Intel
CHATCMD_BUILD_VERSION=0.1.0 ./scripts/build-macos.sh

The macOS script supports MACOS_SIGN_IDENTITY and MACOS_NOTARY_PROFILE. Full release instructions are in docs/RELEASING.md.

To publish all four packages, open Actions → Build desktop release → Run workflow on GitHub and select main. The workflow runs only when started manually, generates a yy.MM.dd.HHmm version, and updates the repository’s latest release; pushes and pull requests do not trigger it.

Verify a change

cargo fmt --all -- --check
cargo check --workspace --all-targets
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

cd web
npm ci
npm run lint
npm test -- --run
npm run build

cd ../chatgpt-extension
node --test content-chatgpt.test.cjs

See docs/DEVELOPMENT.md for the contributor workflow and narrower test commands.

Screenshots

Security and privacy

• Treat every MCP URL as a password. The full tokenized URL can grant the profile’s permissions to anyone who has it.
• Local profile secrets are stored as hashes. Public plugin-link tokens are stored in the local SQLite database in recoverable plaintext so ChatCMD can copy the same link again; protect the database with operating-system account and disk controls.
• Prefer loopback binding and an authenticated, HTTPS tunnel or reverse proxy for remote access.
• The local management API requires a trusted caller marker and encrypts JSON bodies; the WebSocket uses an ephemeral ECDH-derived AES-GCM session. This is defense in depth, not protection from the owner of a compromised browser or machine.
• The extension has no cookie permission and does not read or write ChatGPT login tokens, but it can interact with the signed-in ChatGPT page through its DOM.
• Review SECURITY.md before reporting a vulnerability. Do not place secrets or private data in a public issue.

Documentation

• Documentation index
• Plugin and ChatGPT setup
• Architecture
• Development guide
• Open-source publication checklist
• MCP method reference
• Troubleshooting
• Encryption protocol
• Diagnostic logs
• Release guide

Contributing

Contributions are welcome. Read CONTRIBUTING.md, the Code of Conduct, and GOVERNANCE.md before opening a pull request. Use SUPPORT.md to choose the right support channel.

License

ChatCMD is available under the MIT License. You may use, copy, modify, distribute, sublicense, and sell copies, including as part of commercial products, subject to the license notice and warranty disclaimer.

Third-party dependencies, services, trademarks, and bundled media remain subject to their own licenses and terms.

Copyright © 2026 Nghia Duc and ChatCMD contributors.