一个极简、可读、可 fork 的终端 AI coding agent —— 把 Claude Code 的核心思想用 ~1300 行纯 Python 写出来。

灵感来自极简教学型 coding agent("the nanoGPT of coding agents")的思路,并结合对 Claude Code 源码的架构分析。目标是教学与可 hack,而非生产级 —— 每一行都能在一个下午读完,每个设计决策都能追溯到具体代码。

特点一览:

• 🔁 完整的 Agent Loop —— 发消息 → 执行工具 → 回填结果 → 循环,直到任务完成
• ⚡ 读写分离并发 —— 连续的只读工具并行执行,写工具串行,避免竞态
• 🗜️ 三层上下文压缩 —— 窗口快满时按成本从低到高逐级压缩,尽量不丢早期决策
• 🔌 双后端可配置 —— 同时支持 Anthropic 与任意 OpenAI 兼容 API(OpenAI / DeepSeek / Ollama / Kimi / Qwen …)
• 🛡️ fail-closed 安全默认 + bash 危险命令门控
• 💾 会话保存 / 恢复,流式输出,REPL + 斜杠命令
• 🧪 零重依赖(仅 httpx),26 个单测全程 mock,不触真实 API

给它一句话需求,它会调用工具去读写文件、执行 shell、搜索代码,循环往复直到完成,然后向你汇报。

› 把 utils.py 里的 print 都换成 logging
⚙ grep  print
  utils.py:12:    print(f"start {name}")
  ...
⚙ edit_file  utils.py
  已修改 utils.py(替换 3 处)
已把 3 处 print 替换为 logging.info,并在文件顶部补了 import logging。

git clone git@github.com:wisdom-pan/minicoder.git
cd minicoder
pip install -e .                 # 或 pip install -e ".[dev]" 装测试依赖

export OPENAI_API_KEY=sk-xxx     # 见下方「配置」
minicoder                        # 进入 REPL,输入你的需求

复制 .env.example 为 .env 并填写,或直接用环境变量:

# OpenAI 兼容(OpenAI / DeepSeek / Ollama / Kimi / Qwen ...)
export MINICODER_PROVIDER=openai
export OPENAI_API_KEY=sk-xxx
export OPENAI_BASE_URL=https://api.openai.com/v1   # 换后端只改这里

# 或 Anthropic
export MINICODER_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-xxx

本地跑 Ollama:OPENAI_BASE_URL=http://localhost:11434/v1,API key 随便填。

minicoder                        # 进入 REPL
minicoder -p "创建 hello.py 打印 hello"   # 无头模式,执行单条后退出
minicoder --provider anthropic --model claude-sonnet-4-5

REPL 斜杠命令:

bash · read_file · write_file · edit_file(唯一文本匹配替换)· glob · grep · agent(子 agent,禁止递归)

pip install -e ".[dev]"
pytest          # 26 个单测,全程 mock provider,不触真实 API
ruff check .

minicoder/
├── config.py       # 环境变量 + .env 加载
├── prompt.py       # system prompt + git/项目上下文
├── providers.py    # Provider 抽象(OpenAI 兼容 + Anthropic),流式,重试
├── context.py      # 三层上下文压缩
├── session.py      # 会话持久化 + 路径防护
├── agent.py        # Agent Loop + 读写分离并发
├── cli.py          # REPL + 斜杠命令
└── tools/          # base + bash/read/write/edit/glob/grep/agent

为保持极简,以下 Claude Code 有、这里没做:MCP、Hook 系统、多 provider fallback 链、 Textual TUI、插件、team/swarm、LSP、web 工具、prompt 缓存优化、精确 token 计数(现用字符数/4 估算)。

MIT