Skip to content

Adamlixi/codenano

Repository files navigation

codenano

npm version License: MIT TypeScript Tests

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.

Why codenano?

🚀 Lightweight & Focused

  • ~8,000 lines of pure, focused code
  • Zero bloat, zero overhead
  • Production-grade agent engine

Build AI Coding Agents Fast

npm install codenano

Build your own AI coding agent in 60 seconds. No IDE required. No restrictions.

🎯 Battle-Tested Architecture

Production-grade agent patterns. Proven at scale, optimized for developers.


Quick Start

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.

Streaming? Built-in.

for await (const event of agent.stream('What files are here?')) {
  if (event.type === 'text') process.stdout.write(event.text)
}

Multi-turn conversations? Easy.

const session = agent.session()
await session.send('Read main.ts')
await session.send('Now explain what it does')

Session persistence? Built-in.

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?')

Cross-session memory? Automatic.

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 systems

Memories 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')

Storage paths

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' },
})

Cost tracking? Automatic.

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.0047

Use 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)}`)

Git integration? Built-in.

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..."

Lifecycle hooks? 8 of them.

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.

Sub-agent spawning? One function.

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
})

Context analysis? Ready.

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? Load from disk.

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.

MCP protocol? Supported.

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)

Custom Tools

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],
})

codenano vs Other Frameworks

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) ⚠️ Basic ⚠️ Basic
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

What You Get

🛠️ 17 Built-in Tools

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

🎨 Three Tool Presets

coreTools()      // Essential 6 tools
extendedTools()  // Core + 5 more
allTools()       // All 17 tools

🔧 Production Features

  • ✅ 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.)

System Structure

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.


Documentation

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

Testing

# 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:integration

Roadmap

Implemented:

  • 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!


Why Choose codenano?

For Startups

Ship your AI coding product faster. Stop wrestling with bloated frameworks. Get to market in days, not months.

For Enterprises

Production-ready from day one. Battle-tested architecture, comprehensive testing, full control over your stack.

For Developers

Actually enjoyable to use. Clean APIs, great docs, zero magic. Build what you want, how you want.


License

MIT License.


Get Started Now

npm install codenano

Questions? Check the docs or open an issue.

Ready to build? See examples/ for inspiration.

About

Lightweight AI coding agent SDK extracted from Claude Code. 5,500 lines vs 510,000+. Same power, 97% less complexity. Build custom AI coding agents in 1 minutes

Topics

Resources

Stars

Watchers

Forks

Packages

 
 
 

Contributors