langchain-agentx-cli

AgentX Code — Terminal AI coding assistant with Claude Code compatible TUI.

依托 langchain-agentx-python SDK，提供功能完整的终端编码助手。

Installation

pip install langchain-agentx-cli

Requires Python 3.11+ and ANTHROPIC_API_KEY environment variable.

Quick Start

# Navigate to your project directory
cd ~/my-project

# Start AgentX Code
agentx-code

Environment Setup

# Set your Anthropic API key
export ANTHROPIC_API_KEY="sk-ant-..."

Command Options

agentx-code                                    # Start in current directory
agentx-code --workspace-root /path/to/project  # Specify workspace
agentx-code --mode agentx|claude|cursor        # Config-home brand mode (see below)
agentx-code --agent-home .cursor               # Or set segment directly (overridden by --mode)
agentx-code --model claude-sonnet-4-6         # Specify model
agentx-code --provider claude | openai        # Choose provider
agentx-code --dangerously-skip-permissions    # Skip permission prompts (CC-aligned)
agentx-code --allowed-tools Read Grep Glob    # Pre-approve tools (space or comma; CC --allowed-tools)
agentx-code --allowed-tools Bash,Skill        # Tier1 scan profile (OPS/new_agent); see SDK A25 R0
agentx-code --disallowed-tools Bash Edit      # Block tools (space or comma; deny wins)
agentx-code --tools Read Grep Glob            # Only these built-ins; others auto-denied (CC --tools)
agentx-code --mcp-config extra-mcp.json       # Load extra MCP servers (file or inline JSON; repeatable; CC --mcp-config)
agentx-code --strict-mcp-config               # Only use --mcp-config servers; skip project .mcp.json discovery
agentx-code -p "summarize README.md"          # One-shot print mode (headless)
agentx-code --show-config                     # Print merged config

Config home mode (agent_home_segment，与 SDK 三模式对齐)：

优先级：--mode > --agent-home > 环境变量 LANGCHAIN_AGENTX_AGENT_HOME > CLI 默认 .claude。只换品牌目录名，不按「目录是否存在」隐式回退。与默认 --provider claude 对齐：裸跑 agentx-code 即走 Claude 配置树。

Read-only audit (aligned with Claude Code CLI semantics):

agentx-code --permission-mode dontAsk \
  --allowed-tools Read,Grep,Glob \
  --disallowed-tools Bash,Edit,WebSearch,WebFetch

MCP (Model Context Protocol)

状态（2026-10-04）：CLI 宿主面按 D25 / 实施计划 分阶段落地，P0–P3 整包已交付：mcp add/add-json/list/get/remove 写仓库根 .mcp.json（P0），会话自动装池（project .mcp.json 有 server 即注入，出现 mcp__<server>__<tool> 工具）与 mcp list / mcp get 连接健康检查（P1），/mcp 管理面板 + project server 审批（未审批不连接；Approve/Reject/reconnect/enable/disable）+ mcp reset-project-choices + mcp login --token / mcp logout（P2a），浏览器 OAuth（PKCE：mcp login 打开浏览器 → 粘贴 callback URL；--client-id / --scope 可选）（P2b），启动 flags --mcp-config / --strict-mcp-config 与 mcp serve（默认只读子集 expose；P3）。local/user scope 写入仍待 SDK 提供 write API。

把外部 MCP server 接到 AgentX，用法与 Claude Code MCP 一致。配置生效并完成会话接线后，会出现 mcp__<server>__<tool> 工具。

添加 server

# HTTP（远程）
agentx-code mcp add --transport http docs https://code.claude.com/docs/mcp

# HTTP + 请求头（如 Bearer token）
agentx-code mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_TOKEN"

# SSE（远程）
agentx-code mcp add --transport sse asana https://mcp.asana.com/sse

# stdio（本地进程；`--` 后面整段交给 server，不要省略）
agentx-code mcp add --transport stdio filesystem -- \
  npx -y @modelcontextprotocol/server-filesystem .

# stdio + 环境变量
agentx-code mcp add --env API_KEY=xxx --transport stdio airtable -- \
  npx -y @airtable/mcp-server

# 整段 JSON 配置
agentx-code mcp add-json weather '{"type":"http","url":"https://example.com/mcp"}'

管理 server

agentx-code mcp list                 # 列出配置，并做连接健康检查
agentx-code mcp get docs             # 查看某个 server 详情 / 作用域 / 错误
agentx-code mcp remove docs          # 删除（可加 -s/--scope）
agentx-code mcp reset-project-choices  # 重置本项目 .mcp.json 的批准/拒绝选择

# 远程 MCP 的凭据（向 Sentry/Notion 等第三方授权拿 token；不是登录 Claude 账号）
# 浏览器 OAuth（PKCE）：打开浏览器授权 → 把跳转到的完整 callback URL 粘贴回终端
agentx-code mcp login sentry
agentx-code mcp login sentry --client-id <ID> --scope "mcp:read"   # 授权服务器需要时显式给出
# 或直接给静态 token（经 SDK submit_token 落当前 mode 的 mcp-oauth.json）
agentx-code mcp login sentry --token <ACCESS_TOKEN>
agentx-code mcp logout sentry
# 若服务商提供长期 token，也可在 add 时用 --header，不必走 login

作用域（-s / --scope）与三 mode

MCP 命令与主程序一样支持 --mode / --agent-home（默认 claude → .claude）。
project 始终写在仓库根 .mcp.json（与 mode 无关）；user / local 写在当前 mode 的全局配置根下。

agentx-code mcp add --transport http stripe --scope local https://mcp.stripe.com     # 默认 mode=claude：仅当前项目、私有
agentx-code mcp add --transport http shared --scope project https://example.com/mcp  # 仓库根 .mcp.json，可提交给团队
agentx-code mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic  # 本机所有项目（当前 mode 全局根）

# 显式使用 agentx / cursor 配置树（user/local 落盘目录不同）
agentx-code --mode agentx mcp add --scope user --transport http docs https://example.com/mcp
agentx-code --mode cursor mcp list

手写项目配置（等价于 --scope project）

在项目根创建 .mcp.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    }
  }
}

支持 ${VAR} / ${VAR:-default} 环境变量展开。JSON 里 streamable-http 等价于 http。

会话里使用

cd ~/my-project
agentx-code

进入 REPL 后：

/mcp                         # 管理面板：连接状态、审批项目级 server（a Approve / r Reject / c Reconnect）
/mcp reconnect filesystem    # 重连某个 server
/mcp enable filesystem       # 批准并连接（enable all 批量）
/mcp disable filesystem      # 拒绝并断开（disable all 批量）

project .mcp.json 中的 server 首次使用需审批（未审批不连接；选择持久化在用户级 ~/.config/langchain_agentx/mcp_approvals.json，按项目路径键——仓库本身无法自我批准）。 重置本项目的全部审批选择：

agentx-code mcp reset-project-choices

需要限制可用 MCP 工具时：

agentx-code --allowed-tools "mcp__filesystem__*"
agentx-code --disallowed-tools "mcp__docs__*"

把 AgentX 自己暴露成 MCP Server

除了「连出去」用别人的 MCP，也可以让本进程当 Server，把 AgentX 自身能力（工具子集）暴露给 Cursor 或其他 MCP Client：

# 以 stdio 提供 MCP（供外部 Client 的 command 指向本进程）
agentx-code mcp serve

# 显式打开危险工具（默认不暴露 Bash/Edit/Write）
agentx-code mcp serve --allow-tools Bash,Edit

# 调试（日志走 stderr；stdout 是 MCP 协议通道）
agentx-code mcp serve --debug --verbose

在 Cursor / 其他客户端里把 command 配成 agentx-code、args 配成 mcp serve（工作目录设为你的项目）。对方 tools/list 会看到 AgentX 暴露的工具，tools/call 仍走 SDK 执行与权限链。

默认只暴露只读子集 Read / Grep / Glob / WebFetch；Bash / Edit / Write / Skill 等须经 --allow-tools 显式打开（逗号/空格分隔，可重复；未知名会报错并列出可用工具）。

mcp list / mcp get 会对配置的 server 做探测（stdio 会启动进程）。请只在信任的目录中执行。

设计：D25 · 实施计划：exec-plan

Input Habits (Claude Code Compatible)

Type /help in the REPL for full command list.

Development

# Clone and install in editable mode
git clone https://github.com/GoodMood2008/langchain-agentx-cli.git
cd langchain-agentx-cli
pip install -e ".[dev]"

# Run tests
pytest tests -v

# Run directly (without install)
python -m langchain_agentx_cli

Configuration

Config file location: ~/.config/langchain_agentx/langchain_agentx.json

{
  "llm": {
    "provider": "claude",
    "model": "claude-sonnet-4-6",
    "api_key": null,
    "base_url": null
  },
  "theme": "dark",
  "show_suppressed_text": false
}

历史字段 user_message_preview_lines 已随 BriefTool/user_message 移除而废弃，请勿写入新配置。

Architecture

工程约定与开发说明见根目录 CLAUDE.md。

Design Docs

• D25 MCP CLI host surface — mcp * 子命令、/mcp、与 SDK A26 / Claude Code 对齐
• Tool naming SSOT — RuntimeTool.name、GrantScope、MemoryToolKind 边界
• Implementation Plans
• Design docs index

历史：D01 user_message（BriefTool 已移除，仅作归档）

License

Apache License 2.0