@ai-zen/cli

A command-line interface for AI agents, built on @ai-zen/agents-sdk and @ai-zen/agents-core. Provides an interactive conversation terminal with built-in file system tools, sub-agent orchestration, and skill management.

npm install -g @ai-zen/cli

git clone git@github.com:ai-zen/cli.git
cd cli
pnpm install
pnpm build
npm install -g .

# Interactive main menu
zen

# Quick chat (pass message as argument)
zen Hello, introduce yourself.

Run zen to enter the main menu:

🤖 Welcome to AI-Zen CLI

? Select an action:
  ▶️  Continue last unfinished conversation  (if draft exists)
  💬  Start a new conversation
  📂  Continue a saved conversation
  📋  Manage saved conversations
  🤖  Manage Agents
  ⚙️   Configuration
  ❌  Exit

If you exit a conversation without saving (or the process is killed), the conversation is automatically saved as a draft. Next time you start zen, you'll see:

▶️  Continue last unfinished conversation (12 messages, 2025/1/1 12:00:00)
💬  Start a new conversation (discard draft)

While in a conversation, all commands start with /:

When the API response's usage.prompt_tokens exceeds the model's maxContextTokens, the system automatically generates a handover document summarizing completed tasks, pending items, and key decisions. A new conversation session is created with this document as context, ensuring seamless continuation.

The migration prompt template includes:

• Conversation Breakpoint — Last user/AI exchange verbatim
• Completed Tasks — Task titles and output paths
• Pending Tasks — Description, progress, next steps
• Important Notes — Technical preferences, lessons learned, architecture decisions
• File Index — Key files with descriptions
• Handover Instructions — SOP for the relay agent (read files first, verify state, then act)

When you type an unrecognized command in your terminal, it can be automatically forwarded to AI for processing:

# Install the hook
zen hook install

# After that, try typing something random:
> what's the weather today?
# This will be forwarded to AI instead of showing "command not found"

# Uninstall
zen hook uninstall

Configuration is stored in ~/.ai-zen/cli/config.json (or $AI_ZEN_DIR/cli/config.json if set). The maxContextTokens field on each model sets the migration threshold (typically ~25% of the model's actual context window, e.g. 250,000 for a 1M-token model).

{
  "endpoints": [
    {
      "id": "openai",
      "name": "OpenAI",
      "apiKey": "sk-xxx",
      "baseUrl": "https://api.openai.com/v1"
    }
  ],
  "models": [
    {
      "id": "gpt-5.5",
      "name": "GPT-5.5",
      "endpointId": "openai",
      "modelName": "gpt-5.5",
      "maxContextTokens": 250000
    }
  ],
  "imageModels": [
    {
      "id": "cogview-3",
      "name": "CogView-3",
      "endpointId": "bigmodelcn",
      "modelName": "cogview-3",
      "defaultSize": "1024x1024"
    }
  ],
  "defaultModel": "deepseek-v4-flash",
  "defaultImageModel": "cogview-3",
  "defaultAgent": "default",
  "defaultMigrationModel": "deepseek-v4-flash"
}

• AI_ZEN_DIR — Override the shared root directory (default: ~/.ai-zen). CLI runtime data goes to $AI_ZEN_DIR/cli/, and shared resources (agents, skills, tools, MCP, etc.) go to $AI_ZEN_DIR/.

~/.ai-zen/                    ← Shared root (AI_ZEN_DIR)
├── cli/                      ← CLI runtime data
│   ├── config.json           ← CLI endpoints, models
│   ├── conversations/        ← CLI conversations
│   └── drafts/               ← CLI drafts
├── agents/                   ← Agent definitions (shared)
│   ├── default.json          ← Default agent (created on first run)
│   └── my-custom-agent.json
├── sub-agents/               ← SubAgent definitions (shared)
│   ├── general-assistant.json ← Default sub-agent (created on first run)
│   └── my-coder.json
├── skills/                   ← Skill directory (shared)
│   └── my-skill/
│       └── SKILL.md
├── tools/                    ← User-defined tools (shared)
│   └── my-tool.js
├── mcp.json                  ← MCP config (shared)
└── mcp-oauth/                ← MCP OAuth tokens (shared)

/path/to/project/
├── .mcp.json                 ← Project-shared MCP config (committable)
└── .ai-zen/
    ├── mcp.json              ← Project-personal MCP config (not committed)
    ├── skills/               ← Project Skill directory
    │   └── my-skill/
    │       └── SKILL.md
    ├── tools/                ← Project tool directory
    │   └── my-tool.js
    ├── sub-agents/           ← Project SubAgent directory
    │   └── project-helper.json
    └── agents/               ← Project Agent directory (overrides user-level)
        └── project-agent.json

MCP server configurations are merged from multiple sources (high to low priority):

1. Project personal .ai-zen/mcp.json (collected from cwd up to git root)
2. Project shared .mcp.json (same)
3. User-level ~/.ai-zen/mcp.json

Same-named servers in higher priority override lower ones.

The CLI provides 17 built-in file system tools, implemented by @ai-zen/agents-sdk:

Conditionally injected (requires defaultImageModel in config):

In addition to built-in tools, the SDK provides 5 dynamic loading tools that are registered based on available resources and permissions:

Tools are assembled in three phases by the SDK's Provider capability pipeline:

1. Discovery — Scan filesystem for built-in tools, user tools, SubAgents, Skills, and MCP servers
2. Filtering — Apply permissions (allow/deny) and security exclusions (recursion protection)
3. Instantiation — Map filtered names to Tool instances and register dynamic loaders

Each Agent has independent permissions — no inheritance between parent Agent and SubAgent. The only exception is the temporary Skill sub-agent (created by call_skill_sub_agent), which inherits the caller's permissions as a transient conversation proxy rather than an independent entity.

interface AgentPermissions {
  tools?: { allow: string[] } | { deny: string[] };
  skills?: { allow: string[] } | { deny: string[] };
  mcps?: { allow: string[] } | { deny: string[] };
  subagents?: { allow: string[] } | { deny: string[] };
}

• Missing permissions field = all dimensions denied (deny: ["*"])
• Each dimension uses either allow (whitelist) or deny (blacklist), mutually exclusive
• "*" wildcard matches any name
• Denied resources are fully invisible to the LLM (not just blocked)

MCP servers are configured in mcp.json files:

{
  "mcpServers": {
    "my-server": {
      "transport": "stdio",
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "xxx"
      }
    }
  }
}

Connection lifecycle (connect, reconnect with exponential backoff, idle timeout) is fully managed by the SDK's McpConnectionManager.

OAuth 2.0 授权流程（mcp.json 中的 oauth 字段）已定义类型和预留 mcp-oauth/ 存储目录，但尚未实现。目前配置了 oauth 的 HTTP MCP 服务器将因缺少 token 而连接失败。

pnpm install
pnpm build
pnpm start

# Unit tests
pnpm test

# E2E tests (requires API key in .env.local)
pnpm test -- src/__tests__/e2e.test.ts

ISC