qiming/qimingclaw

QimingClaw

English | 简体中文

Multi-engine AI assistant desktop client based on ACP (Agent Client Protocol), supporting any ACP-compatible Agent engine with cross-platform local AI Agent execution capabilities.

Core Features

Multi-Engine Support

QimingClaw uses ACP (Agent Client Protocol) to communicate with Agent engines, supporting any ACP-compatible Agent:

Engine	Description
Claude Code	Anthropic's official CLI Agent, recommended ⭐
Codex CLI	OpenAI's code Agent
Gemini CLI	Google's AI Agent
GitHub Copilot	GitHub's AI coding assistant
Cline	Open-source autonomous coding Agent
Cursor	Cursor IDE's Agent capability
Goose	Block's open-source AI Agent
Qwen Code	Alibaba's Qwen code Agent
Junie	JetBrains' AI Agent
OpenCode	Open-source code Agent
QimingCode	Agent engine based on OpenCode
More...	View full list

ACP Protocol: Agent Client Protocol standardizes communication between code editors/IDEs and AI coding agents. Similar to how LSP works for language services, ACP lets you connect any ACP-compatible Agent to any supporting client.

• Isolated engine execution with independent environment configuration
• Dynamic engine switching without app restart
• Avoid vendor lock-in, choose your Agent freely

Cross-Platform Clients

• Electron Client - Desktop client based on Electron + React

MCP Protocol Support

• Dynamic MCP server management
• Multi-protocol support (stdio, SSE, Streamable HTTP)
• Resilient connection with automatic reconnection

Other Features

• Persistent Storage - SQLite local storage
• System Tray - Background operation with quick actions

Project Architecture

qiming-agent-client/
├── crates/
│   ├── agent-electron-client/   # Electron client (primary development)
│   ├── qiming-mcp-stdio-proxy/   # MCP protocol aggregation proxy
│   ├── agent-gpui-client/       # GPUI client (experimental)
│   ├── agent-server-admin/      # Admin API service
│   ├── agent-protocol/          # Communication protocol definitions
│   ├── system-permissions/      # System permission management
│   └── qiming-agent-core/        # Core logic (Rust)
└── vendors/                     # Third-party dependencies

Quick Start

Electron Client

# Option 1: Using Makefile (recommended, run from project root)
make electron-dev     # Development mode
make electron-build   # Build
make electron-dist    # Package

# Option 2: Using npm commands in the crate directory
cd crates/agent-electron-client

# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Package
npm run dist:mac      # macOS
npm run dist:win      # Windows
npm run dist:linux    # Linux

MCP Proxy Service

cd crates/qiming-mcp-stdio-proxy

# Install dependencies
npm install

# Build
npm run build

# Run (stdio aggregation mode)
qiming-mcp-stdio-proxy --config '{"mcpServers":{...}}'

# Run (protocol conversion mode)
qiming-mcp-stdio-proxy convert http://remote-mcp-server/sse

# Run (persistent bridge mode)
qiming-mcp-stdio-proxy proxy --port 18099 --config '{"mcpServers":{...}}'

Platform Support

Platform	Architecture	Status
macOS	arm64, x86_64	✅
Windows	x86_64, arm64	✅
Linux	x86_64, arm64	✅

Electron Client Details

Tech Stack

• Main Process: Electron + TypeScript
• Renderer Process: React 18 + Ant Design
• Storage: SQLite (better-sqlite3)
• Build: Vite + electron-builder

Core Services

Service	Description
Unified Agent	Unified ACP engine management
Engine Manager	Engine lifecycle management
MCP	MCP server management
Dependencies	Package management
Permissions	Permission control

Data Storage

~/.qimingclaw/
├── engines/           # Agent engines
├── workspaces/        # Session workspaces
├── node_modules/      # Local npm packages
│   ├── .bin/         # Executables
│   └── mcp-servers/  # MCP servers
├── bin/               # App binaries
├── logs/              # Log files
│   ├── main.log      # Main process log
│   └── mcp-proxy.log # MCP proxy log
└── qimingclaw.db        # SQLite database

IPC Channels

Category	Channels
Session	session:list, session:create, session:delete
Message	message:list, message:add
Settings	settings:get, settings:set
Agent	agent:init, agent:destroy, agent:prompt
MCP	mcp:install, mcp:uninstall, mcp:start, mcp:stop

MCP Proxy Service Details

qiming-mcp-stdio-proxy is an MCP protocol aggregation proxy that solves lifecycle management issues when integrating multiple MCP servers.

Running Modes

Mode	Purpose	Command
stdio	Aggregate multiple MCP servers into single stdio interface	qiming-mcp-stdio-proxy --config '...'
convert	Convert remote MCP service to local stdio	qiming-mcp-stdio-proxy convert <url>
proxy	Persistent bridge, pre-start and expose HTTP interface	qiming-mcp-stdio-proxy proxy --port 18099

Core Features

• Readiness Detection: Block until MCP servers are ready
• Resilient Transport: Heartbeat detection, exponential backoff reconnection, request queue
• Centralized Cleanup: Gracefully terminate all child processes

Resilient Transport Parameters

Parameter	Default	Description
pingIntervalMs	20000	Heartbeat interval
maxConsecutiveFailures	3	Consecutive failure threshold
maxReconnectDelayMs	60000	Reconnection delay cap
maxQueueSize	100	Request queue capacity

Configuration

Electron Client Configuration

Configure through setup wizard on first run:

1. Enter Anthropic API Key
2. Select default model
3. Configure MCP servers

Sensitive configuration is stored in SQLite database, not hardcoded.

MCP Server Configuration Example

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "github": {
      "url": "https://api.github.com/mcp"
    }
  }
}

Development Guide

Directory Structure

crates/agent-electron-client/
├── src/
│   ├── main/              # Main process
│   │   ├── main.ts        # Entry point
│   │   ├── preload.ts     # Preload script
│   │   ├── ipc/           # IPC handlers
│   │   └── services/      # Main process services
│   ├── renderer/          # Renderer process
│   │   ├── main.tsx       # React entry
│   │   ├── App.tsx        # Main component
│   │   ├── components/    # React components
│   │   └── services/      # Renderer services
│   └── shared/            # Shared code
├── resources/             # Packaged resources
├── scripts/               # Build scripts
└── package.json

Running Tests

# Electron client
cd crates/agent-electron-client
npm run test

# MCP proxy
cd crates/qiming-mcp-stdio-proxy
npm run test:run
npm run test:coverage

Debug Mode

# Enable verbose logging
RUST_LOG=debug npm run dev

GitHub Actions

CI/CD Workflows

Workflow	Trigger	Description
ci-electron.yml	crates/agent-electron-client/** changes	Electron test build
release-electron.yml	Push electron-v* tag	Electron release build

Release Process

# Electron release
git tag electron-v0.9.0
git push origin electron-v0.9.0

License

Apache License 2.0

Contributing

Issues and Pull Requests are welcome!

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Create a Pull Request

See CONTRIBUTING.md for details.

Related Projects

• Electron - Cross-platform desktop app framework
• MCP - Model Context Protocol
• Ant Design - React UI component library