CodeCode is a minimal, scratch-built AI coding agent client written in TypeScript, inspired by Claude Code and Open Code.
Why build from scratch?
To deeply understand how coding agents work under the hood — tool-calling loops, multi-provider LLM integration, and file-system tooling — without any framework abstraction like LangChain.
- 🧠 Multi-provider LLM support — OpenAI, DeepSeek, MiniMax, Kimi, GLM (OpenAI-compatible), and Anthropic / Claude
- 🛠️ Native tool calling — tools are defined as JSON schemas and dispatched by the LLM natively (no string parsing)
- 📁 Workspace-aware file operations — read, write, edit files with path-traversal protection
- 🔍 Code search & discovery —
grep(regex over file contents),glob(file-pattern match),ls(directory listing) — all sandboxed, no shell-out - 🐚 Bash execution — run shell commands inside the current workspace
- 🧮 Calculator — evaluate mathematical expressions
- 🔄 Agent loop — the LLM autonomously decides which tool to call, receives results, and iterates until the task is done
- 🏗️ Zero-abstraction design — two runtime dependencies (
dotenv+js-yaml) + TypeScript toolchain
# Install dependencies
npm install
# Copy environment config and add your API keys
cp .env.example .env
# Edit .env with your provider API key and preferred model
# Start the REPL
npm start# Default (Anthropic Claude)
npm start
# OpenAI
npm run openai
# DeepSeek
npm run deepseek
# MiniMax
npm run minimax
# Kimi
npm run kimi
# GLM
npm run glm| Variable | Description |
|---|---|
LLM_PROVIDER |
Provider name: openai, anthropic, deepseek, minimax, kimi, glm, claude (alias for anthropic) |
OPENAI_API_KEY |
OpenAI / DeepSeek / MiniMax / Kimi / GLM API key |
ANTHROPIC_API_KEY |
Anthropic API key |
LLM_MODEL |
(Optional) Override the default model for the selected provider |
src/
├── index.ts # Entry point
├── utils/
│ └── file-utils.ts # File sandboxing utilities (safePath)
├── agent/
│ ├── loop.ts # Agent loop — orchestrates tool calls
│ ├── prompt.ts # System prompt builder
│ ├── permission-manager.ts # Tool-call deny/ask rules
│ ├── hooks.ts # LoopListener lifecycle
│ └── tools/
│ │ ├── index.ts # Tool registry & exports
│ │ ├── tool-registry.ts
│ │ ├── bash.ts # Shell command execution
│ │ ├── calculate.ts # Mathematical expression evaluator
│ │ ├── edit.ts # File text replacement
│ │ ├── glob.ts # File finder by glob pattern (exports globToRegex + walk)
│ │ ├── grep.ts # Regex content search (reuses glob helpers)
│ │ ├── ls.ts # Directory listing
│ │ ├── read.ts # File reader
│ │ ├── write.ts # File writer
│ │ ├── memory/ # save-memory-tool + memory-manager
│ │ ├── skill/ # load-skill + skill-registry
│ │ └── todo/ # todo + todo-tool
│ ├── commands/ # /help /compact /new /list /list-perm-rule /prompt
│ ├── compact/ # Three-layer context compression
│ ├── subagent/ # dispatch_task + subagent runtime
│ └── hooks/ # usage-hook
├── cli/
│ └── repl.ts # Interactive REPL
├── config/
│ └── config-loader.ts # codecode.yml loader
├── llm/
│ ├── factory.ts # Model factory (dispatches by API framework)
│ ├── providers.ts # Provider configuration
│ ├── openai-chat-model.ts # OpenAI-compatible API client
│ └── anthropic-chat-model.ts # Anthropic API client
├── session/
│ └── session-manager.ts # Persist turns to {CODEDIR}/sessions/
└── types/
├── index.ts # Shared types & interfaces
└── messages.ts # Message classes
- The agent loop (
loop.ts) sends the conversation + available tool definitions to the LLM - The LLM responds with either a text reply or one or more tool calls
- If tool calls are requested, the loop executes them via the tool registry (
tools/index.ts) and feeds results back to the LLM - This continues until the LLM produces a final text response
| Tool | Description |
|---|---|
calculate |
Evaluate a mathematical expression |
bash |
Run a shell command in the current workspace |
read |
Read the contents of a file |
write |
Write content to a file (creates parent dirs) |
edit |
Replace text in a file (first occurrence by default; replace_all: true for every match) |
glob |
Find files by glob pattern (e.g. src/agent/tools/*.ts) |
grep |
Search file contents by regex; returns files / lines / counts |
ls |
List entries in a directory (non-recursive) |
load_skill |
Load a skill into the current context |
todo |
Update the session plan for multi-step work |
save_memory |
Persist a memory across sessions (user / feedback / project / reference) |
dispatch_task |
Spawn a read-only subagent with a fresh context for complex sub-tasks |
File I/O tools (read/write/edit) are sandboxed to the current workspace — paths that escape via .. traversal are rejected. bash is gated by the permission system's deny/ask rules.
# TypeScript compilation check
npm run typecheck
# Build
npm run buildISC