🔓 100% Local · Zero Cloud · Zero API Keys

Build a Completely
Sovereign AI System

Reverse-engineer how AI coding agents work. Then build your own — from scratch — running entirely on your machine. No cloud, no subscriptions, no black boxes.

View on GitHub
🐍 Python 3 🦙 Ollama ⏱ ~3 hours total 🧠 qwen2.5:7b

The Core Insight

Every AI coding agent — Claude Code, Cursor, Copilot — is the same pattern:

┌──────────┐ ┌──────────────────┐ ┌──────────┐ │ YOU │────▶│ BRAIN (LLM) │────▶│ TOOLS │ │ terminal │ │ thinks, decides │ │ read,write│ └──────────┘ └──────────────────┘ └──────────┘ │ ▲ decide │ │ result ▼ │ ┌──────────────────┐ │ read_file │ │ write_file │ │ bash │ │ grep_search │ └──────────────────┘

The brain thinks. The tools do. The loop repeats. That's the entire architecture.

🧭 Philosophy

We don't just explain code. At every level you read the real codebase, build your own version, test it, and move on. Your agent grows with each level.

📖
Reverse Engineer
Read the real codebase to understand what it does
🔨
Build
Write your own version of that piece
🧪
Test
Run the provided tests to verify it works
📝
Checkpoint
Your agent now has a new capability

📚 The 7-Level Curriculum

From "what is a coding agent?" to a fully working local agent you built yourself.

LEVEL 1 Understand What You're Building
No code yet. Understand the system you're going to reverse engineer. Learn the 3-box mental model: You → Brain → Tools → loop. Read the real codebase structure.
📖 Read: README.md, CLAW.md, PARITY.md 🎯 Outcome: Explain how Claude Code works in 30 seconds
LEVEL 2 Talk to the Brain
Build ollama_client.py — the module that talks to Ollama. Send messages, get responses. The magic is gone — it's just HTTP.
🔨 Build: ollama_client.py 📖 Read: src/query_engine.py, rust/crates/api/ 🎯 Outcome: Talk to a local LLM from your own code
LEVEL 3 Give It Hands
Build tools.py — 4 real tools: read_file, write_file, bash, grep_search. Define schemas, implement functions, wire up dispatch. Your LLM just read a file because it decided to.
🔨 Build: tools.py (4 tools) 📖 Read: rust/crates/tools/src/lib.rs 🎯 Outcome: LLM can interact with your filesystem
LEVEL 4 The Agent Loop
The big one. Build agent.py and __main__.py. Wire brain + hands together. After this level, python3 -m local_clawd launches YOUR coding agent.
🔨 Build: agent.py, __main__.py 📖 Read: rust/crates/runtime/src/conversation.rs 🎯 Outcome: A working coding agent you built
LEVEL 5 Remember and Adapt
Build session.py and config.py. Save and resume conversations. Detect your project's tech stack. Load CLAW.md for project-aware context.
🔨 Build: session.py, config.py 📖 Read: src/session_store.py, rust/crates/runtime/src/config.rs 🎯 Outcome: Agent remembers conversations and knows your project
LEVEL 6 Stream and Understand
Build streaming.py. Print tokens as they arrive instead of waiting for the full response. Understand tokenization, inference, KV cache, and what happens inside Ollama.
🔨 Build: streaming.py 📖 Read: rust/crates/api/src/sse.rs 🎯 Outcome: Real-time streaming + deep model understanding
LEVEL 7 Production Patterns
Build permissions.py and commands.py. Add permission tiers, context compaction, MCP integration, plugin system, error handling, and cost tracking. From toy to production.
🔨 Build: permissions.py, commands.py 📖 Read: Full architecture comparison 🎯 Outcome: Production-grade local coding agent

🏗️ What You'll Build

10 files. Each maps to a real piece of the codebase. By the end, it's yours.

local_clawd/
├── __init__.py
├── __main__.py         ← python3 -m local_clawd
├── ollama_client.py    ← Level 2: Talk to Ollama
├── tools.py            ← Level 3: 4 real tools
├── agent.py            ← Level 4: The agent loop
├── session.py          ← Level 5: Save/resume
├── config.py           ← Level 5: Project awareness
├── streaming.py        ← Level 6: Real-time tokens
├── permissions.py      ← Level 7: Access control
└── commands.py         ← Level 7: Slash commands

⚡ Prerequisites

Three things. That's it.

# 1. Python 3.10+
python3 --version

# 2. Ollama with a model
ollama pull qwen2.5:7b
ollama list

# 3. Curiosity
# (already installed)

🎯 Who Is This For

🌱 Beginners
"Oh, THAT'S how AI coding agents work" — concepts click, the mystery dissolves.
💻 Junior Developers
Build a working agent, understand tool calling, gain real confidence with AI systems.
🏗️ Senior Engineers
See the architecture patterns, understand the design decisions, fork and extend.
🤔 Curious Minds
Enough understanding to have informed opinions about AI tools and sovereignty.