codenano

从 Claude Code 提取的轻量级 AI 编码代理 SDK。

基于Claude Code 的生产架构重新构建。保留所有能力，去除冗余。开源、完全可定制、生产就绪。

💡 基于 Claude Code — 与驱动 Anthropic 官方编码测试引擎相同，现在作为独立 SDK 提供。

English | 简体中文

为什么选择 codenano？

🚀 Claude Code 的核心，轻 96%

• ~6,500 行纯粹、专注的代码
• Claude Code：150,000+ 行（IDE 集成、UI 等）
• 相同的代理引擎，零开销

⚡ Claude Code 能做的，你也能做

npm install codenano

60 秒内构建你自己的 Claude Code。无需 IDE。无限制。

🎯 经过实战检验的架构

从 Claude Code 的生产引擎中提取。大规模验证，为开发者优化。

---

快速开始

3 行代码运行你的第一个代理：

import { createAgent, coreTools } from 'codenano'

const agent = createAgent({
  model: 'claude-sonnet-4-6',
  tools: coreTools(),  // Read, Edit, Write, Glob, Grep, Bash
})

const result = await agent.ask('读取 package.json 并总结它')
console.log(result.text)

就是这样。无需复杂设置。无需配置地狱。只有纯粹的生产力。

流式输出？内置。

for await (const event of agent.stream('这里有什么文件？')) {
  if (event.type === 'text') process.stdout.write(event.text)
}

多轮对话？简单。

const session = agent.session()
await session.send('读取 main.ts')
await session.send('现在解释它做什么')

会话持久化？内置。

const agent = createAgent({
  model: 'claude-sonnet-4-6',
  tools: coreTools(),
  persistence: { enabled: true },  // 保存到 ~/.agent-core/sessions/
})

const session = agent.session()
console.log(session.id)  // 保存这个 UUID
await session.send('分析代码库')

// 之后 — 从上次中断处恢复
const resumed = agent.session(session.id)
await resumed.send('我们发现了什么？')

跨会话记忆？自动。

const agent = createAgent({
  model: 'claude-sonnet-4-6',
  memory: {
    autoLoad: true,           // 将已保存的记忆注入系统提示
    extractStrategy: 'auto',  // 每轮结束后自动提取记忆
  },
})

// 代理从对话中学习，并在会话间记忆：
// - 用户偏好和角色
// - 工作方式反馈（避免什么/重复什么）
// - 项目上下文和决策
// - 外部系统的指引

记忆以带有 frontmatter 的 markdown 文件存储，由 MEMORY.md 索引。也可以直接使用独立 API：

import { saveMemory, scanMemories, loadMemoryIndex } from 'codenano'

saveMemory({
  name: 'user_role',
  description: '用户是后端工程师',
  type: 'user',
  content: '擅长 Go 和 Python，刚接触 React',
}, '/path/to/memory')

const memories = scanMemories('/path/to/memory')

存储路径

记忆和会话持久化都有合理的默认路径，也支持自定义。目录不存在时会自动创建。

功能	默认路径	自定义配置
记忆	~/.agent-core/memory/<cwd-hash>/	memory.memoryDir
会话	~/.agent-core/sessions/	persistence.storageDir

// 使用默认路径 — 零配置
const agent = createAgent({
  model: 'claude-sonnet-4-6',
  memory: { autoLoad: true, extractStrategy: 'auto' },
  persistence: { enabled: true },
})

// 或指定自定义路径
const agent = createAgent({
  model: 'claude-sonnet-4-6',
  memory: { memoryDir: './my-project/memory', autoLoad: true },
  persistence: { enabled: true, storageDir: './my-project/sessions' },
})

成本追踪？自动。

每个 Result 都包含 costUSD — 基于模型定价的 API 费用估算。

const result = await agent.ask('解释这段代码')
console.log(`费用: $${result.costUSD.toFixed(4)}`)  // 例如 $0.0047

独立 API 用于预算管理：

import { CostTracker, calculateCostUSD } from 'codenano'

const tracker = new CostTracker()
tracker.add('claude-sonnet-4-6', result.usage)
console.log(`总计: $${tracker.summary.totalUSD.toFixed(4)}`)

Git 集成？内置。

自动检测 git 仓库状态，注入系统提示：

import { getGitState, buildGitPromptSection } from 'codenano'

const state = getGitState()
// { isGit: true, branch: 'main', commitHash: 'abc123...', isClean: false, ... }

const section = buildGitPromptSection(state)
// "- Is a git repository: true\n- Current branch: main\n..."

生命周期钩子？8 个。

在每个生命周期点观察和控制代理行为：

const agent = createAgent({
  model: 'claude-sonnet-4-6',
  tools: coreTools(),

  onTurnStart: ({ turnNumber }) => console.log(`第 ${turnNumber} 轮`),

  // 阻止危险工具
  onPreToolUse: ({ toolName, toolInput }) => {
    if (toolName === 'Bash' && toolInput.command?.includes('rm -rf'))
      return { block: '破坏性命令已被阻止' }
  },

  onPostToolUse: ({ toolName, output }) => console.log(`${toolName}: ${output.slice(0, 50)}`),
  onCompact: ({ messagesBefore, messagesAfter }) => console.log(`压缩: ${messagesBefore} → ${messagesAfter}`),
  onError: ({ error }) => console.error(error.message),
  onMaxTurns: () => console.warn('达到最大轮次'),
})

所有钩子都是尽力执行 — 钩子中的错误不会导致代理崩溃。

子代理生成？一个函数。

import { createAgent, createAgentTool, coreTools } from 'codenano'

const config = { model: 'claude-sonnet-4-6', tools: coreTools() }
const agentTool = createAgentTool(config)

const agent = createAgent({
  ...config,
  tools: [...coreTools(), agentTool],  // 模型现在可以生成子代理
})

上下文分析？就绪。

分析对话上下文，识别压缩机会：

import { analyzeContext, classifyTool } from 'codenano'

const analysis = analyzeContext(session.history)
// { toolCalls: 5, duplicateFileReads: { '/a.ts': 3 }, collapsibleResults: 4, ... }

classifyTool('Grep')   // 'search'
classifyTool('Bash')   // 'execute'

MCP 协议？支持。

连接任何 MCP server，使用其工具：

import { createAgent, connectMCPServers } from 'codenano'

const { tools, connections } = await connectMCPServers([
  { name: 'github', transport: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'] },
])

const agent = createAgent({ model: 'claude-sonnet-4-6', tools })
const result = await agent.ask('列出未关闭的 issue')

自定义工具

import { defineTool } from 'codenano'
import { z } from 'zod'

const readFile = defineTool({
  name: 'ReadFile',
  description: '从磁盘读取文件',
  input: z.object({ path: z.string() }),
  execute: async ({ path }) => fs.readFileSync(path, 'utf-8'),
  isReadOnly: true,
})

const agent = createAgent({
  model: 'claude-sonnet-4-6',
  tools: [readFile],
})

---

codenano vs Claude Code

相同的引擎。不同的理念。

特性	codenano	Claude Code
基于	Claude Code 核心	Anthropic 官方产品
代码行数	~6,500（仅核心）	150,000+（完整应用）
包含内容	代理引擎	引擎 + IDE + UI
设置时间	< 1 分钟	安装 IDE 扩展
用例	构建自定义代理	在 IDE 中直接使用
可定制性	✅ 完全开放	⚠️ 闭源
独立运行	✅ 是	❌ 需要 IDE
生产就绪	✅ 是	✅ 是
开源	✅ MIT 许可	❌ 专有

这样理解： - Claude Code = 完整汽车（引擎 + 车身 + 内饰） - codenano = 只有引擎（自己造车）

何时使用 codenano： - 构建自定义 AI 编码工具 - 将代理集成到你的产品中 - 需要完全控制行为 - 想要理解它如何工作

何时使用 Claude Code： - 只想用 AI 辅助编码 - 更喜欢 Anthropic 官方支持 - 满意 IDE 集成

---

工作原理

codenano 提取了 Claude Code 的代理循环：

1. 用户发送消息
2. 代理使用工具调用 Claude API
3. Claude 决定：响应或使用工具
4. 如果使用工具 → 执行 → 发送结果
5. 重复直到完成

我们从 Claude Code 提取了什么： - ✅ 代理循环逻辑 - ✅ 工具执行系统 - ✅ 流式支持 - ✅ 多轮会话 - ✅ 自动压缩（上下文管理） - ✅ 权限系统 - ✅ 重试和回退

我们排除了什么： - ❌ IDE 集成 - ❌ UI 组件 - ❌ 文件监视器 - ❌ Git UI - ❌ 桌面应用外壳

结果：纯粹的代理引擎，可嵌入任何地方。

---

你能得到什么

🛠️ 17 个内置工具

开箱即用，零配置： - 文件操作： Read、Edit、Write - 代码搜索： Glob（模式匹配）、Grep（正则搜索） - 执行： Bash 命令 - 高级： Web 搜索、Web 获取、笔记本、LSP 等

🎨 三种工具预设

coreTools()      // 基础 6 个工具
extendedTools()  // 核心 + 5 个
allTools()       // 全部 17 个工具

🔧 生产特性

• ✅ 自动压缩（处理上下文溢出）
• ✅ 重试和回退（弹性 API 调用）
• ✅ Token 预算（成本控制）
• ✅ 权限系统（安全）
• ✅ 钩子系统（生命周期事件）
• ✅ 流式支持（实时输出）
• ✅ 记忆系统（跨会话持久化）
• ✅ 查询追踪（调试/分析）
• ✅ 会话持久化（基于 JSONL 的保存/恢复）
• ✅ 扩展钩子（8 个生命周期钩子：onTurnStart、onPreToolUse、onPostToolUse、onCompact、onError 等）

---

系统结构

清晰、模块化的架构：

codenano/
  src/
    agent.ts           # 核心代理循环
    session.ts         # 多轮对话
    session-storage.ts # 会话持久化（JSONL）
    hooks.ts           # 生命周期钩子
    cost-tracker.ts    # 成本追踪
    git.ts             # Git 状态检测
    context-analysis.ts # 工具分类与上下文分析
    tools/             # 17 个内置工具 + createAgentTool
    prompt/            # 系统提示构建器
    memory/            # 持久化记忆系统
    provider.ts        # Anthropic SDK + Bedrock
    compact.ts         # 自动压缩逻辑
  tests/               # 374 个测试
  examples/            # 可运行示例
  docs/                # 完整文档

374 个测试。100% 生产就绪。

---

文档

文档	你将学到
架构	代理循环、交互模式、流事件
工具	内置工具、自定义工具、权限
配置	完整配置参考、CLAUDE.md 支持
可靠性	自动压缩、重试、回退、预算
提示系统	系统提示架构
差异分析	SDK vs Claude Code 对比

---

测试

# 单元测试（374 个测试）
npm test

# 带覆盖率
npx vitest run --coverage

# 集成测试（需要 API 密钥）
ANTHROPIC_API_KEY=sk-xxx npm run test:integration

---

路线图

已实现： - [x] 记忆系统（跨会话持久化） - [x] 任务管理工具 - [x] 查询追踪（调试/分析） - [x] 停止钩子（生命周期回调） - [x] 工具结果预算 - [x] 会话持久化（JSONL 保存/恢复） - [x] 扩展钩子（8 个生命周期钩子） - [x] 成本追踪（基于 token 的 USD 估算） - [x] Git 集成（状态检测、提示注入） - [x] 子代理生成（createAgentTool） - [x] 上下文折叠（工具分类、上下文分析） - [x] MCP 协议支持（stdio/SSE/HTTP 传输）

路线图已全部完成！

---

为什么选择 codenano？

对于初创公司

更快交付你的 AI 编码产品。停止与臃肿框架搏斗。几天而非几个月上市。

对于企业

从第一天起就生产就绪。经过实战检验的架构、全面测试、完全控制你的技术栈。

对于开发者

真正好用。清晰的 API、优秀的文档、零魔法。按你想要的方式构建。

---

许可证

MIT 许可证。

---

立即开始

npm install codenano

有问题？查看文档或提交 issue。

准备构建？查看示例获取灵感。