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`	Segment	Typical paths
`claude`（默认）	`.claude`	`~/.claude/`（与 Claude Code 同构，默认复用其全局配置/skills）
`agentx`	`.langchain_agentx`	`~/.langchain_agentx/`、仓库内 `.langchain_agentx/`
`cursor`	`.cursor`	`~/.cursor/`

优先级：--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	谁能用	写到哪里
`local`（默认）	仅你 + 当前项目	当前 mode 全局根内、按项目键的条目（默认 `~/.claude/…`）
`project`	克隆仓库的所有人	始终 `{workspace}/.mcp.json`（不在 `.claude/` / `.cursor/` 内）
`user`	仅你 + 所有项目	当前 mode 全局根（`~/.claude/` / `~/.langchain_agentx/` / `~/.cursor/`）

`--mode`	Segment	全局根（user/local）	工程内 agent home
`claude`（默认）	`.claude`	`~/.claude/`	`{workspace}/.claude/`
`agentx`	`.langchain_agentx`	`~/.langchain_agentx/`	`{workspace}/.langchain_agentx/`
`cursor`	`.cursor`	`~/.cursor/`	`{workspace}/.cursor/`

手写项目配置（等价于 `--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)

Key	Action
Enter	Send message
Shift+Enter	Insert newline
\ + Enter	Insert newline (alternative)
↑ / ↓	Navigate history / move in multiline
Tab	Command completion
Ctrl+R	History search
Ctrl+Shift+L	Clear messages
Ctrl+C	Cancel generation / Quit (twice)

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。

Layer	Name	Description
PyPI Package	`langchain-agentx-cli`	`pip install langchain-agentx-cli`
CLI Command	`agentx-code`	User types in terminal
Python Package	`langchain_agentx_cli`	`import` for use as library

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

Metadata

Release files for langchain-agentx-cli 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for langchain-agentx-cli 1.0.0
File	Size	Uploaded	Provenance
langchain_agentx_cli-1.0.0.tar.gz	439.8 kB	Oct 11, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for langchain-agentx-cli 1.0.0
File	Interpreter	ABI	Platform	Reset
langchain_agentx_cli-1.0.0-py3-none-any.whl 616.7 kB Oct 11, 2026 Without provenance	Python 3	none	any	Details

Total release size: 1.1 MB

Release files / langchain_agentx_cli-1.0.0.tar.gz

Download URL	langchain_agentx_cli-1.0.0.tar.gz
Size	439.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`c0018fed7d41992693a4477c8944bc233fcde349bb35cb0368cc6b71edbd43aa`
BLAKE2b-256 checksum How to use checksums	`c990d8ab81227d50f2964fa5f8d29b63b2307d3fd3300b055967a3191a7f9ac3`
Upload date	Oct 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.6`

Release files / langchain_agentx_cli-1.0.0-py3-none-any.whl

Download URL	langchain_agentx_cli-1.0.0-py3-none-any.whl
Size	616.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b97a913d2b8c0e9a0c9fc7fcf0d6354f3d7ecd0809443b69c4bb47ee183f7270`
BLAKE2b-256 checksum How to use checksums	`a469aabb1659cf8069d1dcbf6c8a773c9fc32b9f496d95236357f2445a34c48d`
Upload date	Oct 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.6`

Security for langchain-agentx-cli 1.0.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.