CodeCode — The scratch-built AI coding agent

Features

Everything you need, nothing you don't

A carefully crafted set of native tools and a lean agent loop — no frameworks, no bloat.

{ }

Multi-Provider LLM Support

OpenAI, Anthropic, DeepSeek, MiniMax, Kimi, GLM — swap providers with a single environment variable.

⟳

Autonomous Agent Loop

The LLM decides which tool to call, receives results, and iterates until the task is done. Max 20 rounds per task.

◇

Native Tool Calling

Tools defined as JSON Schema and dispatched natively by the LLM — no string parsing, no regex hacks.

›_

Bash Execution

Run shell commands safely inside the workspace with a 30-second hardcoded timeout.

◇

File Sandboxing

Path-traversal protection via safePath(). All file operations are locked to the current workspace.

∑

Safe Calculator

Sanitized eval for math — only 0-9 + - * / . ( ) characters pass through.

↗

Skill System

Extend the agent with installable skills. Skills live as SKILL.md files under {CODEDIR}/skills/ or .agents/skills/.

☰

Memory & Context Compression

Persistent memories across sessions and automatic context compression to stay within token limits.

Architecture

How it works

From entry point to agent loop — a zero-abstraction design you can read in an afternoon.

src/
├── index.ts // Entry: createModel() → startRepl() → agentLoop()
├── agent/
│ ├── loop.ts // The core agent loop (max 20 rounds)
│ ├── prompt.ts // System prompt builder with dynamic context
│ ├── permission-manager.ts // Tool-call deny/ask rules
│ ├── hooks.ts // LoopListener lifecycle
│ ├── tools/
│ │ ├── index.ts // Tool registry
│ │ ├── tool-registry.ts
│ │ ├── bash.ts // Shell execution
│ │ ├── read.ts // File reader
│ │ ├── write.ts // File writer
│ │ ├── edit.ts // Text replacement
│ │ ├── calculate.ts // Safe eval
│ │ ├── 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 framework)
│ ├── providers.ts // Provider configurations
│ ├── openai-chat-model.ts
│ └── anthropic-chat-model.ts
├── session/
│ └── session-manager.ts // Persist turns to {CODEDIR}/sessions/
└── types/
├── index.ts // Shared types
└── messages.ts // Message classes

Agent Loop

Sends conversation + tool definitions to the LLM. The LLM responds with text or tool calls. Tool results feed back as user messages. Repeats until done or 20 rounds reached.

Context Compression

Three-layer compression: large outputs → disk with previews, old tool results summarized, and an optional /compact command for LLM continuity summaries.

Permission System

Before each tool call, deny rules are checked. Blocks destructive commands (rm -rf /, dd, mkfs*, shutdown) and /etc/* writes; prompts for confirmation on network commands (wget, curl, ssh, scp).

Memory System

Persistent memories stored as Markdown files with YAML frontmatter. Four types: user preferences, feedback corrections, project facts, external references.

Quick Start

Up and running in 30 seconds

One dependency install, one API key, and you're talking to your agent.

📦 Install

# Clone and install
$ git clone https://github.com/chingjustwe/codecode.git
$ cd CodeCode
$ npm install

# Configure your API key
$ cp .env.example .env
$ # Edit .env with your provider & API key

🚀 Run

# Default (Anthropic Claude)
$ npm start

# Or pick a provider:
$ npm run openai
$ npm run deepseek
$ npm run minimax
$ npm run kimi
$ npm run glm

🌐 Supported Providers

OpenAI Anthropic DeepSeek MiniMax Kimi GLM + Any OpenAI-compatible API

Tools

Native tools at your agent's fingertips

Each tool is a JSON Schema definition with a runtime function — registered in the tool registry and auto-included on every API call.

Tool	Description
calculate	Evaluate a mathematical expression (sanitized eval)
bash	Run a shell command in the current workspace (30s timeout)
read	Read the contents of a file (50 KB cap)
write	Write content to a file (creates parent directories)
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

Philosophy

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.

🏗️

Zero LangChain Dependency

Two minimal runtime dependencies (dotenv + js-yaml) + TypeScript toolchain. That's it.

🔬

Educational Design

Every part of the agent is readable in an afternoon. No black boxes, no magic.

Build better codewith CodeCode