ucode

A free, open-source AI coding agent for your terminal.
Builds whole apps in about a minute on Google Gemini's free tier — then opens them and clicks through to check its own work.

npm i -g ucode-agent     # Node 22 or newer
ucode login YOUR_KEY     # a free key from aistudio.google.com/apikey
ucode                    # in any project folder

A coding agent that lives in your terminal, like Claude Code or Codex CLI — but free: it runs on Gemini's free tier, or on Ollama with no internet at all. It reads your code, edits it, runs your commands, checks its own work, and keeps every conversation on disk. If it helps you, a ⭐ helps other people find it.

It opens on a quiet screen — the name, the place to type, and the version in the corner:

                     ██╗   ██╗ ██████╗ ██████╗ ██████╗ ███████╗
                     ██║   ██║██╔════╝██╔═══██╗██╔══██╗██╔════╝
                     ██║   ██║██║     ██║   ██║██║  ██║█████╗
                     ██║   ██║██║     ██║   ██║██║  ██║██╔══╝
                     ╚██████╔╝╚██████╗╚██████╔╝██████╔╝███████╗
                      ╚═════╝  ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝


  ╭──────────────────────────────────────────────────────────────────────────────╮
  │ Ask anything…                                                                │
  │                                                                              │
  │  BUILD   Gemini 3.5 Flash-Lite                                            0% │
  ╰──────────────────────────────────────────────────────────────────────────────╯

   try   build me a landing page for a coffee shop
         explain what this project does and how it fits together
         add a dark mode toggle that remembers the choice


                                             made and tested by om dixit · v1.68.1

A light crosses the wordmark once as it opens, and the three lines under the box are there so an empty screen has something to say. Once you are talking, each message you send is marked down its left edge in the same blue as the input, so your own words are easy to find in a long session — and each step the agent takes carries the shape of the work: a hollow diamond to look, a filled one to change, an arrow to run.

▌ build a notes dashboard

◇ Read 3 files
◆ Writing index.html +148 -0
▸ Running npm run dev

The dashboard is at http://localhost:3000, and `npm run dev` brings it back up.

╭──────────────────────────────────────────────────────────────────────────────────╮
│ now add a dark mode toggle                                                       │
│                                                                                  │
│  BUILD   Gemini 3.5 Flash-Lite                                                4% │
╰──────────────────────────────────────────────────────────────────────────────────╯

The status sits inside the input box because it describes the thing you are typing into. Three facts, no more: the live mode, the answering model, and how full the context window is. The percentage turns amber at 75%, which is where older turns start being folded into a summary. While a turn is running the middle of that row carries the spinner and the way out of it, and hands the space straight back when it finishes.

npm i -g ucode-agent

Then save your Google key (free at aistudio.google.com/apikey):

ucode login YOUR_KEY

It is written to ~/.ucode/.env as GEMINI_API_KEY. A .env in the project you are working on wins over that one, and a real environment variable wins over both.

Then, in any project:

ucode

Needs Node 22 or newer.

Served by Google (aistudio.google.com), with one key.

One key, every current Gemini model. Flash-Lite is the default; /model (or /models) shows the rest and switches.

When Google releases a newer one (a 3.9 Flash, say), /model finds it on its own and lists it — marked new, and paid if it is a Pro. ucode -m gemini-3.8-flash starts on a model.

Free limits are per model, and they start again at midnight in California (12:30 PM in India). When one model has used its free requests for the day, ucode says so — with when it comes back — and offers to carry on with Flash-Lite, which has its own 500; /model marks it USED UP until then. A Pro model on a key without billing is said to be not free, rather than retried. A per-minute limit is waited out exactly as long as Google says, and the next requests are spaced to fit it.

When Google is overloaded and Flash-Lite stops answering, ucode carries on with 3.5 Flash by itself and goes back to Flash-Lite a few minutes later; the newer Flash models and Gemma carry on with Flash-Lite the same way.

Twenty-one tools, and any MCP server you add. create_app, read_file, read_files, write_file, batch_write, edit_file, multi_edit, edit_files, rename_symbol, find_symbol, outline, type_of, add_block, list_dir, glob, grep, run_command, run_commands, look_at_app, web_search, deploy. Read-only calls run in parallel, and start the moment the model finishes writing them — while the rest of its reply is still arriving. Anything that writes runs on its own, in order.

It asks rather than guesses. type_of opens a language service on the TypeScript the project itself has installed and gives back the exact signature, the JSDoc, and where a thing is defined — inferred types included. find_symbol answers "where is this declared", which is the question grep is usually being asked badly. rename_symbol renames by code shape, knowing where strings and comments begin, because a find-and-replace that matched too much is the most common broken edit.

It checks itself as it goes. After a change: an incremental type check that answers in about a second rather than a cold minute, then the tests that reach the files just changed, then anything the running dev server has complained about since the last look. All three come back the way an error does, so the model fixes them without being told.

New apps are ready in seconds. A starter installed once is kept and hard-linked into the next app — the same files under another name, so it costs no extra disk and skips the wait entirely.

Apps start from a ready-made starter — and finish in the same call. create_app copies a starter that is already known to build, and takes the app's files with it, so a one-page app is a single round trip: the starter lands, the model's files are written over it, and the starter's own files come back inside the result so there is nothing to read afterwards.

The default starter is plain-html: one page, one stylesheet, one module, nothing to install and nothing to build. A tasks app, a game, a calculator or a visualisation is finished before a framework would have finished installing. next-shadcn is there for routes, a database or many screens — Next.js 16, TypeScript, Tailwind 4, shadcn/ui with 25 components, light/dark, toasts and a considered theme. Setting that up by hand is about four minutes (create-next-app and the shadcn CLI measured at 116s and 130s) plus a dozen round trips; the copy takes under a second, and its install runs in the background while the model writes the first components.

Built to be fast, and measured. A traced build of a small Next.js app went from 17 minutes and 116 model steps to about 6 minutes and 25 steps, by fixing where the time actually went:

• Edits return the file as it now stands, so the model does not re-read it.
• Files written more than a few steps ago stop being re-sent in full; the conversation stays small, so every step answers faster.
• A file-write whose JSON is malformed — a missing comma, an unescaped quote in the code, raw line breaks — is repaired instead of thrown away with all its output.
• An edit whose old_string is slightly off — a middle line remembered wrong, escapes written out, a blank line at either end, a different indent — still lands, through the fallback matchers from opencode's edit tool. Found in two places is still refused, and so is a match far bigger than what was asked for. replace_all does a rename in one call.
• A missing file comes back with the lookalikes beside it ("did you mean App.jsx?"), and a tool named with the wrong case runs as the tool it means, instead of each costing a round trip to learn a spelling.
• Every write is parsed on the spot, so a syntax error comes back in the same step rather than a minute later from a failed build.
• A failed build that is missing a component or package says exactly which command fixes it.
• The starter is the shadcn models already know (Radix), so the code they write compiles the first time.
• A new app goes out without the tools it has nothing to point at — no symbol lookup, no rename, no type query in an empty folder — and an instruction pack that loads itself sends its short form, with the full one a load_skill away. Both are re-read by the provider on every step, so what is not in the request is time off every one of them.
• Ready-made blocks for a page with no build step as well as for React: a list you can add to, tick off, rename and remove, a filter row, a localStorage store, a dialog, toasts, a theme toggle. Typing is the slowest part of a build, and each block is a hundred lines nobody has to type.
• A nested argument written the wrong way — a JSON string, a { path: contents } map — is read rather than refused. Each refusal was a round trip spent being told something that could simply be parsed.
• A tool that was not offered is refused rather than quietly run, so withholding one from a new project, or from plan mode, means what it says.
• The closing message is cut to eight lines. A build that ends with the request read back and every feature ticked off is a status report nobody asked for, and it is the last thing left on screen.

UCODE_TRACE=1 writes every model call and tool, with its duration, to ~/.ucode/trace.jsonl.

Measured on "build me a simple todo app" — same prompt, same model, two traced runs: 27 model calls, 8 failed tool calls, no finished app before this round of work; 14 model calls, no failures, a working app in under two minutes after it.

Deploy in one line. Say "deploy it", or type /deploy [folder], and the app goes live on Vercel. ucode picks a short project name that fits the app and is free (food-iq, else food-iq-app…), copies the app's .env keys to Vercel as encrypted variables, refuses code with a secret written into it (and says how to move it to a server route), and gives you the link. Deploying again updates the same link. Needs a token from vercel.com/account/tokens in ~/.ucode/.env as VERCEL_TOKEN=....

A look for every app. create_app takes a design preset — ocean, grove, sunset, graphite, violet or citrus — each a full light and dark palette with its own font, so apps stop looking like the same default blue.

Every turn can be taken back. /undo puts back every file the last turn changed — a rewritten file returns byte for byte, a file that did not exist before is removed again. Each write keeps the original the first time that turn touches it, so what comes back is the state before the turn rather than before the last of six edits to the same file. An agent that writes to your disk on its own should be able to take it back, whether or not the project has git.

It notices when it is going round in circles. The same failing edit, an edit that changes nothing, or a build failing on the same errors three times gets a firm, specific note; if that does not work, the turn moves to another model.

It never dies at the daily limit. When the free daily limit runs out mid-build, ucode counts down to the reset and carries on by itself.

You can see it working. The status row shows the current step with a light sweeping across it, the step count and the time, and each answer ends with ✓ Done in 6m 12s · 25 steps. When a dev server comes up, the app opens in your browser (UCODE_OPEN=0 turns that off).

/stats and ucode doctor. /stats shows the session's time, steps, tokens, files and builds. ucode doctor (or /doctor) checks Node, npm, git, the API key and today's free requests left, the browser, the Vercel token and the version, with the fix for anything wrong.

Parallel workers. When a build splits into parts that touch different files — the API route, the upload component, the results view — the model hands them to up to three workers that build at the same time, each line in the transcript tagged with the worker's name. File writes take turns so two never collide.

Installs that start early. The moment a package.json with dependencies is written, its install starts in the background while the rest of the app is still being written. An install the model asks for later waits for that one instead of running twice, and anything run in that folder waits for it too.

It opens what it built and uses it. Every app build ends with a look — not when the model remembers to ask for one, but as part of the same pass that type-checks. It opens the app in a real browser (the Edge or Chrome already on your machine, so there is nothing extra to download) at 375px and 1440px, and serves the folder itself when there is no dev server to point at, which is how a three-file app gets checked at all.

Then it uses the app. It types into the first field, presses Enter, and clicks the button that submits — and if the page gains no elements, changes no text and stores nothing, that is reported as the thing to fix before anything else. A page that renders and has no working behaviour passes a type check, a syntax check and a screenshot; the only way to find out is to press something.

It also reports console errors, failed requests, content that spills off a phone screen, broken images and unlabeled controls, saves screenshots to .ucode/screenshots, and has Gemini review them the way a designer would. The model fixes what it finds before calling the app done. Both widths load at once, and the designer review — the slow part — runs on the first look at an app in each request and is skipped, not waited on, when the vision model is busy. The look after the fixes re-runs only the fast checks: a few seconds.

Errors fixed before you see them. When the model says it is done, ucode type-checks every file it changed — tsc --noEmit for TypeScript projects, a syntax check for JavaScript and Python — and hands any errors back to fix, up to three rounds.

A plan you can see. For longer jobs the model keeps a short checklist, with a bar across the top for how far along it is and one row per step, so the one in progress is findable without reading the rest:

  ━━━━──────  2/5
    ✓ Scaffold
    ✓ Upload
    ▸ Score dial
    ○ Findings
    ○ Polish

It knows the project before it asks. Each turn starts with a map of every file and the names each code file exports, so the model goes straight to the right file instead of searching for it.

Project memory. UCODE.md in a project — and ~/.ucode/UCODE.md for how you like to work everywhere — is read at the start of every turn. /remember <note> adds a line to it.

Edits that never guess. edit_file matches exactly once or it fails, and when it fails it says why. It tolerates what does not matter — tabs against spaces, a different indent depth, Windows line endings — and re-indents the replacement to fit the file, but a match found twice is still refused. edit_files changes several files in one call, and writes none of them if any edit fails.

Diffs with real line numbers. Removed lines are numbered where they were, added lines where they now are. Numbers you can jump to, not decoration.

Live commentary. ● Listing src, ● Running npm test — what it is doing, as it does it, named after the file or command rather than the tool.

Two modes. Build edits and runs. Plan reads and researches with the writing tools withheld, which is stronger than asking a model nicely. ctrl+b swaps them; the chip inside the input box says which is live.

Sessions. Everything is on disk under ~/.ucode/sessions, saved after every step. /resume lists them with what each one was actually about, the ones from this folder first. Press d twice on one to delete it — the list stays open, so clearing out several is quick — or /session delete 2,5.

It updates itself. Each launch checks npm in the background and, if there is a newer version, installs it while you work. The next launch is the new one. Set UCODE_NO_UPDATE=1 to turn that off.

A context window that folds rather than forgets. Past 75% the oldest turns are summarised instead of dropped, never cutting between a tool call and its result. The full history stays on disk regardless.

Screenshots. Mention a .png in your message and it gets attached.

A skill is a folder with a SKILL.md: frontmatter, then instructions. Only the names and one-line descriptions go into the system prompt — a body is pulled in when it is wanted, so the prompt stays the same size however many you add.

Every skill loads itself when the request calls for it — an app pulls in ui-ux and build-app, "it crashes" pulls in debug, an AI feature pulls in ai-features, an API key pulls in security — so the whole skill is in context before the model takes its first step. Waiting for the model to decide it needs design guidance means finding out it did not after the app is built.

Add your own in .ucode/skills/<name>/SKILL.md inside a project. A project skill shadows a built-in of the same name. Give it an auto: line and it loads itself too:

---
name: house-style
description: How we write services here.
auto: endpoint, handler, migration
---

Everything after the frontmatter is the instruction.

ctrl+b plan/build · click + file (or ctrl+o) to add a picture or file · esc stops a running turn · ctrl+d quits · ↑ ↓ scroll the conversation, or walk history once you are typing · tab completes a command

Type / and the commands pop up over the input box, narrowing as you type: ↑ ↓ to choose, enter to run, tab to fill it in and add more, esc to close. Commands are not echoed into the chat (only /deploy is, since it starts real work), so typing one on the start screen leaves you on the start screen. The rest opens over the input box too, not in the chat — the model and conversation pickers, /help, /stats, /doctor, /mcp, /permissions, /skills, /theme, /diff (↑ ↓ scrolls, esc closes) — and every question before a command runs: y, n or a (always) then enter, or the arrows then enter. enter on its own is no, and anything else you type is sent as a message, so a question that pops up mid-sentence is never answered by it.

╭──────────────────────────────────────────────────────────────────────────╮
│ /stats    time, steps and tokens this session                            │
│ /skills   what ucode knows how to do                                     │
│ enter runs · tab completes · esc closes                                  │
╰──────────────────────────────────────────────────────────────────────────╯

╭──────────────────────────────────────────────────────────────────────────╮
│ /s                                                                       │
│                                                                          │
│  BUILD   Gemini 3.5 Flash-Lite                                        4% │
╰──────────────────────────────────────────────────────────────────────────╯

Press ctrl+t (or click mic, or type /mic) and say what you want — "make me a quiz app about planets". The chip turns red while it listens. enter stops and sends it; ctrl+t stops and puts the words in the box to check first; esc throws it away. It stops by itself after two minutes.

Gemini writes down what you said, so nothing extra is needed beyond your key. Recording uses what the computer already has: Windows' built-in recorder, sox or ffmpeg on macOS (brew install sox), arecord or sox on Linux. If a quiet mic is taken for silence, set UCODE_MIC_QUIET lower than 800.

Just ask: "make ucode orange with the arc spinner", "make my terminal navy with a bigger font", "make the terminal a bit see-through". Or use /theme:

/theme                   what it looks like now, and the choices
/theme orange            a new colour at once (a name, #ff8c2b, or rgb(...))
/theme reset             ucode's own blue again
/theme terminal reset    the terminal back the way it was

A new look — accent and spinner (dots, line, arc, circle, square, bounce, pulse, star) — lasts until you close ucode; the next launch is ucode's own blue again. The credit under the logo, "made and tested by om dixit", always stays: no look changes it.

The terminal is changed the way each one allows, after you say yes:

A file .ucode/commands/explain.md (or ~/.ucode/commands/ for every project) becomes /explain. Its text is the prompt; $ARGUMENTS is replaced by whatever you type after the command.

Connect tools from any MCP server — library docs, GitHub, a database:

ucode mcp add context7 npx -y @upstash/context7-mcp
ucode mcp add github --url https://api.githubcopilot.com/mcp/ --header "Authorization=Bearer ${GITHUB_TOKEN}"
ucode mcp list
ucode mcp remove github

They are saved in ~/.ucode/mcp.json (--project puts them in this folder's .ucode/mcp.json). ucode asks before each MCP tool runs; answer a to always allow that tool. A project's own servers and hooks only run once you approve them.

.ucode/settings.json (or ~/.ucode/settings.json):

{
  "commands": "ask",
  "allow": ["npm test", "git status"],
  "hooks": {
    "afterEdit": ["npx prettier --write {files}"],
    "beforeCommand": ["node guard.js"]
  }
}

"commands": "ask" puts every command to you first (/permissions ask); answering a adds it to allow. A beforeCommand hook that exits non-zero stops the command; it sees it in UCODE_COMMAND.

ucode -p "fix the failing test"            prints the answer
ucode -p "make a quiz app" --json --yes    one JSON line: ok, answer, files, steps, requests, time

Progress goes to stderr. With no --yes, anything that would be asked is declined. npm run eval runs ten real jobs this way and checks each one — use it before a release (it spends about 30 free requests, and takes about seven minutes).

Any OpenAI-compatible server works, Ollama on your own computer included — free and offline:

UCODE_BASE_URL=http://localhost:11434/v1 UCODE_MODEL=qwen2.5-coder ucode

• Thinking levels. Flash-Lite does not think at all unless asked. ucode asks for a little on every step (it costs nothing on a straightforward write), more on the first step of a build, and the most when a fix has already failed. UCODE_THINK=0 turns it off.
• A design direction for every build — a tone, two typefaces and an accent — so two apps never come out the same, and a check for the generated look (the starter's colours, Inter, purple gradients, gradient text, emoji icons) that sends it back to be fixed. UCODE_DESIGN_CHECK=0 turns the check off.
• Learns from its mistakes. Problems ucode keeps catching are counted in ~/.ucode/lessons.json, and the common ones are warned about before the next build.
• Tries a different approach when the same problem survives a fix, and offers to hand that fix to Gemini 3.5 Flash — only if you say yes, since it has about 20 free requests a day.
• Changes to existing code get their own rules: find the code, read only what is involved, make the smallest change in the code's own style.
• Stays under the free limit. Requests are spaced to Google's per-minute limit instead of being refused and waited out; /stats shows how many were sent.

ucode [options]

  -m, --model <id>   which model to use
  -C, --cwd <dir>    work in another directory
      --plan         start in plan mode
  -p, --print <task> do one task with no keyboard, print the answer, exit
      --json         with -p: one JSON object about the run
  -y, --yes          with -p: say yes to anything that would be asked
      --debug        print stack traces when something breaks
  -v, --version      print the version
  -h, --help         the above

Environment overrides: UCODE_MODEL, UCODE_WORKER_MODEL (a faster model for parallel workers), UCODE_WORKER_STEPS, UCODE_MAX_CONTEXT_TOKENS, UCODE_MAX_STEPS, UCODE_MAX_TOOL_OUTPUT, UCODE_REQUEST_TIMEOUT_MS, UCODE_STALL_MS (how long a silent reply is waited on before asking again, 60s), UCODE_BASE_URL, UCODE_NO_UPDATE, UCODE_THINK=0, UCODE_DESIGN_CHECK=0, UCODE_RPM (requests a minute before pacing, 0 = off), UCODE_RIPGREP=0.

Search uses ripgrep (rg) when it is installed — much faster on a big project — and its own search otherwise.

Web search needs a Tavily key — free, 1000 searches a month, no card. Without one, ucode answers from what it knows and says that it could not check.

ucode.js              the command: arguments in, Agent out
src/core/loop.js      the agent loop, the system prompt, the slash commands
src/core/provider.js  the only file that knows which provider answers
src/core/history.js   sessions on disk
src/core/window.js    folding a long conversation to fit
src/core/skills.js    loading skills, and deciding which load themselves
src/core/context.js   the project map and project memory
src/core/failure.js   one error shape: what, why, what next
src/core/scope.js     what a request carries: build scope, design direction, edit rules
src/core/genericcheck.js  the check for a generated-looking design
src/core/lessons.js   mistakes counted across sessions, warned about up front
src/core/snapshot.js  the project before every turn, for /undo
src/core/settings.js  permissions, always-allow, hooks, project trust
src/core/mcp.js       the MCP client: stdio and HTTP servers, no SDK
src/core/headless.js  ucode -p: one job, no keyboard
src/tools/            the twenty-one tools, plus their shared plumbing
src/ui/screen.js      the full-screen interface
src/ui/plain.js       the same interface for when there is no terminal
src/ui/theme.js       colour, boxes, and the string maths behind both

Everything above provider.js speaks one small provider-neutral message format. Moving to another host means rewriting that one file.

Every failure carries three things — what was attempted, what failed, and what to do next — so no screen ever has to fall back on a stack trace. Tool failures are handed to the model as text instead, which is why they read like instructions.

git clone https://github.com/sppideey/ucode-agent
cd ucode-agent
npm install
npm link      # puts `ucode` on PATH, pointing at this checkout
npm test

npm link matters while developing: it symlinks the global command to your working copy, so an edit is live on the next launch. Running npm i -g ucode-agent replaces that with a frozen copy from the registry and your edits stop taking effect.

The tests need no network and no framework — node test/run.js runs them all.

Contributions are welcome — see CONTRIBUTING.md (sign off with git commit -s).

ucode is free software under the GNU AGPL v3 (LICENSE) with three additional terms (NOTICE): every copy and every changed version keeps the credit "made and tested by om dixit" on screen, a changed version is marked as changed, and the ucode name and logo stay ucode's.

Contributions: CONTRIBUTING.md.

The edit matchers, the summary template, the context-overflow and transient-error patterns and tool-name repair are adapted from opencode (MIT); see THIRD_PARTY_NOTICES.md.