codegen — a local autonomous coding agent

A small, fully-local AI coding agent that runs on Ollama (CPU-only friendly). The model works in a loop with simple tool blocks (<<<READ>>>, <<<RUN>>>, <<<FILE>>>, <<<DONE>>>…) that even a 3B model can follow. No cloud, no API keys.

Four ways to drive it — same engine (codegen.py) behind all of them:

Interface	Entry point	Use
CLI	codegen.py	terminal, scripting
Browser GUI	gui.py → server.py	editor-independent: model manager + chat, one command
VS Code	extension/ → server.py	sidebar chat + diff approval
Telegram	telegram_bot.py	drive it from your phone, 24/7

Quick start (works on any Linux, cloned anywhere)

# 0. prerequisites: Ollama (https://ollama.com) running + Python 3.10+

# 1. clone wherever you like
git clone <repo-url> codegen && cd codegen

# 2. turnkey setup — python deps + both Ollama models + a portable `ai` launcher.
#    Uses local ../models/*.gguf if present, otherwise pulls the base models
#    straight from the Ollama registry. No manual downloads, no hard-coded paths.
./setup.sh

# 3. run it — from ANY project directory:
ai "write a FastAPI hello-world app"     # `ai` was installed to ~/.local/bin

setup.sh auto-detects its own location, so the ai command always points at wherever you cloned the project. Prefer not to install a launcher? Run it directly:

python3 /path/to/codegen/codegen.py -d ./demo "task..."   # one-shot
python3 /path/to/codegen/codegen.py -d ./demo             # chat mode

Local GGUF files live in a sibling ../models/ by default; override with CODEGEN_MODELS_DIR=/some/path ./setup.sh. Without any local gguf, setup pulls the base models from the Ollama registry — so a fresh clone needs nothing extra.

Browser GUI (editor-independent)

One command opens a self-contained UI in your browser — no editor required:

codegen-gui            # installed by setup.sh  (or: python3 gui.py)

It has two tabs:

• Models — a first-class model manager: list installed models, pull new ones from the Ollama registry with a live progress bar, create a named model from a base with a baked context size, delete, and edit the model registry (context size / temperature per model) — all with no code editing.
• Chat — agent / chat / build / web / research modes with live token streaming, file-diff approvals, stop, a project picker, and a context-size selector (4K / 8K / 16K / 32K) applied per run via Ollama's options.num_ctx (no Modelfile rebuild).

The GUI and the VS Code extension are two thin frontends over the same server.py backend. Backend talks to Ollama at OLLAMA_HOST (default http://localhost:11434).

Model registry (config-driven — no code edits)

Models are described in one declarative file, ~/.codegen/models.json, read by the engine, the CLI, and both GUIs (and editable from the GUI). Swapping a model, changing its default context size, or adding a cloud provider never touches Python. If the file is absent a sensible default is synthesized (reproducing the built-in qwen-fast / qwen3-think behavior). models.yaml is also read if PyYAML happens to be installed; JSON stays the canonical, zero-dependency format. Set context per run from the CLI too:

ai --model qwen-fast --num-ctx 16384 "..."   # per-request context window override

The registry also assigns roles: the executor (default chat/agent model) and the planner (build-mode planner), editable from the model manager. The engine honors them — --model / --planner / CODEGEN_MODEL still override per run.

Choosing a model

Models are plain Ollama models built from Modelfile.* (see setup.sh).

Model	Built from	Best for
qwen-fast ⭐	Modelfile.coder3b (Qwen2.5-Coder-3B)	default — fast code writing (~9 tok/s on CPU)
qwen3-think	Modelfile.q3test (Qwen3-4B)	planning / reasoning (think mode)

ai --model qwen-fast "..."                          # fast executor (default)
ai --model qwen3-think --think -b "..."             # think-mode planner, build mode
ai --model qwen-fast --planner qwen3-think --think -b "..."   # hybrid: smart plan, fast build

Modes & key flags

• chat (no task arg) · one-shot ("task") · build (-b, plan → file-by-file)
• -d DIR target dir · -y auto-approve · -n N max iterations · --think reasoning · -c FILE preload context
• --model NAME executor · --planner NAME build planner · --num-ctx N context window · --provider NAME cloud backend
• run python3 codegen.py --help for the full flag list

Tools the agent can use

<<<LIST>>> <<<READ>>> <<<RUN>>> <<<FILE>>> <<<RAGSEARCH>>> (local RAG over your code, rag_tool.py) · <<<DOCRAG>>> (optional document Q&A — needs the separate docrag package on PYTHONPATH; degrades gracefully if absent) · <<<RESEARCH>>> (web) · <<<DONE>>>.

Persistent memory via mem0_tool.py (optional, local Mem0). RAG/Mem0 data live in ~/.codegen/.

VS Code extension

Build & install once, then reload the VS Code window:

cd extension && npm install && npm run compile
npx @vscode/vsce package --no-dependencies --allow-missing-repository
code --install-extension codegen-local-0.1.0.vsix --force

The extension is UI only — it auto-launches server.py and talks to it over HTTP/SSE (all logic stays in codegen.py). It finds server.py automatically (next to the extension, or at ~/Downloads/codegen/server.py). If your clone lives elsewhere, point it there in VS Code settings:

"codegen.serverScript": "/abs/path/to/codegen/server.py"

In the sidebar you get:

• Chat / agent / build / web / research modes — live token streaming, file-diff approval, stop, history & rewind, @-file mentions, / slash commands.
• A context-size selector (4K / 8K / 16K / 32K) applied per run (options.num_ctx).
• A Model manager (server icon, top-right): list installed models, pull with a live progress bar, create from a base, delete, edit the registry (per-model num_ctx / temperature), and assign roles — choose the default executor (chat/agent) and planner (build).
• A first-run wizard: if Ollama is down or no model is installed, it offers to pull one.

See extension/README.md for details.

Telegram bot

export TELEGRAM_BOT_TOKEN=...           # from @BotFather
export TELEGRAM_ALLOWED_CHAT_ID=...     # your chat id (hard whitelist)
python3 telegram_bot.py

⚠️ The agent can run shell commands. The bot enforces a chat-id whitelist, a sandbox dir (CODEGEN_SANDBOX, default ~/codegen-sandbox), and codegen's catastrophic-command block.

Tests

Stdlib unittest only — no Ollama or network needed (the backend is faked):

python3 -m unittest discover -s tests

Covers the model registry, behavior-preserving num_ctx/temperature plumbing, the tool registry, provider selection, and role assignment.

Layout

codegen.py        engine: agent loop + tool registry + provider strategy
model_registry.py config-driven model registry (~/.codegen/models.json)
server.py         HTTP/SSE wrapper + model-manager API (GUI + extension backend)
gui.py            one-command launcher for the standalone browser GUI
gui/              standalone browser GUI (static HTML/CSS/JS — no build, no deps)
contracts.py      build-mode state + cross-step bug fixing
rag_tool.py       local RAG over your files (Ollama embeddings)
mem0_tool.py      persistent memory (local Mem0)
telegram_bot.py   Telegram interface
tests/            stdlib unittest suite (registry, runtime knobs, tool/provider, roles)
extension/        VS Code extension (TypeScript, UI only)
Modelfile.*       Ollama model definitions (FROM ../models/*.gguf)
qwen3*.tmpl       prompt templates
docs/             full reference: codegen-REFERENCE.md, BUILD-SPEC, setup guide, backlog

Full docs: docs/codegen-REFERENCE.md.