codeAgent README

The project's README from github.com/Harvil1/codeAgent. As one markdown file: README.md.

CodeAgent

自学习 AI Agent 命令行工具——交互体验对标 claude code,Windows 优先,开箱即用。

Python 3.11+ License: MIT Platform

English | 简体中文

CodeAgent 是一个跑在终端里的 AI 编程助手:你用自然语言下指令,它读代码、改文件、跑命令、查资料,把活干完。它有自己的一套「长本事」机制——从对话轨迹里沉淀可复用的技能,越用越顺手。

🧭 这是一份手写的「中文版 claude code」

不是套壳,也不是翻译——是从交互界面到 Agent 主循环一行行手写出来的完整实现,注释全是中文:

✨ 特性

终端体验(对标 claude code)

模型与工具

安全防线

记忆与自学习

协作与自动化

上下文工程

🖥 界面一览

运行中的 CodeAgent

🚀 快速开始

前提:Python 3.11+ 和 uv(Python 包管理器)。

# 1) 安装 uv(已有可跳过)
#    Windows (PowerShell):  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
#    macOS / Linux:         curl -LsSf https://astral.sh/uv/install.sh | sh

# 2) 拉代码 + 装依赖
git clone https://github.com/Harvil1/codeAgent.git
cd codeAgent
uv sync

# 3) 配置 API key(二选一)
#    a) 环境变量——按所用厂商设置其一即可,程序会自动识别:
#       DEEPSEEK_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY /
#       OPENROUTER_API_KEY / ZHIPUAI_API_KEY(BIGMODEL_API_KEY 亦可)
#    b) 写入 ~/.codeAgent/settings.json 的 models.<名字>.api_key
#       (首次运行会自动生成默认配置文件,默认模型为 DeepSeek)

# 4) 跑起来
uv run python main.py              # 交互模式
uv run python main.py -c           # 自动恢复最近一次会话

提示:换模型 / 换厂商在会话里输 /model 按引导配置,或直接编辑 ~/.codeAgent/settings.json。

⌨️ 常用操作

会话内 40+ 个 slash 命令,常用如下:

命令 作用
/help 命令帮助
/model 切换 / 配置模型(按引导填厂商、key、端点)
/new /resume /sessions 新会话 / 恢复 / 会话列表
/rewind 回溯到某个 checkpoint 重来
/skills /plugin 管理技能 / 插件市场
/memory 查看维护长期记忆
/permission /sandbox /approved 权限模式 / 沙箱开关 / 已批准命令白名单
/doctor 自诊断(配置、网络、组件健康检查)
/plan 计划模式:先出方案批准再动手
/stats /usage /trace 花费统计 / 用量 / 调用链追踪

⚙️ 配置与数据

运行时数据统一放在 ~/.codeAgent/(环境变量 CODEAGENT_HOME 可覆盖,测试 / 多配置隔离用):

路径 内容
settings.json 全部配置(默认值单一源头在代码里,落盘深合并,手改安全)
sessions.db/ 会话持久化(JSONL)
MEMORY.md + 记忆库 长期记忆索引与正文
skills/ 用户技能
plugins/ 插件(含官方市场 claude-plugins-official)
logs/ 运行日志(滚动,5MB × 3)

🏗 架构一览

调用链一句话:main.py(点火:控制台编码、终端自举)→ cli.main → run_interactive(REPL + slash 命令 + RuntimeContext 装配)→ AIAgent.run_conversation(主循环心脏)。

主循环每轮:组装消息(注入后台 / 定时 / 团队 / 计划等临时消息)→ 上下文压缩 → 刷新工具集 → 调 LLM → 分发工具调用,模型不再要工具即收尾。

子系统 模块
LLM llm_client.py(OpenAI 兼容 / Anthropic 协议)、aux_llm.py(辅助小模型路由)
记忆 memory_store.py、memory_retriever.py
上下文 context_compressor.py(分级压缩)、context_pipeline.py
子代理 / 团队 tools/delegate_tool.py、agent/team/
工作流 workflow_engine.py + workflow_journal.py
技能 ~/.codeAgent/skills/ + agent/skill_learning/(自学习)
安全 bash_injection.py、ssrf_guard.py、secret_scanner.py、sandbox_runner.py、permission.py
持久化 session_store.py、task_store.py、hooks.py

🧪 开发

uv run python scripts/verify.py   # 60+ 项回归检查(改完代码先跑这个)
uv run ruff check .               # lint

❓ FAQ

📄 许可证

MIT © 2026 Harvil1

codeAgent (Harvil1/codeAgent)

Searching Database…

What is this?CodeAgent is an open-source AI coding assistant that lives in your terminal: you give it natural-language instructions and it reads your code, edits files, runs commands, searches for information, and finishes the task.
Is this just a wrapper around Claude Code, or a separate implementation?It is not a wrapper or translation — the whole interaction loop and agent core were hand-written line by line, with fully Chinese-commented source code, explicitly built to mirror the Claude Code experience from scratch.
How do I get it running?You need Python 3.11+ and the uv package manager installed first; once running, you configure your model provider inside a session with /model or by editing ~/.codeAgent/settings.json.
Does it work on macOS and Linux, or is it Windows-only?It is developed and validated Windows-first; Linux is supported (including an optional bwrap sandbox), while macOS is expected to work in theory but hasn't been fully tested yet.
Do I need a DeepSeek API key, or can I use other providers?DeepSeek is just the default — any OpenAI-compatible endpoint or Anthropic-protocol endpoint works, switchable via /model or settings.json, with keys supported through environment variables or config files.
What is the self-learning skill system?CodeAgent observes its own conversation traces and distills reusable 'skills' from them, either heuristically or via an auxiliary model, so it gets better at your codebase and workflows the more you use it.
What safety guardrails are built in?It requires approval for destructive commands and writes outside a whitelist, detects shell injection patterns, scans for secrets before they get written to files or memory, guards against SSRF, and on Linux can run commands inside a bwrap sandbox.
Can it coordinate multiple agents on bigger tasks?Yes — it supports synchronous or background subagent delegation with git-worktree isolation, plus a full coordinator/worker team mode with a message bus and mailboxes for larger jobs.
Creator
Harvil1
Size
5.3 MB
Stars
884
Updated
CommitOct 14
Age
16d
Commits · 90 Days