**English** | [中文](README.zh-CN.md)

# ai-cli

> A cross-platform AI coding assistant — CLI, Web UI, and Desktop App — with multi-provider support and agentic tool calling

[![npm version](https://img.shields.io/npm/v/jinzd-ai-cli)](https://www.npmjs.com/package/jinzd-ai-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
[![Tests](https://img.shields.io/badge/tests-1097%20passing-brightgreen)]()
[![GitHub Release](https://img.shields.io/github/v/release/jinzhengdong/ai-cli)](https://github.com/jinzhengdong/ai-cli/releases)
[![CI](https://github.com/jinzhengdong/ai-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/jinzhengdong/ai-cli/actions/workflows/ci.yml)

**ai-cli** is a powerful AI assistant that connects to 9 providers (including local Ollama models) and executes tasks autonomously through agentic tool calling. Use it as a terminal REPL, a browser-based Web UI, or a standalone Electron desktop app.

<p align="center">
  <img src="https://img.shields.io/badge/CLI-Terminal-blue" alt="CLI" />
  <img src="https://img.shields.io/badge/Web_UI-Browser-green" alt="Web UI" />
  <img src="https://img.shields.io/badge/Desktop-Electron-purple" alt="Desktop" />
</p>

## Highlights

- **9 Built-in Providers** — Claude, Gemini, DeepSeek, OpenAI, Zhipu GLM, Kimi, **MiniMax (海螺)**, OpenRouter (300+ models), **Ollama** (local models, no API key needed)
- **3 Interfaces** — Terminal CLI, browser Web UI (`aicli web`), Electron desktop app
- **Agentic Tool Calling** — AI autonomously runs shell commands, reads/writes files, searches code, fetches web, runs tests (default 200 rounds, configurable up to 10000 via `config.maxToolRounds` or `--max-tool-rounds`)
- **Prompt Caching** *(v0.4.70+)* — System prompt split into stable/volatile halves so Claude caches the stable part with `cache_control: ephemeral`; cached tokens bill at ~10% of the input price
- **Unified-Diff Patch Edits** *(v0.4.72+)* — `edit_file` accepts standard `@@ -a,b +c,d @@` hunks for the most compact way to apply many scattered small changes to a large file (±200-line drift tolerance + whitespace fallback)
- **Anthropic Batches API** *(v0.4.73+)* — `aicli batch submit/list/status/results/cancel` for 50%-off, 24-hour async processing — ideal for offline analysis and bulk evals
- **Web UI Session Replay** *(v0.4.71+)* — 🎬 button on every saved session opens a timeline replay: every message, tool call, reasoning, and cache-aware token usage at a glance
- **Conversation Branching** *(v0.4.74+)* — `/branch list/new/switch/delete/rename` inside the REPL, plus a 🌿 "fork here" button on every replay step — explore alternate directions without losing the original thread
- **Symbol Index** *(v0.4.76+, multi-language since v0.4.143)* — persistent tree-sitter index for TypeScript / JavaScript / TSX / Python / Go / Rust / Java / C/C++ powers three new AI tools: `find_symbol`, `get_outline`, `find_references`. Orders of magnitude faster than grep for definition lookups; background refresh on REPL startup, `/index status|rebuild|clear` to manage
- **Semantic Code Search** *(v0.4.77+)* — `search_code` tool finds code by meaning, not name. Local sentence embeddings (multilingual MiniLM, 117 MB one-time download) score symbols by cosine similarity against natural-language queries in English or Chinese ("where are users authenticated", "哪里做了速率限制"). No API key, runs on CPU. Manage with `/index semantic-rebuild|semantic-clear`
- **MCP Server Mode** *(v0.4.84+)* — `aicli mcp-serve` reverses ai-cli into an MCP server (JSON-RPC 2.0 over stdio), exposing its 28 built-in tools (incl. `find_symbol` / `search_code` / `run_tests`) to Claude Desktop / Cursor / any MCP client. Opt-in destructive-tool allow, `--tools` whitelist, `--cwd` override
- **Session Sensitive-Data Redaction** *(v0.4.88+)* — unified redactor scrubs `password=` / `api_key` / bearer tokens / OpenAI-style keys from every message **before it hits disk**. Query text is redacted too, so secrets never reach embeddings or logs. `/security status` + `/security scan` to audit
- **Human-like Long-Term Memory** *(v0.4.89+, B4)* — semantic index over every past chat session + `recall_memory` AI tool + `/memory rebuild|refresh|status|recall` commands. AI is prompted to auto-recall when it sees "last time" / "之前" / ambiguous references. Reuses the same MiniLM embedder as semantic code search
- **Web UI Memory Panel** *(v0.4.90+, B4)* — new 🧠 Memory sidebar tab with semantic search across past chats; each hit has **➕ Inject** (quotes the snippet into the chat input as a markdown blockquote so you can review/edit before sending — no silent context injection) and **↗ Load** (jumps to source session). Bulk "Inject top 3" for recall bundles
- **Streaming Tool Use** — Real-time streaming of AI reasoning and tool calls as they happen
- **Sub-Agents** — Delegate complex subtasks to isolated child agents with independent tool loops
- **Extended Thinking** — Claude deep reasoning mode with `/think` toggle
- **Plan Mode** — Read-only planning phase (`/plan`) where AI analyzes before executing, with loop detection
- **Auto-Pause** — Automatically pauses every 10 rounds for user review and redirection
- **MCP Protocol** — Connect external MCP servers for dynamic tool discovery
- **Multi-User Auth** — Web UI supports multiple users with password authentication
- **PWA Support** — Install Web UI as a desktop/mobile app, accessible over LAN
- **Hierarchical Context** — 3-layer context files (global / project / subdirectory) auto-injected
- **Headless Mode** — `ai-cli -p "prompt"` for CI/CD pipelines and scripting
- **44 REPL Commands** — Session management, checkpointing, code review, security review/scan, rewind, scaffolding, cross-session history search, chat-memory recall, smart model routing (`/route`), and more
- **GitHub Actions CI/CD** — Automated testing on Node 20/22 + npm publish on release tags
- **Cross-Platform** — Windows, macOS, Linux

## Installation

### npm (recommended)

```bash
npm install -g jinzd-ai-cli
```

Requires Node.js >= 20. After installation, use `aicli` to start.

### Electron Desktop App (Windows)

Download the installer from [GitHub Releases](https://github.com/jinzhengdong/ai-cli/releases) — no Node.js required:

| Platform | Download |
|----------|----------|
| Windows x64 | [`ai-cli-setup.exe`](https://github.com/jinzhengdong/ai-cli/releases/latest) |

### Standalone CLI Executables

Pre-built CLI binaries (no Node.js required, ~56 MB):

| Platform | File |
|----------|------|
| Windows x64 | `ai-cli-win.exe` |
| macOS arm64 | `ai-cli-mac` |
| macOS x64 | `ai-cli-mac-x64` |
| Linux x64 | `ai-cli-linux` |

## Quick Start

### Terminal CLI

```bash
aicli
```

On first run, an interactive setup wizard guides you through setting up your profile and entering your API key. Your identity is persisted and injected into every AI conversation.

```
[deepseek] > Hello! Tell me about this project
[deepseek] > @src/main.ts Review this file for bugs
[deepseek] > @screenshot.png What's in this image?
[deepseek] > /help
```

Use `@filepath` to reference files or images directly in your prompt.

### Web UI

```bash
aicli web                    # Start on localhost:3456
aicli web --port 8080        # Custom port
aicli web --host 0.0.0.0    # LAN access (shows QR-friendly URL)
```

Features: multi-tab sessions, file tree panel, drag & drop images, prompt templates, 8 DaisyUI themes, PWA installable, keyboard shortcuts, diff syntax highlighting.

### User Management

```bash
aicli user create admin      # Create user (enables auth)
aicli user list              # List all users
aicli user reset-password x  # Reset password
aicli user delete x          # Delete user
```

## Supported Providers

| Provider | Models | Get API Key |
|----------|--------|-------------|
| **Claude** | Opus 4, Sonnet 4, Haiku 4 | [console.anthropic.com](https://console.anthropic.com) |
| **Gemini** | 2.5 Pro, 2.5 Flash | [aistudio.google.com](https://aistudio.google.com) |
| **DeepSeek** | DeepSeek-Chat (V3), Reasoner (R1) | [platform.deepseek.com](https://platform.deepseek.com) |
| **OpenAI** | GPT-5.4, GPT-4o, o3, o4-mini | [platform.openai.com](https://platform.openai.com) |
| **OpenRouter** | 300+ models (Claude, GPT, Gemini, Llama, Qwen, Mistral...) | [openrouter.ai](https://openrouter.ai) |
| **Zhipu** | GLM-4, GLM-5 | [open.bigmodel.cn](https://open.bigmodel.cn) |
| **Kimi** | Moonshot, Kimi-K2 | [platform.moonshot.cn](https://platform.moonshot.cn) |
| **Ollama** | Any locally installed model (Llama, Qwen, Gemma, Mistral...) | No API key — [ollama.com](https://ollama.com) |

Any OpenAI-compatible API can also be used via `customBaseUrls` in config.

### Ollama (Local Models)

Run AI models entirely on your own hardware — no API key, no usage fees, no data leaving your machine.

```bash
# Install Ollama from https://ollama.com, then pull a model:
ollama pull qwen3:4b      # recommended: good tool-calling support
ollama pull gemma3:4b
ollama pull llama3.1:8b

# Start aicli and switch to Ollama:
aicli
[deepseek] > /provider ollama   # auto-discovers installed models
[ollama] > /model               # select from your local models
```

> **Note**: Use models 4B+ for best results with tool calling. Small models (<4B) may struggle with the tool definitions injected by MCP servers.

## Built-in Tools (Agentic)

AI autonomously invokes these 27 tools during conversations:

| Tool | Safety | Description |
|------|--------|-------------|
| `bash` | varies | Execute shell commands (PowerShell on Windows, $SHELL on Unix) |
| `read_file` | safe | Read file contents (10 MB limit, image support) |
| `write_file` | write | Create/overwrite files (diff preview + confirmation) |
| `edit_file` | write | Precise string replacement with fuzzy matching hints + `replaceAll` mode |
| `list_dir` | safe | List directory contents |
| `grep_files` | safe | Regex search across files |
| `glob_files` | safe | Match files by glob pattern |
| `web_fetch` | safe | Fetch web pages as Markdown (SSRF-protected) |
| `google_search` | safe | Google Custom Search API |
| `run_interactive` | safe | Run interactive programs with stdin input |
| `run_tests` | safe | Auto-detect and run project tests (JUnit XML parsing) |
| `spawn_agent` | safe | Delegate subtasks to isolated child agents |
| `ask_user` | safe | Pause and ask the user a question |
| `save_memory` | safe | Persist important info across sessions |
| `write_todos` | safe | Task breakdown with live progress rendering |
| `save_last_response` | write | Save AI response to file |
| `task_create` | write | Start a command running in the background |
| `task_list` | safe | List background tasks and their status/output |
| `task_stop` | write | Stop a running background task |
| `git_status` | safe | Show working tree status (branch, staged, modified, untracked) |
| `git_diff` | safe | Show file diffs (staged/unstaged, stat summary) |
| `git_log` | safe | Show commit history (oneline/full, filter by file/author) |
| `git_commit` | write | Create a git commit (stage files, message) |
| `notebook_edit` | write | Edit Jupyter notebook cells (add/edit/delete/move) |
| `find_symbol` | safe | Locate symbol definitions via persistent tree-sitter index (TS/JS/TSX/Python/Go/Rust/Java/C++) |
| `get_outline` | safe | Enumerate all top-level declarations in one source file |
| `find_references` | safe | Search indexed files for references to a symbol name |
| `search_code` | safe | Semantic (meaning-based) code search via local sentence embeddings — bilingual, "grep by meaning" |

**Safety levels**: `safe` = auto-execute, `write` = diff preview + confirmation, `destructive` = prominent warning + confirmation.

## Key REPL Commands

| Command | Description |
|---------|-------------|
| `/provider` | Switch AI provider |
| `/model` | Switch model |
| `/plan` | Enter read-only planning mode |
| `/think` | Toggle Claude extended thinking |
| `/test` | Auto-detect and run project tests |
| `/review` | AI code review of current git diff |
| `/security-review` | Security vulnerability scan on git diff |
| `/rewind` | Rewind conversation + restore files to checkpoint state |
| `/scaffold <desc>` | AI generates project skeleton |
| `/init` | AI generates project context file (AICLI.md) |
| `/compact` | Compress conversation history |
| `/session` | Session management (new / list / load) |
| `/checkpoint` | Save/restore conversation checkpoints |
| `/fork` | Fork the current session into a new session file |
| `/branch` | Create/switch/delete branches *within* the current session (B2) |
| `/index` | Manage symbol + semantic index (status/rebuild/clear/semantic-rebuild/semantic-clear) — powers `find_symbol` / `get_outline` / `find_references` / `search_code` (C1+C2) |
| `/search <keyword>` | Full-text search across all sessions |
| `/skill` | Manage agent skill packs |
| `/mcp` | View MCP server status and tools |
| `/cost` | Show token usage statistics |
| `/undo` | Undo last file operation |
| `/doctor` | Health check (API keys, MCP, context) |
| `/export` | Export session as Markdown or JSON |
| `/profile` | View/edit your identity (AI knows who you are across all providers) |
| `/config` | Open configuration wizard |
| `/help` | Show all available commands |

**Multi-line input**: Use `\` at end of line for continuation, or paste multi-line content directly (auto-detected and merged).

Type `/help` in the REPL to see all 40 commands.

## CLI Parameters

```bash
aicli [options]

Options:
  --provider <name>        Set AI provider
  -m, --model <name>       Set model
  -p, --prompt <text>      Headless mode: single prompt, then exit
  --system <prompt>        Override system prompt (headless)
  --json                   Output JSON response (headless)
  --output-format <fmt>    text | streaming-json (NDJSON)
  --resume <id>            Resume a previous session
  --allowed-tools <list>   Comma-separated tool whitelist
  --blocked-tools <list>   Comma-separated tool blacklist
  --no-stream              Disable streaming output

Subcommands:
  aicli web [options]      Start Web UI server
  aicli config             Run configuration wizard
  aicli providers          List all providers and status
  aicli sessions           List recent sessions
  aicli user <action>      Manage Web UI users
  aicli batch <action>     Anthropic Batches API (submit | list | status | results | cancel)
```

### Batch Mode (Anthropic Message Batches)

For offline analysis, bulk evals, or any workload where latency is flexible, use the Batches API for **50% off** tokens with a 24-hour processing window.

```bash
# 1. Prepare a JSONL file (one request per line):
#    {"customId":"req-1","messages":[{"role":"user","content":"..."}],"maxTokens":1024}
aicli batch submit prompts.jsonl         # validate + submit + track locally
aicli batch submit --dry-run prompts.jsonl  # parse only, no network

aicli batch list                          # live status of recent batches
aicli batch status <id>                   # detailed status + request counts
aicli batch results <id> out.jsonl        # download results (stdout if no path)
aicli batch cancel <id>                   # cancel an in-progress batch
```

Local tracking file: `~/.aicli/batches.json` (last 200 submissions). Requires `AICLI_API_KEY_CLAUDE` or a Claude API key configured via `aicli config`.

### Headless Mode

```bash
# Single prompt
aicli -p "Explain recursion in one sentence"

# Pipe stdin
cat src/main.ts | aicli -p "Review this code"

# JSON output for scripting
aicli -p "hello" --json

# Streaming JSON (NDJSON)
aicli -p "write a poem" --output-format streaming-json
```

## Configuration

Configuration is stored at `~/.aicli/config.json`. Run `aicli config` for the interactive wizard, or edit directly:

```json
{
  "defaultProvider": "deepseek",
  "apiKeys": {
    "deepseek": "sk-...",
    "claude": "sk-ant-...",
    "openrouter": "sk-or-..."
  },
  "proxy": "http://127.0.0.1:10809",
  "mcpServers": { },
  "ui": {
    "theme": "dark",
    "wordWrap": 0,
    "notificationThreshold": 10000
  }
}
```

### Permission Rules

Control when tools require confirmation. Rules are checked in order — first match wins:

```json
{
  "permissionRules": [
    { "tool": "read_file", "action": "auto-approve" },
    { "tool": "list_dir", "action": "auto-approve" },
    { "tool": "grep_files", "action": "auto-approve" },
    { "tool": "glob_files", "action": "auto-approve" },
    { "tool": "write_todos", "action": "auto-approve" },
    { "tool": "bash", "action": "auto-approve", "when": { "dangerLevel": "safe" } },
    { "tool": "write_file", "action": "auto-approve", "when": { "pathPattern": "src/" } },
    { "tool": "bash", "action": "deny", "when": { "pathPattern": "rm -rf" } },
    { "tool": "*", "action": "confirm" }
  ]
}
```

| Field | Description |
|-------|-------------|
| `tool` | Tool name, or `*` for all tools |
| `action` | `auto-approve` (skip confirmation), `deny` (block), `confirm` (ask user) |
| `when.dangerLevel` | Only match when danger level is `safe`, `write`, or `destructive` |
| `when.pathPattern` | Substring match against tool's `path` or `command` argument |

**Recommended minimal config** — auto-approve all read-only tools to reduce y/N prompts:

```json
{
  "permissionRules": [
    { "tool": "read_file", "action": "auto-approve" },
    { "tool": "list_dir", "action": "auto-approve" },
    { "tool": "grep_files", "action": "auto-approve" },
    { "tool": "glob_files", "action": "auto-approve" },
    { "tool": "web_fetch", "action": "auto-approve" },
    { "tool": "write_todos", "action": "auto-approve" },
    { "tool": "ask_user", "action": "auto-approve" },
    { "tool": "run_tests", "action": "auto-approve" }
  ]
}
```

### Environment Variables

Environment variables take precedence over config file values:

| Variable | Description |
|----------|-------------|
| `AICLI_API_KEY_CLAUDE` | Claude API Key |
| `AICLI_API_KEY_GEMINI` | Gemini API Key |
| `AICLI_API_KEY_DEEPSEEK` | DeepSeek API Key |
| `AICLI_API_KEY_OPENAI` | OpenAI API Key |
| `AICLI_API_KEY_OPENROUTER` | OpenRouter API Key |
| `AICLI_API_KEY_ZHIPU` | Zhipu API Key |
| `AICLI_API_KEY_KIMI` | Kimi API Key |
| `AICLI_PROVIDER` | Default provider ID |
| `AICLI_NO_STREAM` | Set to `1` to disable streaming |
| `HTTPS_PROXY` / `HTTP_PROXY` | Proxy URL |

### Hierarchical Context Files

ai-cli automatically discovers and injects context files into the system prompt:

| Layer | Path | Purpose |
|-------|------|---------|
| Global | `~/.aicli/AICLI.md` | Personal preferences across all projects |
| Project | `<git-root>/AICLI.md` | Project rules (commit to git for team sharing) |
| Subdirectory | `<cwd>/AICLI.md` | Directory-specific instructions |

Also supports `CLAUDE.md` as an alternative filename at each layer.

### MCP Integration

Connect external [MCP](https://modelcontextprotocol.io/) servers for dynamic tool discovery. Configuration is compatible with Claude Desktop format:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
      "timeout": 30000
    }
  }
}
```

Project-level `.mcp.json` files are also supported and automatically merged with global config.

## Web UI Features

The Web UI (`aicli web`) provides a full-featured browser interface:

- **Multi-Tab Sessions** — parallel conversations in separate browser tabs
- **File Tree Panel** — browse project files, click to insert `@path` references
- **Image Upload** — drag & drop or Ctrl+V paste images into chat
- **Prompt Templates** — CRUD with tags, search, import/export
- **8 Themes** — DaisyUI themes with code highlight auto-sync
- **Diff Syntax Highlighting** — colored diff in tool confirm dialogs
- **Keyboard Shortcuts** — `Esc` stop, `Ctrl+L` clear, `↑↓` history
- **Export** — `/export md` or `/export json` browser download
- **PWA** — installable as desktop/mobile app
- **LAN Access** — `--host 0.0.0.0` for phone/tablet access
- **Multi-User Auth** — password authentication with per-user data isolation
- **Auto-Reconnect** — heartbeat + exponential backoff reconnection

## Testing

```bash
npm test              # Run all 396 tests
npm run test:watch    # Watch mode
```

26 test suites covering: authentication, sessions, tool types & danger levels, permissions, output truncation, diff rendering, edit-file similarity, error hierarchy, config management, env loading, provider registry, web-fetch, grep-files, hub renderer, hub discussion, hub presets, dev-state, token estimator, tool registry budget, parallel tool execution, cost tracker, session tool history.

## Documentation

- [`docs/USAGE.md`](docs/USAGE.md) — Complete reference manual (commands, tools, config)
- [`docs/TUTORIAL.md`](docs/TUTORIAL.md) — Hands-on tutorial, zero to fluent in an hour
- [`docs/ADVANCED.md`](docs/ADVANCED.md) — Architecture and internals (for developers)
- [`docs/RECIPES.md`](docs/RECIPES.md) — Practical recipes by scenario
- [`docs/SECURITY.md`](docs/SECURITY.md) — **Security model, deployment checklist, audit history.** Read before exposing `aicli web` to a network.
- [`CHANGELOG.md`](CHANGELOG.md) — Per-version change log
- [Chinese README](README.zh-CN.md) — 中文说明文档

## License

[MIT](LICENSE)
