# X Code Cli

> Open-source, model-agnostic coding agent CLI with subagents, skills, MCP, and plugins.

- **Type:** MCP server
- **Install:** `agentstack add mcp-woai3c-x-code-cli`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [woai3c](https://agentstack.voostack.com/s/woai3c)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [woai3c](https://github.com/woai3c)
- **Source:** https://github.com/woai3c/x-code-cli

## Install

```sh
agentstack add mcp-woai3c-x-code-cli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# X-Code CLI

**A model-agnostic coding agent CLI with Claude Code-compatible extensions.**

Use Claude, GPT, Gemini, DeepSeek, Qwen, Kimi, or any OpenAI-compatible model in one open-source agent workflow.

[](https://www.npmjs.com/package/@x-code-cli/cli)
[](./LICENSE)

English · [简体中文](./README.zh-CN.md)

## Why X-Code CLI?

**Model agnostic** — Switch providers at any time with `/model`, or connect any OpenAI-compatible endpoint. One workflow, any model.

**Claude Code-compatible extensions** — Reuse plugins, skills, sub-agents, MCP servers, and hooks built for Claude Code. The plugin loader recognizes both `.x-code-plugin/` and `.claude-plugin/` formats.

**Open and controllable** — Open source, BYOK, local execution, configurable 3-level permission model. You decide what the agent can do.

**Complete agent runtime** — More than a chat wrapper: it covers planning, execution, memory, context management, and task verification.

> X-Code CLI is an independent open-source project and is not affiliated with Anthropic.

## Install

> Requires **Node.js >= 22** (Node 20 is not supported).

```bash
npm install -g @x-code-cli/cli

# Or
pnpm add -g @x-code-cli/cli
```

After installation, launch with the `xc` or `x-code` command.

## Configure API Keys

> **X-Code CLI does not bundle a free model. At least one provider API key must be configured.**
>
> **Recommended: [DeepSeek](https://platform.deepseek.com/)** — affordable, free credits on signup, sufficient coding capability for everyday use.

| Variable                       | Provider           | Sign up                                                                     |
| ------------------------------ | ------------------ | --------------------------------------------------------------------------- |
| `ANTHROPIC_API_KEY`            | Anthropic (Claude) | [console.anthropic.com](https://console.anthropic.com/)                     |
| `OPENAI_API_KEY`               | OpenAI (GPT)       | [platform.openai.com/api-keys](https://platform.openai.com/api-keys)        |
| `DEEPSEEK_API_KEY`             | DeepSeek           | [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys)    |
| `GOOGLE_GENERATIVE_AI_API_KEY` | Google (Gemini)    | [aistudio.google.com/apikey](https://aistudio.google.com/apikey)            |
| `ALIBABA_API_KEY`              | Alibaba (Qwen)     | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com/apiKey) |
| `XAI_API_KEY`                  | xAI (Grok)         | [console.x.ai](https://console.x.ai/)                                       |
| `ZHIPU_API_KEY`                | Zhipu (GLM)        | [open.bigmodel.cn](https://open.bigmodel.cn/usercenter/apikeys)             |
| `MOONSHOT_API_KEY`             | Moonshot (Kimi)    | [Choose a service](#moonshot-kimi-endpoints)                                |

**OpenAI-compatible escape hatch** (vLLM / OpenRouter / internal gateways): set both `OPENAI_COMPATIBLE_API_KEY` and `OPENAI_COMPATIBLE_BASE_URL`, then address models as `custom:`.

Shell configuration examples (click to expand)

The examples below use `ANTHROPIC_API_KEY`; substitute your provider's variable name.

**bash (Linux / Git Bash / WSL)**

```bash
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc
source ~/.bashrc
```

**zsh (macOS default)**

```bash
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.zshrc
source ~/.zshrc
```

**fish**

```fish
set -Ux ANTHROPIC_API_KEY sk-ant-...
```

**Windows PowerShell (user-level, persistent)**

```powershell
[Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-...', 'User')
# Restart PowerShell to take effect
```

**Windows CMD (user-level, persistent)**

```cmd
setx ANTHROPIC_API_KEY "sk-ant-..."
:: Restart CMD to take effect
```

> For temporary use: `export X=...` (bash) or `$env:X = '...'` (PowerShell); discarded when the terminal closes.
>
> Per-project: place a `.env` file in the project root. `xc` walks up from the current directory.

Web search keys (optional)

To enable the `web_search` tool, configure either of the following. Both offer a free tier:

| Variable         | Provider                                      | Free quota         | Signup         |
| ---------------- | --------------------------------------------- | ------------------ | -------------- |
| `TAVILY_API_KEY` | [Tavily](https://tavily.com)                  | ~1,000 requests/mo | Email, no card |
| `BRAVE_API_KEY`  | [Brave Search](https://brave.com/search/api/) | ~1,000 requests/mo | Card required  |

> Tavily is recommended for first-time setup: simpler signup, LLM-optimized responses. When both are set, Tavily is preferred and Brave serves as fallback.

Moonshot (Kimi) endpoint note

Moonshot/Kimi credentials come from three separate services. A key only works with the endpoint of the service that issued it:

- Kimi Code plan: [Kimi Code console](https://www.kimi.com/code/console) → `https://api.kimi.com/coding/v1`
- China Open Platform: [platform.kimi.com](https://platform.kimi.com/console/api-keys) → `https://api.moonshot.cn/v1`
- International Open Platform: [platform.kimi.ai](https://platform.kimi.ai/console/api-keys) → `https://api.moonshot.ai/v1`

After selecting a Kimi model via `/model`, an endpoint picker appears automatically.

## Quick Start

```bash
cd your-project

xc                                              # Interactive session
xc "Explain the overall architecture"           # Run with a prompt
xc -m sonnet "Refactor the formatDate function" # Specify a model
```

## Key Features

### Intelligent Development

- **Built-in tools** — file I/O, shell execution, code search (Grep / Glob), web fetch, sub-agent delegation, todo tracking, and more
- **Sub-agents** — ships with 5 (explore / general-purpose / plan / code-reviewer / goal-verifier), supports custom agents
- **Plan mode** — `--plan` or `/plan` enters read-only exploration; the agent designs a plan, then executes after approval
- **Durable goal loops** — `/goal` runs execute → verify → repair cycles until passing or hitting a stop condition
- **File attachments** — `@path` or bare absolute paths auto-ingest text / code / PDF / Office docs (docx / xlsx / pptx / odt / ods / odp) / images / audio
- **Local audio transcription** — attach MP3 / WAV / M4A / OGG / FLAC / AAC / AIFF / WMA / WebM / Opus files; when the active model can't take audio input, X-Code CLI transcribes them locally via Whisper (whisper.cpp) and feeds the model timestamped text — the audio never leaves your machine. The Whisper model auto-downloads on first use and is cached under `~/.x-code/whisper-models/` (default `tiny`; set `X_CODE_WHISPER_MODEL` to pick another, e.g. `base`)
- **Vision sub-agent** — text-only providers (e.g. DeepSeek) can borrow a configured vision model for image understanding

### Context Management

- **Knowledge system** — layered `AGENTS.md` loading (compatible with `CLAUDE.md`), subpackages override root
- **Auto-memory** — durable facts (preferences, corrections, project state) saved after each turn, loaded next session
- **Session resumption** — `--continue` resumes the last session, `--resume` opens a picker or jumps by ID
- **Context compression** — long conversations auto-compress; loop-guard detects cycles; prompt cache reuses prefixes
- **3-level permission model** — safe by default, prompts before writes; `--trust` bypasses

### Extension Ecosystem

- **MCP integration** — stdio + HTTP (with OAuth), `/mcp` management, server tools merge into agent toolset
- **Plugin system** — bundle skills / sub-agents / MCP / hooks; byte-compatible with Claude Code plugin format
- **Skills** — reusable workflow templates as `SKILL.md`, triggered via `/`
- **Custom slash commands** — drop markdown into `~/.x-code/commands/` or project scope, invoke with `/`
- **Hooks** — 10 lifecycle event callbacks to intercept or rewrite agent behavior via shell commands
- **Browser automation** — `/browser on` enables a real-browser sub-agent (Playwright-powered), off by default

### Terminal Experience

- **Streaming output** — results render as they are generated
- **Theme switching** — `/theme` controls diff colors and syntax-highlight palette
- **Unified thinking mode** — `/thinking on|off` consolidates provider-specific reasoning parameters
- **Multiline input** — `Alt+Enter` or trailing `\` inserts a newline
- **Input history** — `↑`/`↓` on empty prompt recalls previous messages
- **Mid-turn steering** — keep typing while the agent is working: your message is queued above the spinner and injected at the next tool boundary
- **Live footer** — the active model and current context usage (e.g. `Kimi K3 · 6.6k / 200k · 3%`) are always visible under the input
- **Cross-platform** — Windows, macOS, Linux

## CLI Options

```text
xc [options] [prompt]

--model, -m       Model to use (e.g. sonnet, deepseek, openai:gpt-5.6-sol)
--trust, -t           Trust mode: skip write-operation confirmations
--print, -p           Non-interactive mode: print result and exit
--plan                Start in plan mode (read-only; user approves before edits)
--continue, -c        Resume the most recent session (no picker)
--resume, -r [id]     Resume a session: no argument opens the picker
--max-turns        Agent loop turn cap per submit (default: unlimited)
--no-plugins          Disable the plugin system (built-in only; for triage)
--no-hooks            Skip all hook execution
--plugin-debug        Mirror plugin/hook debug logs to stderr
--version, -v         Show version
--help, -h            Show help
```

### Non-interactive subcommands

```text
xc plugin             Manage plugins (list / install / uninstall / enable / disable / search / update / info / doctor / marketplace)
xc plugin install [--yes]    Install a plugin; --yes skips confirmation
xc plugin marketplace        Manage marketplace subscriptions (list / add / remove / refresh / info)
```

## Slash Commands

| Command                | Description                                                          |
| ---------------------- | -------------------------------------------------------------------- |
| `/help`                | Show available commands                                              |
| `/model [alias]`       | Switch model or list available models                                |
| `/thinking [on\|off]`  | Enable / disable thinking mode                                       |
| `/theme [name]`        | Switch UI theme                                                      |
| `/plan [on\|off]`      | Enable / disable plan mode                                           |
| `/goal [objective]`    | Start a durable goal loop (see [docs/goal.en.md](./docs/goal.en.md)) |
| `/usage`               | Token usage: context split, per-step detail, attribution, cache hits |
| `/usage-history`       | List past session usage                                              |
| `/clear`               | Clear the current conversation                                       |
| `/compact`             | Manually compress context                                            |
| `/resume`              | Pick a past session to resume                                        |
| `/rewind`              | Roll back to a previous message (restores files + truncates history) |
| `/init`                | Create or update `AGENTS.md` at project root                         |
| `/review [PR#]`        | Review a GitHub PR (requires `gh`)                                   |
| `/memory [subcommand]` | Inspect, search, explain, or reload global long-term memory          |
| `/skill `         | Manage Skills                                                        |
| `/mcp `           | Manage MCP servers                                                   |
| `/plugin `        | Manage plugins and marketplaces                                      |
| `/browser [on\|off]`   | Toggle the browser sub-agent (off by default)                        |
| `/doctor`              | Diagnose the runtime environment                                     |
| `/exit`                | Save session and exit                                                |

## Detailed Docs

This README is the entry view. Each feature has a focused doc under [`docs/`](./docs/) (Chinese `*.md`, English `*.en.md`):

| Doc                                                            | What it covers               |
| -------------------------------------------------------------- | ---------------------------- |
| [`docs/skills.en.md`](./docs/skills.en.md)                     | Reusable workflow templates  |
| [`docs/goal.en.md`](./docs/goal.en.md)                         | Durable goal loops (`/goal`) |
| [`docs/sub-agents.en.md`](./docs/sub-agents.en.md)             | Built-in / custom sub-agents |
| [`docs/mcp.en.md`](./docs/mcp.en.md)                           | MCP server configuration     |
| [`docs/knowledge.en.md`](./docs/knowledge.en.md)               | Knowledge base & auto-memory |
| [`docs/plugins.en.md`](./docs/plugins.en.md)                   | Plugin management            |
| [`docs/marketplace.en.md`](./docs/marketplace.en.md)           | Plugin marketplace           |
| [`docs/hooks.en.md`](./docs/hooks.en.md)                       | Agent lifecycle hooks        |
| [`docs/plugin-authoring.en.md`](./docs/plugin-authoring.en.md) | Plugin authoring guide       |

## Troubleshooting

Set `DEBUG_STDOUT=1` to capture a debug log:

```bash
# bash / zsh
DEBUG_STDOUT=1 xc

# fish
env DEBUG_STDOUT=1 xc

# PowerShell
$env:DEBUG_STDOUT=1; xc

# CMD
set DEBUG_STDOUT=1 && xc
```

Log path: `~/.x-code/logs/debug.log` (Windows: `%USERPROFILE%\.x-code\logs\debug.log`), 10 MB per file, ~20 MB total with rotation.

## Build From Source

```bash
git clone https://github.com/woai3c/x-code-cli.git
cd x-code-cli
pnpm install
pnpm dev
```

> Source changes require `pnpm build` or `pnpm dev`. For auto-watch, run `pnpm dev` inside `packages/core` (`tsc -b --watch`).

## Companion Book (Chinese)

For a deep dive into the implementation, check out the companion Juejin booklet: [**《从零打造一个 AI Agent CLI》**](https://juejin.cn/book/7639017024882278440?suid=1433418893103645&source=h5) — walks through the agent loop, multi-provider adapter, terminal rendering, permission model, and more using this codebase as reference.

**QQ Group: 455053594**

## Feedback & Contributing

Issues and pull requests are welcome: 

## License

[MIT](./LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [woai3c](https://github.com/woai3c)
- **Source:** [woai3c/x-code-cli](https://github.com/woai3c/x-code-cli)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-woai3c-x-code-cli
- Seller: https://agentstack.voostack.com/s/woai3c
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.