The lightweight AI coding agent SDK inspired by production agent architecture.
Built with battle-tested patterns from production AI coding systems. ~8,000 lines of focused code, zero bloat. Open source, fully customizable, production-ready.
💡 Production-Grade Patterns — Agent loop architecture inspired by real-world AI coding assistants, now available as a standalone SDK.
- ~8,000 lines of pure, focused code
- Zero bloat, zero overhead
- Production-grade agent engine
npm install codenanoBuild your own AI coding agent in 60 seconds. No IDE required. No restrictions.
Production-grade agent patterns. Proven at scale, optimized for developers.
Get your first agent running in 3 lines:
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('Read package.json and summarize it')
console.log(result.text)That's it. No complex setup. No configuration hell. Just pure productivity.
for await (const event of agent.stream('What files are here?')) {
if (event.type === 'text') process.stdout.write(event.text)
}const session = agent.session()
await session.send('Read main.ts')
await session.send('Now explain what it does')const agent = createAgent({
model: 'claude-sonnet-4-6',
tools: coreTools(),
persistence: { enabled: true }, // saves to ~/.agent-core/sessions/
})
const session = agent.session()
console.log(session.id) // save this UUID
await session.send('Analyze the codebase')
// Later — resume from where you left off
const resumed = agent.session(session.id)
await resumed.send('What did we find?')const agent = createAgent({
model: 'claude-sonnet-4-6',
memory: {
autoLoad: true, // inject saved memories into system prompt
extractStrategy: 'auto', // extract memories after every turn
},
})
// The agent learns from conversations and remembers across sessions:
// - User preferences and role
// - Feedback on approach (what to avoid/repeat)
// - Project context and decisions
// - Pointers to external systemsMemories are stored as markdown files with frontmatter, indexed by MEMORY.md. Use the standalone API for direct access:
import { saveMemory, scanMemories, loadMemoryIndex } from 'codenano'
saveMemory({
name: 'user_role',
description: 'User is a backend engineer',
type: 'user',
content: 'Expert in Go and Python, new to React',
}, '/path/to/memory')
const memories = scanMemories('/path/to/memory')Both memory and session persistence have sensible defaults and support custom paths. Directories are created automatically if they don't exist.
| Feature | Default Path | Custom Config |
|---|---|---|
| Memory | ~/.agent-core/memory/<cwd-hash>/ |
memory.memoryDir |
| Session | ~/.agent-core/sessions/ |
persistence.storageDir |
// Use defaults — zero config
const agent = createAgent({
model: 'claude-sonnet-4-6',
memory: { autoLoad: true, extractStrategy: 'auto' },
persistence: { enabled: true },
})
// Or specify custom paths
const agent = createAgent({
model: 'claude-sonnet-4-6',
memory: { memoryDir: './my-project/memory', autoLoad: true },
persistence: { enabled: true, storageDir: './my-project/sessions' },
})Every Result includes costUSD — estimated API cost based on model pricing.
const result = await agent.ask('Explain this code')
console.log(`Cost: $${result.costUSD.toFixed(4)}`) // e.g. $0.0047Use the standalone API for budget management:
import { CostTracker, calculateCostUSD } from 'codenano'
const tracker = new CostTracker()
tracker.add('claude-sonnet-4-6', result.usage)
console.log(`Total: $${tracker.summary.totalUSD.toFixed(4)}`)Auto-detect git repo state for system prompt injection:
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..."Observe and control agent behavior at every lifecycle point:
const agent = createAgent({
model: 'claude-sonnet-4-6',
tools: coreTools(),
onTurnStart: ({ turnNumber }) => console.log(`Turn ${turnNumber}`),
// Block dangerous tools
onPreToolUse: ({ toolName, toolInput }) => {
if (toolName === 'Bash' && toolInput.command?.includes('rm -rf'))
return { block: 'Destructive commands blocked' }
},
onPostToolUse: ({ toolName, output }) => console.log(`${toolName}: ${output.slice(0, 50)}`),
onCompact: ({ messagesBefore, messagesAfter }) => console.log(`Compacted: ${messagesBefore} → ${messagesAfter}`),
onError: ({ error }) => console.error(error.message),
onMaxTurns: () => console.warn('Max turns reached'),
})All hooks are best-effort — errors in hooks never crash the agent.
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], // model can now spawn sub-agents
})Analyze conversation context to identify compression opportunities:
import { analyzeContext, classifyTool } from 'codenano'
const analysis = analyzeContext(session.history)
// { toolCalls: 5, duplicateFileReads: { '/a.ts': 3 }, collapsibleResults: 4, ... }
classifyTool('Grep') // 'search'
classifyTool('Bash') // 'execute'Skills are Markdown files with YAML frontmatter:
import { loadSkills, createSkillTool, createAgent } from 'codenano'
// Load skills from .claude/skills/ directories
const skills = loadSkills()
// Create a functional SkillTool
const skillTool = createSkillTool(skills)
const agent = createAgent({
model: 'claude-sonnet-4-6',
tools: [skillTool], // model can invoke skills via the Skill tool
})Skill file format (.claude/skills/my-skill/SKILL.md):
---
name: review-pr
description: Review a pull request
arguments: [pr_number]
context: inline
---
Review PR #$pr_number. Focus on bugs and security.Connect to any MCP server and use its tools:
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('List open issues')
// Cleanup
await disconnectAll(connections)import { defineTool } from 'codenano'
import { z } from 'zod'
const readFile = defineTool({
name: 'ReadFile',
description: 'Read a file from disk',
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],
})Lightweight, production-grade, inspired by battle-tested patterns.
| Feature | codenano | Vercel AI SDK | LangChain |
|---|---|---|---|
| Philosophy | Inspired by production AI coding systems | General-purpose AI SDK | General agent framework |
| Lines of Code | ~8,000 (focused) | ~15,000+ | 100,000+ |
| What's Included | Agent engine + 17 tools | Multi-model + streaming | Everything + kitchen sink |
| Setup Time | < 1 minute | < 1 minute | 10+ minutes |
| Use Case | Build coding agents | Build any AI app | Build complex workflows |
| Production Hardening | ✅ Full (compaction, recovery, budgeting) | ||
| Streaming Tool Execution | ✅ Yes | ❌ No | ❌ No |
| Open Source | ✅ MIT License | ✅ Apache 2.0 | ✅ MIT License |
When to use codenano:
- Building AI coding tools or agents
- Need production-grade reliability (auto-compact, 413 recovery, tool budgeting)
- Want lightweight, focused architecture
- Prefer battle-tested patterns over experimental features
Ready to use, zero configuration:
- File Operations: Read, Edit, Write
- Code Search: Glob (pattern matching), Grep (regex search)
- Execution: Bash commands
- Advanced: Web search, web fetch, notebooks, LSP, and more
coreTools() // Essential 6 tools
extendedTools() // Core + 5 more
allTools() // All 17 tools- ✅ Auto-compact (handles context overflow)
- ✅ Retry & fallback (resilient API calls)
- ✅ Token budgeting (cost control)
- ✅ Permission system (security)
- ✅ Hook system (lifecycle events)
- ✅ Streaming support (real-time output)
- ✅ Memory system (cross-session persistence)
- ✅ Query tracking (debugging/analytics)
- ✅ Session persistence (JSONL-based save/resume)
- ✅ Extended hooks (8 lifecycle hooks: onTurnStart, onPreToolUse, onPostToolUse, onCompact, onError, etc.)
Clean, modular architecture:
codenano/
src/
agent.ts # Core agent loop
session.ts # Multi-turn conversations
session-storage.ts # Session persistence (JSONL)
hooks.ts # Lifecycle hook helpers
cost-tracker.ts # Token-based cost tracking
git.ts # Git state detection
context-analysis.ts # Tool classification & context analysis
tools/ # 17 built-in tools + createAgentTool
prompt/ # System prompt builder
memory/ # Persistent memory system
provider.ts # Anthropic SDK + Bedrock
compact.ts # Auto-compact logic
tests/ # 374 tests
examples/ # Ready-to-run demos
docs/ # Comprehensive guides
374 tests. 100% production-ready.
| Doc | What You'll Learn |
|---|---|
| Architecture | Agent loop, interaction modes, stream events |
| Tools | Built-in tools, custom tools, permissions |
| Configuration | Full config reference, CLAUDE.md support |
| Reliability | Auto-compact, retry, fallback, budgeting |
| Prompt System | System prompt architecture |
| Gap Analysis | SDK vs Claude Code comparison |
# Unit tests (374 tests)
npm test
# With coverage
npx vitest run --coverage
# Integration tests (requires API key)
ANTHROPIC_API_KEY=sk-xxx npm run test:integrationImplemented:
- Memory system (cross-session persistence)
- Task management tools
- Query tracking (debugging/analytics)
- Stop hooks (lifecycle callbacks)
- Tool result budgeting
- Session persistence (JSONL save/resume)
- Extended hooks (8 lifecycle hooks)
- Cost tracking (token-based USD estimation)
- Git integration (state detection, prompt injection)
- Sub-agent spawning (createAgentTool)
- Context collapse (tool classification, context analysis)
- MCP protocol support (stdio/SSE/HTTP transports)
Roadmap complete!
Ship your AI coding product faster. Stop wrestling with bloated frameworks. Get to market in days, not months.
Production-ready from day one. Battle-tested architecture, comprehensive testing, full control over your stack.
Actually enjoyable to use. Clean APIs, great docs, zero magic. Build what you want, how you want.
MIT License.
npm install codenanoQuestions? Check the docs or open an issue.
Ready to build? See examples/ for inspiration.