@opencoder/code-tools

Professional code intelligence tools - 15 tools for search, editing, diagnostics, and analysis.

✨ Features

🔍 Code Search (6 tools)

• search_codebase - Semantic code search using AST analysis
• search_symbol - Find specific classes, functions, methods
• grep_code - Exact pattern matching with regex
• search_file - Locate files by name or glob pattern
• read_code - Intelligent file reading with context awareness
• extract_symbol - Extract complete symbol definitions

✏️ Code Editor (3 tools) ⭐

• search_replace - Precise code modifications with automatic backup
• create_code_file - Create new files with safety limits
• delete_code_file - Safe deletion with trash recovery

🔧 Code Diagnostics (3 tools)

• get_problems - Find lint, compile, and type errors
• run_tests - Execute test suites with auto-detection
• check_code_quality - Code quality metrics (complexity, duplication, size)

📊 Code Analysis (3 tools)

• analyze_dependencies - Dependency graphs and coupling analysis
• code_statistics - Code metrics and language distribution
• analyze_architecture - Project structure and pattern analysis

🚀 Installation

From npm (Recommended)

openclaw plugin install @opencoder/code-tools
openclaw gateway restart

From Local Tarball

# Download or build the package
npm pack @opencoder/code-tools

# Install
openclaw plugin install ./opencoder-code-tools-1.0.0.tgz
openclaw gateway restart

From GitHub

openclaw plugin install github:opencoder/opencoder
openclaw gateway restart

📦 External Dependencies

Some tools require external dependencies for full functionality:

Code Complexity Analysis (lizard)

pip3 install lizard

Code Duplication Detection (jscpd)

npm install -g jscpd

Code Statistics (cloc)

# Ubuntu/Debian
sudo apt install cloc

# macOS
brew install cloc

# Windows (with Chocolatey)
choco install cloc

⚙️ Configuration

Automatic Setup

On installation, the plugin automatically:

1. ✅ Registers all 15 tools in the tool whitelist
2. ✅ Applies optimized system prompt for better tool usage
3. ✅ Checks external dependencies

Skip Automatic Configuration

# Skip system prompt update
export OPENCLAW_SKIP_PROMPT_OVERRIDE=1

# Skip dependency check
export OPENCLAW_SKIP_DEPS_CHECK=1

openclaw plugin install @opencoder/code-tools

Manual Configuration

Edit ~/.openclaw/openclaw.json:

{
  "tools": {
    "allow": [
      "search_codebase",
      "search_symbol",
      "grep_code",
      "search_file",
      "read_code",
      "extract_symbol",
      "search_replace",
      "create_code_file",
      "delete_code_file",
      "get_problems",
      "run_tests",
      "check_code_quality",
      "analyze_dependencies",
      "code_statistics",
      "analyze_architecture"
    ]
  }
}

📖 Usage

Example: Code Analysis

Ask OpenClaw to analyze your project:

Analyze the architecture of /home/user/my-project

The AI will automatically use:

• analyze_architecture for structure analysis
• code_statistics for metrics
• search_codebase for understanding

Example: Code Modification

Fix the bug in src/auth/login.js where token validation fails

The AI will:

1. Read the file with read_code
2. Fix it with search_replace
3. Check for errors with get_problems

Example: Quality Check

Check code quality of /home/user/project

Returns:

• Cyclomatic complexity (lizard)
• Code duplication (jscpd)
• Code statistics (cloc)

🎯 Tool Selection Guide

| Task | Tool | When to Use | |------|------|-------------| | Understand functionality | search_codebase | "How does X work?" | | Find specific code | search_symbol | "Find class Foo" | | Pattern matching | grep_code | "Find all TODOs" | | Modify code | search_replace | "Fix/change/update" | | Create new file | create_code_file | "Create/add new file" | | Delete file | delete_code_file | "Remove/delete file" | | Check errors | get_problems | After code changes | | Run tests | run_tests | Before committing | | Quality metrics | check_code_quality | Code review |

🔒 Safety Features

• Automatic Backup: search_replace creates backups in .openclaw-backups/
• Trash Recovery: delete_code_file moves to .openclaw-trash/ instead of permanent delete
• File Size Limit: Enforces MAX_FILE_LINES (1000 lines) to prevent huge files
• Syntax Validation: Optional ESLint/py_compile checks after modifications
• Local Only: All processing is local, code never leaves your machine

📊 System Prompt Optimization

This plugin includes an optimized system prompt that:

1. Prioritizes code editor tools - Marks them as "PRIMARY TOOLS"
2. Provides usage scenarios - 12 explicit use cases for each editor tool
3. Enforces safety rules - 5 mandatory safety guidelines
4. Improves parameter handling - Detailed parameter documentation

Effect

AI will:

• ✅ Use search_replace more frequently (instead of manual rewriting)
• ✅ Create new files with create_code_file
• ✅ Delete files safely with delete_code_file
• ✅ Make fewer unnecessary tool calls

🛠️ Development

Build from Source

# Clone the repository
git clone https://github.com/opencoder/opencoder.git
cd opencoder

# Install dependencies
npm install

# Build
npm run build

# Package
npm pack

# Install locally
openclaw plugin install ./opencoder-code-tools-1.0.0.tgz

Run Tests

npm test
npm run test:watch

Lint & Format

npm run lint
npm run format

📝 Changelog

v1.0.0 (2026-05-09)

• 🎉 Initial release
• ✅ 15 code tools (search, editor, diagnostics, analysis)
• ✅ Optimized system prompt
• ✅ Automatic configuration
• ✅ Safety features (backup, trash)
• ✅ External dependency checks

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📚 Documentation

• Full Documentation
• API Reference
• Configuration Guide
• Troubleshooting
• Contributing Guide

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built on the OpenClaw plugin system
• Uses lizard for complexity analysis
• Uses jscpd for duplication detection
• Uses cloc for code statistics

📧 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs.openclaw.ai

📕 中文 README

@opencoder/code-tools 中文文档

专业的代码智能工具套件 - 包含 15 个用于搜索、编辑、诊断和分析的工具。

✨ 功能特性

🔍 代码搜索工具（6 个）

• search_codebase - 基于 AST 分析进行语义代码搜索
• search_symbol - 查找特定的类、函数、方法
• grep_code - 使用正则表达式进行精确模式匹配
• search_file - 根据文件名或 glob 模式定位文件
• read_code - 智能读取代码文件
• extract_symbol - 提取符号的完整定义和上下文

✏️ 代码编辑器工具（3 个）⭐

• search_replace - 精确的代码替换，支持自动备份
• create_code_file - 创建新文件，支持行数限制
• delete_code_file - 安全删除文件到回收站

🔧 代码诊断工具（3 个）

• get_problems - 查找 lint、编译和类型错误
• run_tests - 运行测试套件（自动检测测试框架）
• check_code_quality - 代码质量指标（复杂度、重复度、大小）

📊 代码分析工具（3 个）

• analyze_dependencies - 依赖图和循环依赖分析
• code_statistics - 代码指标和语言分布统计
• analyze_architecture - 项目结构分析

🚀 安装方式

npm 安装（推荐）

openclaw plugin install @opencoder/code-tools
openclaw gateway restart

本地包安装

# 下载或构建包
npm pack @opencoder/code-tools

# 安装
openclaw plugin install ./opencoder-code-tools-1.0.0.tgz
openclaw gateway restart

从 GitHub 安装

openclaw plugin install github:opencoder/opencoder
openclaw gateway restart

📦 外部依赖

部分工具需要安装外部依赖才能发挥完整功能：

代码复杂度分析（lizard）

pip3 install lizard

代码重复检测（jscpd）

npm install -g jscpd

代码统计（cloc）

# Ubuntu/Debian
sudo apt install cloc

# macOS
brew install cloc

# Windows（使用 Chocolatey）
choco install cloc

⚙️ 配置说明

自动设置

安装时，插件会自动：

1. ✅ 在工具白名单中注册所有 15 个工具
2. ✅ 应用优化的系统提示（system prompt）
3. ✅ 检查外部依赖

跳过自动配置

# 跳过系统提示更新
export OPENCLAW_SKIP_PROMPT_OVERRIDE=1

# 跳过依赖检查
export OPENCLAW_SKIP_DEPS_CHECK=1

openclaw plugin install @opencoder/code-tools

手动配置

编辑 ~/.openclaw/openclaw.json：

{
  "tools": {
    "allow": [
      "search_codebase",
      "search_symbol",
      "grep_code",
      "search_file",
      "read_code",
      "extract_symbol",
      "search_replace",
      "create_code_file",
      "delete_code_file",
      "get_problems",
      "run_tests",
      "check_code_quality",
      "analyze_dependencies",
      "code_statistics",
      "analyze_architecture"
    ]
  }
}

📖 使用示例

示例 1：代码分析

向 OpenClaw 提问：

分析 /home/user/my-project 的项目架构

AI 会自动使用：

• analyze_architecture 进行结构分析
• code_statistics 进行指标统计
• search_codebase 进行理解

示例 2：代码修改

修复 src/auth/login.js 中 token 验证失败的 bug

AI 将：

1. 使用 read_code 读取文件
2. 使用 search_replace 进行修复
3. 使用 get_problems 检查错误

示例 3：质量检查

检查 /home/user/project 的代码质量

返回：

• 圈复杂度（lizard）
• 代码重复度（jscpd）
• 代码统计（cloc）

🎯 工具选择指南

| 任务 | 工具 | 使用时机 | |------|------|----------| | 理解功能 | search_codebase | "X 是如何工作的？" | | 查找具体代码 | search_symbol | "查找类 Foo" | | 模式匹配 | grep_code | "查找所有 TODO" | | 修改代码 | search_replace | "修复/修改/更新" | | 创建新文件 | create_code_file | "创建/添加新文件" | | 删除文件 | delete_code_file | "移除/删除文件" | | 检查错误 | get_problems | 代码变更后的检查 | | 运行测试 | run_tests | 提交代码前 | | 质量指标 | check_code_quality | 代码审查 |

🔒 安全特性

• 自动备份：search_replace 在 .openclaw-backups/ 中创建备份
• 回收站恢复：delete_code_file 将文件移至 .openclaw-trash/ 而非永久删除
• 文件大小限制：强制 MAX_FILE_LINES（1000 行）以防止大文件
• 语法验证：修改后支持 ESLint/py_compile 检查
• 本地处理：所有处理都在本地进行，代码不会离开您的机器

📊 系统提示优化

本插件包含优化的系统提示，能够：

1. 优先使用代码编辑器工具 - 标记为"MAIN TOOLS"
2. 提供使用场景 - 为每个编辑器工具提供 12 个明确的用例
3. 执行安全规则 - 5 条必须遵守的安全准则
4. 改进参数处理 - 详细的参数文档

效果

AI 将会：

• ✅ 更频繁使用 search_replace（而非手动重写文件）
• ✅ 使用 create_code_file 创建新文件
• ✅ 使用 delete_code_file 安全删除文件
• ✅ 减少不必要的工具调用

🛠️ 开发相关

从源码构建

# 克隆仓库
git clone https://github.com/opencoder/opencoder.git
cd opencoder

# 安装依赖
npm install

# 构建
npm run build

# 打包
npm pack

# 本地安装
openclaw plugin install ./opencoder-code-tools-1.0.0.tgz

运行测试

npm test
npm run test:watch

Lint 和格式化

npm run lint
npm run format

📝 更新日志

v1.0.0 (2026-05-09)

• 🎉 首次发布
• ✅ 15 个代码工具（搜索、编辑器、诊断、分析）
• ✅ 优化的系统提示
• ✅ 自动配置
• ✅ 安全特性（备份、回收站）
• ✅ 外部依赖检查

🤝 贡献指南

欢迎贡献！请阅读我们的 贡献指南。

1. 派生仓库
2. 创建设备分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m '添加 amazing 功能'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起拉取请求

📚 文档

• 完整文档
• API 参考
• 配置指南
• 故障排除
• 贡献指南

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

🙏 致谢

• 基于 OpenClaw 插件系统构建
• 使用 lizard 进行复杂度分析
• 使用 jscpd 进行重复度检测
• 使用 cloc 进行代码统计

📧 支持

• 问题反馈：GitHub Issues
• 讨论：GitHub Discussions
• 文档：docs.openclaw.ai