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
• 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:

1. 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").
2. 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.
3. 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).
4. 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):
  • Ollama — local, free, no account needed
  • LM Studio — local, free, no account needed
  • Groq — cloud, free tier, very fast
  • OpenRouter — cloud, free tier, 100+ models
  • Google Gemini — cloud, generous free tier
  • DeepSeek — cloud, very cheap, strong coder
  • Any OpenAI-compatible endpoint

Installation

git clone https://github.com/razvanneculai/litecode.git
cd litecode
npm install
npm run build
npm link

After npm link, the litecode command is available globally in your terminal.

Without installing globally: Replace litecode with npm run dev -- in all commands below.

Quick Start (5 minutes)

Step 1 — Go to your project

cd /path/to/your/project

LiteCode always operates on the current directory. Run all commands from inside the project you want to edit.

Step 2 — Connect to an LLM

litecode connect

An interactive menu will guide you through:

• Selecting a provider (Ollama, Groq, OpenRouter, etc.)
• Entering your API key (or leaving it blank for local models)
• Picking a model from the live list
• Setting your token limit

This saves a litecode.json file in your project directory. That file contains y