ucode-agent 1.65.0 → 1.67.1

package/README.md

@@ -1,631 +1,28 @@
-# ucode
-
-A coding agent that lives in your terminal. It reads your code, edits it, runs
-your commands, and keeps every conversation on disk. It runs on Google's
-Gemini models, free with a key.
-
-## At a glance
-
-| | |
-| --- | --- |
-| **Builds** | a whole app in about a minute, from a starter that already works, opened for you when it does |
-| **Thinks** | a thinking level per step — cheap on easy steps, more on the plan, most when a fix has failed |
-| **Designs** | its own tone, typefaces and accent for every app, and a check that sends the generated look back |
-| **Checks** | types, syntax, related tests, the running server's errors, and the page itself — opened and clicked |
-| **Fixes** | sends problems back to the model, tries a different approach when a fix fails, learns the common ones |
-| **Edits real code** | finds the code first, smallest change in the code's own style; renames by code shape |
-| **Undoes** | `/undo [n]` puts the whole project back, including what commands changed |
-| **Git** | `/diff`, `/commit` with a written message, `/review` for bugs |
-| **Extends** | MCP servers, hooks, skills, your own slash commands |
-| **Restyles** | itself and your terminal, when you ask: "make ucode orange and my terminal navy" |
-| **Automates** | `ucode -p "task" --json` for scripts and CI; `npm run eval` runs ten real jobs |
-| **Stays free** | Gemini's free tier, paced to its per-minute limit — or Ollama, offline |
-
-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
-
-
-                                                                           v1.65.0
-```
-
-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.
-
-## Install
-
-```bash
-npm i -g ucode-agent
-```
-
-Then save your Google key (free at [aistudio.google.com/apikey](https://aistudio.google.com/apikey)):
-
-```bash
-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:
-
-```bash
-ucode
-```
-
-Needs Node 22 or newer.
-
-## The models
-
-Served by Google (aistudio.google.com), free with a key.
-
-| Model | For |
-| --- | --- |
-| **Gemini 3.5 Flash-Lite** ★ | the default — fast, reliable with tools, 500 free requests a day |
-| Gemini 3.5 Flash | smarter, but only about 20 free requests a day |
-| Gemini 3.1 Flash-Lite | older and lighter, 500 free requests a day |
-
-`/model` shows them and switches. `ucode -m gemini-3.5-flash` starts on one.
-
-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.
-
-## What it does
-
-**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.
+<div align="center">
 
-**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.
-
-## Skills
-
-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.
-
-| Skill | For |
-| --- | --- |
-| `ui-ux` | interfaces: direction, tokens, layout, states, motion, accessibility |
-| `build-app` | going from nothing to something running, and proving it runs |
-| `debug` | finding the real cause instead of the first plausible one |
-| `code-review` | reviewing a change the way a careful colleague would |
-| `write-tests` | tests that fail for the right reason |
-| `ai-features` | model-backed features: prompts with rules, validated JSON, images, failure handling |
-| `security` | secrets, auth, ownership checks, injection, XSS, CSRF, SSRF, uploads |
-| `performance` | measure first, find the real bottleneck, prove the win with numbers |
-| `refactor` | change the shape of code without changing what it does |
-
-**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:
-
-```markdown
----
-name: house-style
-description: How we write services here.
-auto: endpoint, handler, migration
----
-
-Everything after the frontmatter is the instruction.
-```
-
-## Commands
-
-| | |
-| --- | --- |
-| `/help` | the list |
-| `/model` | show the models and switch — `/models` does the same |
-| `/resume` | pick up an earlier conversation — `/session`, `/sessions` too |
-| `/session delete 2,5` | delete saved conversations by number (or `d d` in the list) |
-| `/new` | save this one and start fresh |
-| `/remember <note>` | add a standing note to this project's `UCODE.md` |
-| `/undo [n]` | put the project back as it was before the last turn — or `n` turns — including what commands changed |
-| `/diff` | what has changed this session |
-| `/commit [msg]` | commit the changes, with a message written from the diff if you give none |
-| `/review` | read the uncommitted changes for bugs, changing nothing |
-| `/init` | read the project and write its `UCODE.md` |
-| `/mcp` | connected MCP servers and their tools |
-| `/permissions [ask\|auto]` | ask before every command, or run them; what is always allowed |
-| `/theme [what]` | change how ucode or your terminal looks — or just ask in words |
-| `/look [url]` | open the running app and report what is on the page |
-| `/deploy [folder]` | put the app online and get its link |
-| `/mic` | say what you want instead of typing it — same as `ctrl+t` |
-| `/stats` | time, steps and tokens this session |
-| `/doctor` | check that everything ucode needs is working |
-| `/skills` | what it knows how to do, and what is loaded |
-| `/search <query>` | look something up on the web |
-| `/copy` | last reply to the clipboard |
-| `/clear` | clear the screen, keep the conversation |
-| `/exit` | save and quit |
-
-`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
-
-### Speak instead of typing
-
-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.
-
-### Change how it looks — and your terminal
-
-Just ask: "make ucode orange with the arc spinner", "put my name under the
-logo", "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
-```
-
-ucode's look is saved in `~/.ucode/theme.json` — accent, spinner (`dots`,
-`line`, `arc`, `circle`, `square`, `bounce`, `pulse`, `star`) and the line
-under the logo — so it survives restarts and updates.
-
-The terminal is changed the way each one allows, after you say yes:
-
-| Terminal | What changes | How long |
-| --- | --- | --- |
-| Windows Terminal | background, text, cursor, font, size, opacity | kept, every tab (the old settings are backed up) |
-| Terminal.app (macOS) | background, text, cursor, font, size | this window |
-| iTerm2 (macOS) | background, text, cursor | this session |
-| Linux, VS Code and others | background, text, cursor | this session |
-
-### Your own commands
-
-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.
-
-### MCP servers
-
-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.
-
-### Permissions and hooks
-
-`.ucode/settings.json` (or `~/.ucode/settings.json`):
-
-```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`.
-
-### Run it without a keyboard
-
-```
-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).
-
-### Other models
-
-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
-```
-
-## How it thinks
-
-- **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.
-
-## Options
-
-```
-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
-```
-
-## Configuration
-
-| | |
-| --- | --- |
-| `~/.ucode/.env` | `GEMINI_API_KEY`, and `TAVILY_API_KEY` for web search |
-| `~/.ucode/settings.json`, `.ucode/settings.json` | permissions, always-allowed commands, hooks |
-| `~/.ucode/mcp.json`, `.ucode/mcp.json` | MCP servers |
-| `.ucode/commands/*.md` | your own slash commands |
-| `~/.ucode/snapshots/` | the project before each turn, for `/undo` |
-| `~/.ucode/lessons.json` | mistakes ucode keeps catching, warned about next time |
-| `~/.ucode/sessions/` | one JSON per conversation |
-| `.ucode/skills/` | skills belonging to a project |
-| `UCODE.md` | project memory, read every turn |
-| `~/.ucode/UCODE.md` | your own standing instructions, for every project |
-
-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.
-
-## How it is put together
+# ucode
 
-```
-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
-```
+**A free, open-source AI coding agent for your terminal.**<br>
+Builds whole apps in about a minute on Google Gemini's free tier — then opens them and clicks through to check its own work.
 
-Everything above `provider.js` speaks one small provider-neutral message
-format. Moving to another host means rewriting that one file.
+[![npm](https://img.shields.io/npm/v/ucode-agent?color=4d8dff&label=npm)](https://www.npmjs.com/package/ucode-agent)
+[![downloads](https://img.shields.io/npm/dm/ucode-agent?color=4d8dff)](https://www.npmjs.com/package/ucode-agent)
+[![tests](https://github.com/sppideey/ucode-agent/actions/workflows/test.yml/badge.svg)](https://github.com/sppideey/ucode-agent/actions/workflows/test.yml)
+[![license](https://img.shields.io/badge/license-AGPL--3.0-4d8dff)](LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A522-4d8dff)](https://nodejs.org)
+[![stars](https://img.shields.io/github/stars/sppideey/ucode-agent?style=social)](https://github.com/sppideey/ucode-agent/stargazers)
 
-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.
+<img src="https://raw.githubusercontent.com/sppideey/ucode-agent/main/.github/ucode-hero.png" alt="ucode in a terminal: a tasks app built in 58 seconds, with the command list popped up over the input box" width="900">
 
-## Development
+</div>
 
 ```bash
-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 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
 ```
 
-`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.
-
-## Licence
-
-Dual-licensed under either of, at your option:
-
-- MIT — see [LICENSE](LICENSE)
-- Apache License 2.0 — see [LICENSE-APACHE](LICENSE-APACHE)
-
-Made with ❤️ by om dixit.
-
-The edit matchers, the summary template, the context-overflow and transient-error
-patterns and tool-name repair are adapted from
-[opencode](https://opencode.ai) (MIT); see
-[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+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.