ucode-agent 1.63.0 → 1.65.0

package/README.md

@@ -4,6 +4,23 @@ 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:
 
@@ -19,7 +36,7 @@ corner:
   ╭──────────────────────────────────────────────────────────────────────────────╮
   │ › Ask anything…                                                              │
   │                                                                              │
-  │  BUILD   North Mini Code                                                  0% │
+  │  BUILD   Gemini 3.5 Flash-Lite                                            0% │
   ╰──────────────────────────────────────────────────────────────────────────────╯
 
    try   build me a landing page for a coffee shop
@@ -27,7 +44,7 @@ corner:
          add a dark mode toggle that remembers the choice
 
 
-                                                                           v1.62.7
+                                                                           v1.65.0
 ```
 
 A light crosses the wordmark once as it opens, and the three lines under the box
@@ -49,7 +66,7 @@ The dashboard is at http://localhost:3000, and `npm run dev` brings it back up.
 ╭──────────────────────────────────────────────────────────────────────────────────╮
 │ › now add a dark mode toggle                                                     │
 │                                                                                  │
-│  BUILD   North Mini Code                                                      4% │
+│  BUILD   Gemini 3.5 Flash-Lite                                                4% │
 ╰──────────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -101,7 +118,7 @@ When Google is overloaded and Flash-Lite stops answering, ucode carries on with
 
 ## What it does
 
-**Twenty-one tools.** `create_app`, `read_file`, `read_files`, `write_file`,
+**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
@@ -253,7 +270,7 @@ 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 Nemotron Nano Omni review them the way a designer
+`.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:
@@ -365,7 +382,14 @@ Everything after the frontmatter is the instruction.
 | `/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` | put back every file the last turn changed |
+| `/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` |
@@ -393,6 +417,112 @@ 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
 
 ```
@@ -401,6 +531,9 @@ 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
@@ -410,7 +543,12 @@ ucode [options]
 
 | | |
 | --- | --- |
-| `~/.ucode/.env` | `UCODE_API_KEY`, and `TAVILY_API_KEY` for web search |
+| `~/.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 |
@@ -420,7 +558,11 @@ 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_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.
@@ -436,6 +578,13 @@ 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

package/package.json

@@ -1,64 +1,65 @@
-{
-  "name": "ucode-agent",
-  "version": "1.63.0",
-  "description": "ucode - a terminal coding agent that reads, edits and runs your code, on Google Gemini models.",
-  "type": "module",
-  "main": "ucode.js",
-  "bin": {
-    "ucode": "ucode.js"
-  },
-  "files": [
-    "ucode.js",
-    "src/",
-    "skills/",
-    "templates/",
-    "THIRD_PARTY_NOTICES.md",
-    "LICENSE-APACHE"
-  ],
-  "scripts": {
-    "start": "node ucode.js",
-    "test": "node test/run.js",
-    "prepublishOnly": "node scripts/no-bundled-key.js && node test/run.js",
-    "hooks": "node scripts/install-hooks.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/sppideey/ucode-agent.git"
-  },
-  "bugs": {
-    "url": "https://github.com/sppideey/ucode-agent/issues"
-  },
-  "homepage": "https://github.com/sppideey/ucode-agent#readme",
-  "engines": {
-    "node": ">=22"
-  },
-  "keywords": [
-    "agent",
-    "cli",
-    "terminal",
-    "coding-agent",
-    "llm",
-    "gemini",
-    "google-gemini",
-    "ai"
-  ],
-  "author": "om dixit",
-  "license": "(MIT OR Apache-2.0)",
-  "dependencies": {
-    "@babel/parser": "^7.29.9",
-    "chalk": "^6.0.0",
-    "dotenv": "^18.0.3",
-    "jsonrepair": "^3.15.0",
-    "marked": "^15.0.12",
-    "marked-terminal": "^7.3.0",
-    "openai": "^7.23.0",
-    "playwright-core": "^1.63.0"
-  },
-  "devDependencies": {
-    "@types/node": "^26.6.2",
-    "typescript": "^5.9.3"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "ucode-agent",
+  "version": "1.65.0",
+  "description": "ucode - a terminal coding agent that reads, edits and runs your code, on Google Gemini models.",
+  "type": "module",
+  "main": "ucode.js",
+  "bin": {
+    "ucode": "ucode.js"
+  },
+  "files": [
+    "ucode.js",
+    "src/",
+    "skills/",
+    "templates/",
+    "THIRD_PARTY_NOTICES.md",
+    "LICENSE-APACHE"
+  ],
+  "scripts": {
+    "start": "node ucode.js",
+    "test": "node test/run.js",
+    "prepublishOnly": "node scripts/no-bundled-key.js && node test/run.js",
+    "hooks": "node scripts/install-hooks.js",
+    "eval": "node test/evals/run.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sppideey/ucode-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sppideey/ucode-agent/issues"
+  },
+  "homepage": "https://github.com/sppideey/ucode-agent#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "agent",
+    "cli",
+    "terminal",
+    "coding-agent",
+    "llm",
+    "gemini",
+    "google-gemini",
+    "ai"
+  ],
+  "author": "om dixit",
+  "license": "(MIT OR Apache-2.0)",
+  "dependencies": {
+    "@babel/parser": "^7.29.9",
+    "chalk": "^6.0.0",
+    "dotenv": "^18.0.3",
+    "jsonrepair": "^3.15.0",
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0",
+    "openai": "^7.23.0",
+    "playwright-core": "^1.63.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/core/commands.js

@@ -0,0 +1,44 @@
+/**
+ * commands.js — slash commands the user writes themselves.
+ *
+ *   ~/.ucode/commands/<name>.md          yours, everywhere
+ *   <project>/.ucode/commands/<name>.md  this project's (wins over yours)
+ *
+ * The file is a prompt. `/name some words` sends it, with $ARGUMENTS replaced
+ * by the words — or the words added at the end when the file has no
+ * $ARGUMENTS. Its first line is what /help shows.
+ */
+
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const USER_COMMANDS = path.join(os.homedir(), '.ucode', 'commands');
+export const projectCommands = (cwd) => path.join(cwd, '.ucode', 'commands');
+
+async function readDir(dir) {
+  const found = new Map();
+  for (const entry of await fs.readdir(dir, { withFileTypes: true }).catch(() => [])) {
+    if (!entry.isFile() || !/\.md$/i.test(entry.name)) continue;
+    const name = entry.name.replace(/\.md$/i, '').toLowerCase();
+    if (!/^[a-z0-9][\w-]*$/.test(name)) continue;
+    const body = await fs.readFile(path.join(dir, entry.name), 'utf8').catch(() => null);
+    if (!body?.trim()) continue;
+    const first = body.trim().split('\n')[0].replace(/^#+\s*/, '').trim();
+    found.set(name, { name, body: body.trim(), description: first.slice(0, 70) });
+  }
+  return found;
+}
+
+/** Every command, by name without the slash. */
+export async function loadCommands(cwd, { userDir = USER_COMMANDS } = {}) {
+  const [mine, project] = await Promise.all([readDir(userDir), readDir(projectCommands(cwd))]);
+  return new Map([...mine, ...project]);
+}
+
+/** The prompt a command sends, given what was typed after it. */
+export function expandCommand(body, args = '') {
+  const words = String(args).trim();
+  if (body.includes('$ARGUMENTS')) return body.split('$ARGUMENTS').join(words);
+  return words ? `${body}\n\n${words}` : body;
+}

package/src/core/genericcheck.js

@@ -0,0 +1,147 @@
+/**
+ * genericcheck.js — the generated look, caught in code.
+ *
+ * The rules against it were already written down, in the system prompt and
+ * the ui-ux skill: not the starter's palette, not Inter at every size, not a
+ * purple-to-blue gradient, not emoji standing in for icons. Flash-Lite reads
+ * them and ships the starter's teal anyway. A rule the model can skip is a
+ * suggestion; a check that hands the problem back is a rule.
+ *
+ * Everything here is a few regular expressions over files already on disk —
+ * milliseconds, no model call. Only a hit costs anything: one fix round.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/** The starter's own accent, which means nobody chose one. */
+const STARTER = {
+  'plain-html': { files: ['styles.css'], token: /--accent\s*:\s*#2dd4bf\b/i },
+  'next-shadcn': { files: ['src/app/globals.css'], token: /--primary\s*:\s*oklch\(\s*0\.53\s+0\.2\s+264\s*\)/i },
+};
+
+/** Files that carry a Next.js app's look. */
+const LOOK_FILES = {
+  'next-shadcn': ['src/app/globals.css', 'src/app/layout.tsx', 'src/app/page.tsx'],
+};
+
+const NAMED = {
+  purple: 300, violet: 300, indigo: 275, blueviolet: 271, mediumpurple: 260, rebeccapurple: 270,
+  darkviolet: 282, slateblue: 248, mediumslateblue: 249, darkslateblue: 248, magenta: 300, fuchsia: 300,
+  blue: 240, royalblue: 225, mediumblue: 240, dodgerblue: 210, cornflowerblue: 219,
+};
+
+/** Hue in degrees of one colour, or null for a grey or something unreadable. */
+export function hueOf(colour) {
+  const c = String(colour).trim().toLowerCase();
+  if (NAMED[c] !== undefined) return NAMED[c];
+
+  let r; let g; let b;
+  const hex = /^#([0-9a-f]{3,8})$/.exec(c);
+  if (hex) {
+    let h = hex[1];
+    if (h.length === 3 || h.length === 4) h = [...h.slice(0, 3)].map((x) => x + x).join('');
+    [r, g, b] = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255);
+  }
+  const rgb = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/.exec(c);
+  if (rgb) [r, g, b] = rgb.slice(1, 4).map((v) => Number(v) / 255);
+  const hsl = /^hsla?\(\s*([\d.]+)(?:deg)?[\s,]+([\d.]+)%/.exec(c);
+  if (hsl) return Number(hsl[2]) < 25 ? null : Number(hsl[1]) % 360;
+  const lch = /^oklch\(\s*[\d.]+%?\s+([\d.]+)\s+([\d.]+)/.exec(c);
+  // oklch puts blue near 264 and purple near 300-310; shift to the same wheel as hsl.
+  if (lch) return Number(lch[1]) < 0.06 ? null : (Number(lch[2]) - 25 + 360) % 360;
+  if (r === undefined) return null;
+
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const d = max - min;
+  const light = (max + min) / 2;
+  const sat = d === 0 ? 0 : d / (1 - Math.abs(2 * light - 1));
+  if (sat < 0.25) return null;
+  let hue;
+  if (max === r) hue = ((g - b) / d) % 6;
+  else if (max === g) hue = (b - r) / d + 2;
+  else hue = (r - g) / d + 4;
+  return Math.round((hue * 60 + 360) % 360);
+}
+
+/** Every gradient's argument list, brackets balanced. */
+function gradients(css) {
+  const found = [];
+  const re = /(?:linear|radial|conic)-gradient\(/gi;
+  let m;
+  while ((m = re.exec(css))) {
+    let depth = 1;
+    let i = re.lastIndex;
+    for (; i < css.length && depth; i++) {
+      if (css[i] === '(') depth++;
+      else if (css[i] === ')') depth--;
+    }
+    found.push(css.slice(re.lastIndex, i - 1));
+  }
+  return found;
+}
+
+const COLOUR = /#[0-9a-f]{3,8}\b|(?:rgba?|hsla?|oklch)\([^)]*\)|\b[a-z]+\b/gi;
+
+/** The purple-to-blue gradient: every coloured stop blue-to-purple, at least one of them purple. */
+export function purpleGradient(css) {
+  return gradients(css).some((args) => {
+    const hues = (args.match(COLOUR) ?? []).map(hueOf).filter((h) => h !== null);
+    return hues.length >= 2 && hues.every((h) => h >= 200 && h <= 330) && hues.some((h) => h >= 250);
+  });
+}
+
+/**
+ * The files that make up the page. For a plain page that is index.html and
+ * whatever it actually links: a starter stylesheet left behind, unlinked,
+ * says nothing about how the app looks.
+ */
+async function lookFiles(dir, template) {
+  if (template !== 'plain-html') return LOOK_FILES[template] ?? [];
+  const html = await fs.readFile(path.join(dir, 'index.html'), 'utf8').catch(() => '');
+  const linked = [...html.matchAll(/<(?:link|script)\b[^>]*\b(?:href|src)\s*=\s*["']([^"'?#]+)/gi)]
+    .map((m) => m[1])
+    .filter((f) => !/^(?:[a-z]+:)?\/\//i.test(f) && /\.(?:css|m?js)$/i.test(f));
+  return ['index.html', ...new Set(linked)];
+}
+
+/** Problems with the look of the app in `dir`, as lines for the model. Never throws. */
+export async function genericLook(dir, template = 'plain-html') {
+  const files = await lookFiles(dir, template);
+  const texts = await Promise.all(files.map((f) => fs.readFile(path.join(dir, f), 'utf8').catch(() => '')));
+  const all = texts.join('\n');
+  if (!all.trim()) return [];
+
+  const problems = [];
+  const starter = STARTER[template];
+  if (starter) {
+    const own = starter.files.filter((f) => files.includes(f) || template !== 'plain-html');
+    const texts2 = await Promise.all(own.map((f) => fs.readFile(path.join(dir, f), 'utf8').catch(() => '')));
+    if (texts2.some((t) => starter.token.test(t))) {
+      problems.push('The accent is still the starter\'s own colour, so the app looks like every other one built from it. Pick an accent for this app and set it in the tokens.');
+    }
+  }
+  if (/font-family\s*:\s*["']?Inter["']?\s*[,;}]|--font-[\w-]+\s*:\s*["']?Inter["']?\s*[,;]|family=Inter(?![+\w])|import\s*\{[^}]*\bInter\b[^}]*\}\s*from\s*["']next\/font\/google/i.test(all)) {
+    problems.push('The type is Inter, the default of generated apps. Choose a typeface with a character that fits this app.');
+  }
+  if (purpleGradient(all)) {
+    problems.push('There is a purple-to-blue gradient, the most recognisable mark of a generated design. Use the app\'s own accent, flat or with a quiet tint.');
+  }
+  if (/(?:-webkit-)?background-clip\s*:\s*text/i.test(all)) {
+    problems.push('There is gradient text (background-clip: text). Set headings in a solid colour and let the type carry them.');
+  }
+  const emoji = all.match(/<(?:button|h[1-6])\b[^>]*>\s*\p{Extended_Pictographic}/gu) ?? [];
+  if (emoji.length >= 3) {
+    problems.push(`Emoji stand in for icons in ${emoji.length} buttons or headings. Use small inline SVG icons or plain words.`);
+  }
+  return problems;
+}
+
+/** The fix-round text for a list of look problems. */
+export function genericMessage(problems) {
+  return 'ucode checked the design for the generated look and found:\n' +
+    problems.map((p) => `- ${p}`).join('\n') +
+    '\nFix these in the design tokens and styles only - a new accent, a new typeface. Do not ' +
+    'restructure the app or change what it does.';
+}

package/src/core/headless.js

@@ -0,0 +1,73 @@
+/**
+ * headless.js — `ucode -p "task"`: one job, no keyboard, then exit.
+ *
+ * For scripts, CI and the eval set. Progress goes to stderr, the answer to
+ * stdout (or, with --json, one JSON object describing the run), and the exit
+ * code says whether it worked. Nobody is there to approve anything, so every
+ * question is answered no — unless --yes says to answer yes.
+ */
+
+import { Readable } from 'node:stream';
+import { Plain } from '../ui/plain.js';
+import { Agent } from './loop.js';
+import { requestCount } from './provider.js';
+import { stopServers } from '../tools/shell.js';
+import { closeBrowser } from '../tools/browser.js';
+
+export class Headless extends Plain {
+  constructor({ cwd, yes = false }) {
+    super({ cwd, input: Readable.from([]), output: process.stderr });
+    this.yes = yes;
+    this.answer = '';
+  }
+
+  assistant(text, opts = {}) {
+    super.assistant(text, opts);
+    if (!opts.replay && String(text).trim()) this.answer = String(text).trim();
+  }
+
+  confirm({ action }) {
+    this.note(`${this.yes ? 'approved' : 'declined'} (no one to ask): ${action}`);
+    return Promise.resolve(this.yes);
+  }
+}
+
+/** Run one prompt. Resolves to the exit code. */
+export async function runHeadless({ cwd, prompt, json = false, yes = false, plan = false, write = (s) => process.stdout.write(s) }) {
+  const ui = new Headless({ cwd, yes });
+  const agent = new Agent({ cwd, ui });
+  if (plan) ui.mode = 'plan';
+  const started = Date.now();
+  const sent = requestCount();
+  let error = null;
+  try {
+    await agent.bootstrap();
+    agent.startMcp();
+    await agent.mcpStarting;
+    await agent.turn(prompt);
+  } catch (err) {
+    error = err;
+    ui.error(err);
+  } finally {
+    stopServers();
+    agent.mcp?.close();
+    await closeBrowser().catch(() => {});
+    await agent.settled?.().catch(() => {});
+  }
+
+  const ok = !error && !agent.endedSilently;
+  if (json) {
+    write(`${JSON.stringify({
+      ok,
+      answer: ui.answer,
+      files: [...(agent.touched ?? [])],
+      steps: agent.stats.steps,
+      requests: requestCount() - sent,
+      ms: Date.now() - started,
+      error: error ? (error.failed ?? error.message ?? String(error)) : null,
+    })}\n`);
+  } else if (ui.answer) {
+    write(`${ui.answer}\n`);
+  }
+  return ok ? 0 : 1;
+}