Skip to content

README.md

Latest commit

 

History

History
175 lines (128 loc) · 4.81 KB

README.md

File metadata and controls

175 lines (128 loc) · 4.81 KB

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。

CodingClaw Web UI preview

Demo

轻量演示预览：

CodingClaw demo preview

界面预览：

CodingClaw CLI preview

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

Star History Chart