# Add to your Claude Code skills
git clone https://github.com/razvanneculai/litecode
README.md
LiteCode
The AI coding agent built for the models everyone actually has — free tiers, local models, and 8k context windows.
LiteCode lets you describe a code change in plain English and have an AI execute it across your entire project. No paid subscription. No 200k-token model required. Works right now with a free Groq account, a free OpenRouter key, or just Ollama on your laptop.
What it does
Multi-file edits from one instruction — "rename validateToken to verifyToken everywhere" touches every file that needs changing, in the right order
Never exceeds 8k tokens — token budget is enforced in code before every single LLM call, not by hoping the model behaves
Runs edits in parallel — independent file changes happen at the same time; sequential ones wait for their dependencies
Short-term memory — LiteCode remembers the last 4 things it did in your project. Say "undo the last change" or "also add a goodbye() function" and it knows exactly what you mean. Memory is now passed to both the planner and executor (expanded in v1.1)
Auto-sequential for local models — when the configured provider is on localhost, executors run one at a time automatically, eliminating the parallel connection pressure that causes Ollama to drop requests
Interactive TUI with scroll + mouse wheel — persistent chat session, live token sidebar, scrollable history, diff viewer. Run litecode with no arguments, or use --ansi for the plain terminal mode
Works with any free model — Groq, OpenRouter, Ollama, LM Studio, Gemini, DeepSeek — all supported out of the box
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Context maps are plain Markdown — readable by humans, cheap on tokens, safe to commit to git
Diff preview before every write — see exactly what the AI wants to change, file by file, before anything touches disk
Short-Term Memory
As of v1.1, LiteCode remembers the last 4 actions it performed in each project. This memory is stored in .litecode/memory.json inside your project and is injected into both the planner's and executor's prompts on every request so the AI can reason about what it previously did.
What this enables:
litecode "add a hello() function that logs 'hi' to utils.js"
# → Planner adds hello(), applies, saves memory
litecode "undo the last change"
# → Planner reads memory, knows hello() was added to utils.js, removes it
litecode "also add a goodbye() function"
# → Planner sees recent context and makes the right decision
How it works:
After the planner produces a task list, it also outputs a one-sentence synthesis describing what the plan will do (e.g. "Added a hello() function in utils.js").
After at least one file is successfully written to disk, LiteCode saves an entry with the user's original request, the synthesis, the files that were written, and a timestamp.
The memory is a ring buffer of 4 — the oldest entry is evicted when a fifth is added. This keeps the token cost negligible (~80–90 tokens per entry).
On every subsequent request, the memory block is prepended to both the planner's and executor's system prompts so both the planning and editing stages can reason about "last time", "undo", "revert", "previous", etc. The executor only injects memory when it fits within the remaining token budget.
Token cost: ~80–90 tokens per entry (~320–360 tokens for a full buffer of 4). The budget check (canFit) accounts for memory — if the project context is very large, folder context is dropped first, then memory, to ensure the planner always fits within your configured token limit. The executor guards memory injection independently with the same logic.
Storage:.litecode/memory.json — per-project, not global. You can add .litecode/ to your .gitignore if you don't want it committed.
TUI by default (and how to opt out)
LiteCode ships with a full TUI (terminal user interface) enabled by default, built on Ink + React. You get a two-pane layout — a scrollable chat/diff view on the left and a live token/model sidebar on the right — plus per-task spinners, inline diff previews, and mouse-wheel scrolling. The TUI auto-activates whenever stdout is a TTY.
If you prefer the older plain-ANSI REPL — for piping, logging, recording sessions, or running inside environments where the TUI misbehaves — pass --ansi:
litecode --ansi "add a test for foo"
litecode --ansi chat
No other behavior changes — memory, diffs, and confirmation prompts all work identically in both modes.
Why LiteCode?
Most AI coding tools assume you have access to a 200k-token model. In practice, the free tiers and local models most developers actually use have 8k context windows — barely enough for one large file, let alone a whole project.
LiteCode was built from the ground up for this constraint. It never sends your entire codebase to the AI at once. Instead, it uses a three-stage system:
You: "rename the login function to authenticate everywhere"
│
▼
┌─────────────────────────────┐
│ PLANNER (1 AI call) │
│ │
│ Reads your project map │
│ + last 4 memory entries. │
│ Figures out which files │
│ need to change and in │
│ what order. │
│ │
│ Output: { synthesis, tasks }
└────────────┬────────────────┘
│
▼
┌─────────────────────────────┐
│ ORCHESTRATOR (pure code) │
│ │
│ Reads the task list. │
│ Figures out what can run │
│ in parallel vs. in order. │
│ Loads just the right code. │
│ Checks token budgets. │
└──┬──────────┬───────────────┘
│ │
▼ ▼
┌──────┐ ┌──────┐ ← One AI call per file, running in parallel
│ auth │ │login │
│ .js │ │ .js │
└──┬───┘ └──┬───┘
│ │
▼ ▼
Edit Edit ← Pure code writes results back to disk
│
▼
┌─────────────────┐
│ memory.json │ ← Synthesis + files saved after successful apply
└─────────────────┘
The key insight: only one file's worth of code ever goes to the AI at a time. The AI doesn't need to see the whole project — it just needs to know what to change in this one file.
Understanding the Context Map System
Before editing, LiteCode needs to understand your project. Running litecode init --fast generates plain Markdown files alongside your code:
your-project/
├── project_context.md ← "What is this project?" (~300–500 tokens)
│ Tech stack, entry points, folder descriptions
├── src/
│ ├── folder_context.md ← "What's in src/?" (~200–400 tokens)
│ │ Every file, one-line description, key imports/exports
│ ├── auth.js
│ ├── auth.js.file_analysis.md ← Only for files >150 lines
│ │ Line-range index: what lives on which lines
│ └── ...
└── routes/
├── folder_context.md
└── ...
Layer 1 — project_context.md: The 30-second overview. Tech stack, which folder does what, entry points. The AI reads this first on every request.
Layer 2 — folder_context.md: One per folder. Lists every file with a one-liner description. The AI uses this to know exactly which file to open.
Layer 3 — *.file_analysis.md: Generated only for large files (over ~150 lines). Contains a line-by-line index so the AI can request only the section it needs — fitting even huge files into an 8k window.
These files are plain Markdown. You can read them. They're safe to commit to git — they act as a persistent record of your project's structure between sessions.
Token Budget
Every LLM call is budgeted like this:
Total context window: 8192 tokens
─────────────────────────────────────────────
System prompt + instructions: ~1000 tokens
Reserved for AI response: ~2000 tokens
Memory (up to 4 entries): ~360 tokens
─────────────────────────────────────────────
Available for your code: ~4800 tokens (≈ 140–190 lines)
The token counter runs before every LLM call. If the code doesn't fit, LiteCode automatically falls back to loading just the relevant section using the file's analysis index. This check never gets skipped.
Priority when budget is tight: folder context is dropped first, then memory, to preserve the most recent history as long as possible.
Requirements
Node.js v18 or later
npm
An LLM provider (pick any — free options listed below):
A Claude Code plugin that automatically captures everything Claude does during your coding sessions, compresses it with AI (using Claude's agent-sdk), and injects relevant context back into future sessions.
