Metadata-Version: 2.4
Name: langchain-agentx-cli
Version: 0.9.2
Summary: Terminal CLI/TUI for AgentX: migrate Claude Code Ink UI, backed by langchain-agentx-python SDK.
Author: GoodMood2008
License: Apache-2.0
Project-URL: Homepage, https://github.com/GoodMood2008/langchain-agentx-cli
Project-URL: Documentation, https://github.com/GoodMood2008/langchain-agentx-cli#readme
Project-URL: Repository, https://github.com/GoodMood2008/langchain-agentx-cli.git
Project-URL: Python SDK, https://github.com/GoodMood2008/langchain_agentx_python
Keywords: ai,assistant,coding,claude,langchain,terminal,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain-agentx-python>=2.3.6
Requires-Dist: click>=8.1
Requires-Dist: markdown-it-py>=2.0
Requires-Dist: textual>=0.79.0
Requires-Dist: watchfiles>=0.21
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Dynamic: license-file

# langchain-agentx-cli

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

依托 [langchain-agentx-python](https://github.com/GoodMood2008/langchain_agentx_python) SDK，提供功能完整的终端编码助手。

## Installation

```bash
pip install langchain-agentx-cli
```

Requires Python 3.11+ and `ANTHROPIC_API_KEY` environment variable.

## Quick Start

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

# Start AgentX Code
agentx-code
```

### Environment Setup

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

### Command Options

```bash
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):

```bash
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](docs/design-docs/D25-mcp-cli-host-surface.html) / [实施计划](docs/exec-plan/mcp/mcp-cli-host-surface-2026-10-04.html) 分阶段落地，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](https://code.claude.com/docs/en/mcp) 一致。配置生效并完成会话接线后，会出现 `mcp__<server>__<tool>` 工具。

### 添加 server

```bash
# 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

```bash
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 的全局配置根下。

```bash
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`：

```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`。

### 会话里使用

```bash
cd ~/my-project
agentx-code
```

进入 REPL 后：

```text
/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`，按项目路径键——仓库本身无法自我批准）。
重置本项目的全部审批选择：

```bash
agentx-code mcp reset-project-choices
```

需要限制可用 MCP 工具时：

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

### 把 AgentX 自己暴露成 MCP Server

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

```bash
# 以 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](docs/design-docs/D25-mcp-cli-host-surface.html) · 实施计划：[exec-plan](docs/exec-plan/mcp/mcp-cli-host-surface-2026-10-04.html)

## 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

```bash
# 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`

```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](docs/design-docs/D25-mcp-cli-host-surface.html) — `mcp *` 子命令、`/mcp`、与 SDK A26 / Claude Code 对齐
- [Tool naming SSOT](docs/guides/tool-naming-ssot.md) — RuntimeTool.name、GrantScope、MemoryToolKind 边界
- [Implementation Plans](docs/exec-plan/)
- [Design docs index](docs/design-docs/README.md)

> 历史：[D01 user_message](docs/design-docs/tools/D01-user-message-dual-output.md)（BriefTool 已移除，仅作归档）

## License

Apache License 2.0
