代码模式代理

一个配备执行工具的Claude代理，该工具提供对文件操作、系统命令和MCP工具的程序化访问。其特点包括实时输入的交互模式、持久的执行上下文，以及与多个MCP服务器的无缝集成。

特点/特性

交互模式实时命令输入，使用Escape键隐藏/显示输入提示
执行工具在多次执行之间保持上下文运行JavaScript代码
内置函数读取、写入、编辑、全局搜索、文本搜索、Bash（一种Unix/Linux shell编程语言）、列出文件（LS）、网页获取、网页搜索、待办事项写入
MCP集成Glootie、Playwright 和 Vexify 工具作为函数提供
持久上下文在同一会话内的多次执行调用中，变量保持持久性
信号处理支持适当的Ctrl-C操作以实现优雅关闭
语法高亮着色的代码块和格式化的输出
拓展思维10,000个代币的思考预算，支持实时流处理

安装

npm install -g codemode-agent

或者使用 npx（无需安装）：

npx codemode-agent --agent "Your task here"

使用方法/用途

CodeMode支持两种模式： 代理模式 （交互式）和 MCP 服务器模式。

代理模式（交互式）

使用执行工具运行Claude代理以完成自主任务：

# Interactive mode (default)
codemode-agent --agent "Create a React component"

# Single execution mode (non-interactive)
codemode-agent --agent "Fix bugs" --no-interactive

# Using npx
npx codemode-agent --agent "Your task here"

交互模式功能

随时输入开始输入以自动显示输入提示
Esc键按 Esc 键隐藏输入提示
Ctrl-C随时优雅退出
流式输出实时观察代理的思考和工作过程

MCP服务器模式

启动提供执行工具的MCP服务器：

# Start MCP server
codemode-agent --mcp

# Using npx
npx codemode-agent --mcp

# Disable external MCP servers (built-in tools only)
codemode-agent --mcp --nomcp

在您的Claude桌面配置中添加：

{
  "mcpServers": {
    "codeMode": {
      "command": "npx",
      "args": ["codemode-agent", "--mcp"]
    }
  }
}

示例

基本文件操作

# Create a file
codemode-agent --agent "Create a file called test.txt with content 'Hello World'"

# Search code
codemode-agent --agent "Find all JavaScript files and count the lines of code"

# Edit files
codemode-agent --agent "Replace all console.log with logger.info in src/"

网页自动化

# Navigate and extract data
codemode-agent --agent "Navigate to example.com and get the page title"

# Screenshot capture
codemode-agent --agent "Take a screenshot of github.com"

# Form automation
codemode-agent --agent "Fill out the contact form on example.com"

代码分析

# Semantic search
codemode-agent --agent "Find all authentication-related functions"

# AST pattern matching
codemode-agent --agent "Find all useState calls with initial value of null"

# Codebase audit
codemode-agent --agent "List all TODO comments with their locations"

可用功能

文件操作

读取(path, 偏移量?, 限制?) - 读取文件内容，可选择行范围
写入（路径，内容） - 写入或覆盖文件内容
编辑路径（path），将旧字符串（oldString）替换为新字符串（newString），replaceAll?（是否全部替换） - 在文件中精确替换字符串
Glob(模式, 路径?, 作为数组?) - 查找匹配通配符模式的文件（默认返回字符串，若设置 as_array=true 则返回 JSON 数组）

搜索行动

Grep(模式, 路径?, 选项?) - 使用 ripgrep 搜索模式

- 选项： {glob, type, output_mode, '-i', '-n', '-A', '-B', '-C', multiline, head_limit}

系统操作

执行Bash命令（命令, 描述?, 超时时间?） - 执行shell命令
\LS(path?, show_hidden?, recursive?, files_only?)\ 翻译成中文为：\列出文件（路径?, 显示隐藏文件?, 递归?, 仅文件?）\ - 列出目录内容

网络运营

WebFetch(url, 提示) - 获取并分析网页内容
WebSearch(查询词, 允许的域名?, 禁止的域名?) - 在网上搜索

任务管理

TodoWrite（所有任务） - 编写和管理待办事项列表

- 格式： [{content, status, activeForm}] - 状态： 'pending' | 'in_progress' | 'completed'

MCP 工具

所有MCP工具均可通过命名空间函数访问。请使用 serverName.toolName(params) 格式。

Glootie（代码执行与分析）

\glootie.execute(code, runtime?, workingDirectory?, timeout?)\ 翻译成中文是：“执行代码，可选参数包括运行时环境、工作目录和超时时间” - 在不同的运行时环境中执行代码
\glootie.ast_tool(operation, workingDirectory, pattern, ...)\ 翻译成中文为：\glootie AST工具（操作, 工作目录, 模式, ...)\。这里，“AST”通常指的是“Abstract Syntax Tree”（抽象语法树），但具体含义可能根据上下文有所不同。在中文中，我们通常直接保留“AST”以指代这一概念，或者根据上下文翻译为更具体的术语（如果有的话）。在这个翻译中，我选择了直接保留“AST”以保持术语的一致性 - AST（抽象语法树）模式匹配用于代码结构搜索
\glootie.caveat(workingDirectory, action, text?, id?)\ 翻译成中文可以是：“在工作目录下，对操作发出警告（或注意事项），可选文本说明，可选标识符”。不过，为了更贴合中文表达习惯，也可以稍作调整为：“在指定工作目录中，针对某操作发出警告（或注意事项），可附带文本说明及标识符”。这里的 \workingDirectory\、\action\、\text?\、\id?\ 分别对应工作目录、操作、可选文本说明、可选标识符 - 管理技术上的注意事项和限制

Playwright（浏览器自动化）

\playwright.browser_navigate(url)\ 翻译成中文是：“使用 Playwright 导航到指定 URL” - 导航到URL
\playwright.browser_snapshot()\ 翻译成中文是：“Playwright 浏览器快照” - 捕获无障碍性快照
\playwright.browser_click(element, ref)\ 翻译成中文是：“使用 Playwright 点击浏览器中的元素（element），参考（ref）”。不过，这里的“ref”可能是一个特定上下文中的参数或引用，如果它没有特定的含义，也可以简化为“使用 Playwright 点击浏览器中的元素” - 点击元素
\playwright.browser_type(element, ref, text, slowly?, submit?)\ 的中文翻译可以是：“根据元素、引用、文本（以及是否缓慢、是否提交）来选择浏览器类型”。不过，这里的“slowly?”和“submit?”作为参数，具体含义可能需要根据上下文来确定，因为它们不是标准的中文表达。在中文中，我们可能会更具体地描述它们，比如“是否缓慢执行”或“是否提交表单”，但在这里为了保持原参数的简洁性，直接翻译为“是否缓慢”和“是否提交”也是可以接受的 - 在元素中输入文本
\playwright.browser_evaluate(function, element?, ref?)\ 翻译成中文是：“在浏览器上下文中执行函数，可选参数：元素(element)和引用(ref)”。不过，这里的“element?”和“ref?”表示这些参数是可选的，即在调用时可以不提供。所以，更自然的中文表达可能是：“在浏览器中执行给定函数，可选地传入元素和引用” - 在浏览器中执行JavaScript
\playwright.browser_take_screenshot(element?, ref?, filename?, type?, fullPage?)\ 翻译成中文为：\playwright（用于浏览器操作的库/工具）.browser_take_screenshot(元素?, 引用?, 文件名?, 类型?, 全页截图?)\。不过，为了更自然地表达，我们可以稍作调整，翻译为：“使用 Playwright 的浏览器功能截取屏幕截图（可选参数：元素、引用、文件名、类型、全页截图）” - 截图
\playwright.browser_close()\ 翻译成中文是：关闭浏览器 - 关闭浏览器
\playwright.browser_resize(width, height)\ 翻译为中文是：“调整浏览器窗口大小至指定宽度和高度” - 调整浏览器窗口大小
\playwright.browser_console_messages(onlyErrors?)\ 翻译成中文是：“获取浏览器控制台消息（仅错误？）” - 获取控制台消息
\playwright.browser_handle_dialog(accept, promptText?)\ 的中文翻译是：“处理浏览器对话框（接受或输入提示文本）”。不过，这里的翻译为了更贴近原句的结构和语境，可以稍作调整为：“使用 playwright 处理浏览器对话框（接受或输入提示文本）”。但通常我们会简化为：“使用 playwright 处理浏览器对话框，可选择接受或输入提示文本” - 处理对话框
\playwright.browser_file_upload(paths?)\ 翻译为中文是：“在浏览器中上传文件（路径可选？）”。不过，这里的“paths?”可能表示的是路径参数是可选的，或者是一个占位符，表示可以传递文件路径。在中文表达中，我们可能会更明确地表达这一点，比如：“在浏览器中上传文件，路径可选”。但直接翻译保持原样的话，就是“在浏览器中上传文件（路径可选？）” - 上传文件
\playwright.browser_fill_form(fields)\ 翻译成中文是：\使用 Playwright 在浏览器中填写表单（字段）\ - 填充多个表单字段
\playwright.browser_press_key(key)\ 翻译成中文是：“使用 Playwright 按下浏览器中的某个键” - 按下键盘键
\playwright.browser_navigate_back()\ 翻译成中文是：使用 Playwright 执行浏览器后退操作 - 返回导航
\playwright.browser_network_requests()\ 翻译为中文是：“Playwright 浏览器网络请求” - 获取网络请求
\playwright.browser_hover(element, ref)\ 翻译为中文是：在浏览器中悬停（鼠标）于指定元素上（相对于参考元素） - 将鼠标悬停在元素上
\playwright.browser_drag(startElement, startRef, endElement, endRef)\ 翻译为中文是：“在浏览器中执行拖动操作，从起始元素（或参考点）开始，到结束元素（或参考点）结束” - 拖放
\playwright.browser_select_option(element, ref, values)\ 翻译成中文是：\在浏览器中为指定元素选择选项（element），参考（ref），选择值（values）\。不过，这里的“ref”在中文语境下可能不太常见，具体翻译可能需要根据上下文调整，但基本意思是为某个元素（通过引用或标识）选择一组值作为选项 - 选择下拉菜单选项
\playwright.browser_tabs(action, index?)\ 可以翻译为：“在浏览器选项卡中执行操作（action），可选指定选项卡索引（index）”。不过，为了更贴合中文表达习惯，也可以稍作调整为：“在浏览器的选项卡中执行指定操作（action），可选参数index用于指定选项卡索引” - 管理浏览器标签页
\playwright.browser_wait_for(text?, textGone?, time?)\ 翻译成中文是：“Playwright 浏览器等待函数（可选参数：文本、文本消失、时间）”。不过，为了更自然地表达，我们也可以将其翻译为：“Playwright 浏览器等待特定文本/消失或指定时间”。这里的翻译根据上下文可能略有不同，但基本意思是指 Playwright 提供的一个浏览器等待功能，可以根据特定文本的出现/消失或指定的时间来进行等待 - 等待条件满足

Vexify（语义代码搜索）

\vexify.search_code(query, top_k?, include_content?)\ 翻译成中文是：“vexify 搜索代码（查询，返回顶部k个结果？，是否包含内容？）”。不过，为了更自然地表达，我们可以稍作调整，翻译为：“vexify 搜索代码功能（根据查询，可选择返回前k个结果，可选择是否包含内容）” - 使用嵌入进行语义代码搜索

建筑

CodeMode由三个主要部分组成：

1. cli.js - 统一入口点

基于命令行标志进入代理模式或MCP服务器模式的路径。

2. agent.js - 交互式Claude代理

实时显示思考过程的流式响应
管理交互式输入，支持Escape键
处理信号中断（Ctrl-C）
以语法高亮格式输出
通过执行工具与MCP服务器集成

3. code-mode.js - MCP 服务器

将Claude的执行工具暴露出来
管理持久执行上下文
生成并管理子MCP服务器
处理所有进程的优雅关闭
将工具函数注入到JavaScript运行时中

4. execution-worker.js - 持久化工作线程

在多次调用之间保持执行上下文
处理与父进程的IPC（进程间通信）
管理变量持久性
响应关闭信号

5. interactive-mode.js - 输入处理程序

管理readline接口
处理键盘事件（输入、Esc键、Ctrl-C）
动态显示/隐藏输入提示
为代理执行排队命令

配置

创建 .codemode.json 配置MCP服务器：

{
  "mcpServers": {
    "builtInTools": {
      "command": "node",
      "args": ["built-in-tools-mcp.js"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "vexify": {
      "command": "npx",
      "args": ["-y", "vexify@latest", "mcp"]
    }
  }
}

配置文件按以下顺序搜索：

当前工作目录： ./.codemode.json
库目录： ./node_modules/codemode-agent/.codemode.json
用户主目录： ~/.claude/.codemode.json

持久执行上下文

在同一个会话内的多次执行调用中，变量会保持不变：

// First execute call
myVar = 42;
console.log(myVar);

// Second execute call (same session)
console.log(myVar);

用（某种方式）声明的变量 let， const，或者 var 不要坚持（使用某种方式）。使用直接赋值或 global.myVar 为了坚持不懈。

使用 clear_context() 重置执行上下文。

测试

运行测试套件：

npm test

对于全面集成测试：

# Start MCP server
node code-mode.js

# In another terminal
node test-builtin-tools.js

命令行标志

代理模式

--agent [task] - 以代理模式运行，可选初始任务
--no-interactive - 在非交互模式下运行单次执行

MCP 服务器模式

--mcp - 启动MCP服务器模式
--nomcp - 禁用外部MCP服务器（仅使用内置工具）

信号处理

CodeMode 正确处理中断信号：

Ctrl-C（SIGINT）优雅地关闭所有进程
SIGTERM（信号终止）工件服务器和MCP服务器的优雅关闭
Esc键在交互模式下隐藏输入提示

所有子进程（MCP服务器、执行工作进程）都会接收到适当的关闭信号并清理资源。

快捷键

交互模式

类型自动显示输入提示
逃脱隐藏输入提示并清除当前行
输入向代理提交命令
Ctrl-C（复制）退出应用程序

依赖项

@anthropic-ai/claude-agent-sdk - 代理框架和流处理
@modelcontextprotocol/sdk - MCP协议实现
chalk - 终端颜色和样式
highlight.js - 代码语法高亮
fast-glob - 文件模式匹配
chokidar - 文件系统监控
uuid - 唯一标识符生成
which - 命令解析
zod - 模式验证

故障排除

Ctrl-C 无法正常工作

如果按 Ctrl-C 无法中断执行，请确保您运行的是最新版本：

npm install -g codemode-agent@latest

MCP服务器超时

对于长时间运行的操作，超时时间设置为180秒。如果需要更长的时间：

编辑 execution-worker.js 并增加超时值 __callMCPTool。

变量未持久化

用（某种方式）声明的变量 let， const，或者 var 不要坚持。使用直接赋值：

// Won't persist
let myVar = 42;

// Will persist
myVar = 42;

// Will persist
global.myVar = 42;

终端颜色未显示

确保您的终端支持ANSI颜色。对于Windows系统，请使用Windows Terminal或WSL（Windows Subsystem for Linux）。

版本

当前版本： 2.0.38

见 CHANGELOG.md 翻译为中文是：“版本更新日志文件” 以查看完整版本历史和最近更改。

许可证

麻省理工学院（MIT）

作者

割草机

做出贡献

欢迎贡献！请提交问题或拉取请求。

链接

MCP 文档

Codemode Agent

快速接入

详细介绍