CodingClaw Agent

一个面向本地开发工作流的 personal coding agent，适合想从 0 开始理解 Agent、工具调用、MCP、RAG、CLI / Web UI 的同学上手。

CodingClaw 不是“只会聊天”的 demo，而是一个尽量贴近真实开发过程的 Python agent 项目：能读写工作区、调用工具、接入 OpenAI-compatible 模型、连接 MCP server、保存会话、支持本地 RAG，并同时提供 CLI、JSON-RPC 和 Web UI。

Demo

轻量演示预览：

界面预览：

Why This Project

如果你刚开始学 agent，这个项目比较适合拿来拆解和练手：

• local-first：数据默认保存在本地目录，便于理解 session、logs、artifacts、RAG 索引这些真实组件。
• easy to read：核心代码按 agent / models / tools / storage / interfaces / mcp / rag / skills 分层，适合顺着目录学习。
• practical：不是只有 prompt 拼接，还包含权限确认、上下文规划、会话持久化、工具执行和导出。
• hackable：你可以很容易加自己的 skill、MCP server、provider 或工具。

What It Can Do

• 单 agent 编码工作流
• OpenAI-compatible provider 接入
• CLI、JSON-RPC over stdin/stdout、Web UI
• 内置工具与权限确认机制
• MCP client，支持接入外部工具服务器
• skills 加载与 prompt 模板
• 本地 JSONL 会话、导出与日志
• 本地 RAG 管线，支持 Chroma 与离线 fallback

Quick Start

python -m venv .venv
.venv\Scripts\activate
pip install -e .
codingclaw --help

或者直接用仓库里的启动脚本：

start-cli.bat
start-web.bat

启动 CLI：

codingclaw

单次提问：

codingclaw --prompt "Analyze this repository and explain the architecture"

启动 Web UI：

codingclaw --mode web

常用查看命令：

codingclaw models
codingclaw tools
codingclaw skills
codingclaw sessions

Good For Beginners

如果你是刚接触 Agent 的同学，可以重点看这几块：

1. app/agent/runner.py 整个 agent 的主流程，适合先理解“收到用户消息之后系统做了什么”。
2. app/tools/builtins.py 看工具是怎么定义、怎么执行、哪些操作需要确认。
3. app/mcp/client.py 看 MCP server 怎么接入。
4. app/skills/loader.py 看 skills 怎么触发和加载。
5. app/interfaces/cli/main.py 与 app/interfaces/http.py 看同一套 agent 能怎样挂到 CLI 和 Web 上。

Example Assets

• Sample skills: examples/skills/
• Sample MCP servers:
  • examples/mcp/workspace_inspector_server.py
  • examples/mcp/repo_fingerprint_server.py
  • examples/mcp/github_server.py
• Example config: example.config.json

Suggested Learning Path

1. 先跑起来 CLI，确认整个项目能工作。
2. 再读 runner -> tools -> models -> storage 这条主链路。
3. 接着自己加一个小工具，或者改一个 skill。
4. 最后尝试接入一个 MCP server 或自己的 provider。

Project Structure

app/
  agent/         # Agent main loop, context planning, summaries, flow
  integrations/  # External integrations
  interfaces/    # CLI / HTTP / RPC interfaces
  mcp/           # MCP client
  models/        # Model providers
  rag/           # Retrieval pipeline
  skills/        # Skill loading
  storage/       # Sessions, logs, exports, artifacts
  tools/         # Built-in tools and permissions
  types.py       # Shared typed structures
examples/
tests/
ui/

Roadmap Ideas

• 更完整的多 agent / planner 能力
• 更丰富的工具生态和更细粒度权限控制
• 更顺手的 Web UI 使用体验
• 更适合初学者的 demo tasks 和 walkthrough
• 更完整的 benchmark / examples / tutorial 内容

如果你对其中某一项感兴趣，欢迎提 issue 或直接发 PR。

Contributing

欢迎任何形式的参与：

• 提 bug
• 提改进建议
• 补初学者教程
• 增加 example skills / MCP servers
• 优化 README、文档或 Web UI 体验

可以先看 CONTRIBUTING.md。

Why Star This Repo

如果这个项目帮你更快理解了下面任何一个关键词，欢迎点个 star：

• AI coding agent
• agent tool calling
• MCP (Model Context Protocol)
• OpenAI-compatible models
• local-first agent architecture
• Python agent learning project

这会帮助更多刚开始学 agent 的朋友更容易发现这个项目。

Star History