ucode-agent 1.64.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:
@@ -372,6 +389,7 @@ Everything after the frontmatter is the instruction.
 | `/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` |
@@ -399,6 +417,32 @@ 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
@@ -448,7 +492,7 @@ ucode -p "make a quiz app" --json --yes    one JSON line: ok, answer, files, ste
 
 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 100 free requests).
+a release (it spends about 30 free requests, and takes about seven minutes).
 
 ### Other models
 
@@ -499,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 |
@@ -529,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,6 +1,6 @@
 {
   "name": "ucode-agent",
-  "version": "1.64.0",
+  "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",

package/src/core/loop.js

@@ -67,6 +67,8 @@ import { Snapshots } from './snapshot.js';
 import { loadSettings, addAllow, isTrusted, trust, runHook } from './settings.js';
 import { McpHub, readServers, USER_MCP, projectMcpFile } from './mcp.js';
 import { loadCommands, expandCommand } from './commands.js';
+import { SPINNERS, saveLook, look, normaliseColour } from '../ui/theme.js';
+import { customizeTerminal, resetTerminal, detectTerminal, TERMINAL_NAMES } from './terminal.js';
 
 /**
  * Tool calls allowed in one turn.
@@ -569,6 +571,53 @@ export class Writing {
 /** Tools that only mean anything once there is code in the folder. */
 const LOOKUP_TOOLS = new Set(['find_symbol', 'outline', 'rename_symbol', 'type_of']);
 
+/**
+ * A request about ucode's own look, or the terminal's - not an app's. Only
+ * then do the two tools below go out: "make it purple" about an app must not
+ * repaint ucode instead.
+ */
+const WANTS_LOOK = /\b(?:ucode|terminal|yourself|your (?:own )?(?:colou?rs?|look|theme|style|banner|spinner|font|byline)|this (?:terminal|window))\b/i;
+
+const lookTool = {
+  name: 'change_look',
+  description:
+    'Change how ucode itself looks in the terminal - only when the user asks about ucode, not about an app. ' +
+    'Sets the accent colour (borders, wordmark, chips; a lighter and a deeper step are worked out from it), ' +
+    'the spinner, and the line under the logo. Saved, so it stays after a restart. reset: true goes back to ucode\'s own blue.',
+  parameters: {
+    type: 'object',
+    properties: {
+      accent: { type: 'string', description: 'A hex colour like "#ff8c2b", or a name like "orange", "teal", "pink".' },
+      light: { type: 'string', description: 'Optional: the lighter step (labels, the top of the wordmark).' },
+      deep: { type: 'string', description: 'Optional: the deeper step (the bottom of the wordmark).' },
+      spinner: { type: 'string', enum: Object.keys(SPINNERS), description: 'The spinner shape.' },
+      byline: { type: 'string', description: 'The short line beside the logo, up to 40 characters.' },
+      reset: { type: 'boolean', description: 'Go back to the default look.' },
+    },
+  },
+};
+
+const terminalTool = {
+  name: 'change_terminal',
+  description:
+    'Change the terminal window ucode is running in - its background, text colour, cursor, font, font size, or ' +
+    'see-through opacity - only when the user asks about their terminal. Windows Terminal keeps the change; ' +
+    'Terminal.app changes this window; other terminals change colours for this session. The user approves it ' +
+    'first. reset: true puts the terminal back.',
+  parameters: {
+    type: 'object',
+    properties: {
+      background: { type: 'string', description: 'Hex like "#1e1e2e" or a name like "navy".' },
+      foreground: { type: 'string', description: 'The text colour.' },
+      cursor: { type: 'string', description: 'The cursor colour.' },
+      font: { type: 'string', description: 'A font installed on this computer, e.g. "Cascadia Code" or "Menlo".' },
+      font_size: { type: 'integer', description: 'Font size, 6 to 48.' },
+      opacity: { type: 'integer', description: 'How solid the window is, 20 to 100 (Windows Terminal only).' },
+      reset: { type: 'boolean', description: 'Put the terminal back as it was.' },
+    },
+  },
+};
+
 /** A request that plainly wants the internet keeps web_search in a new project. */
 const WANTS_WEB = /\b(?:search|google|web|online|internet|latest|current|news|docs|documentation|api reference|look up|find out about)\b/i;
 
@@ -1394,6 +1443,13 @@ export class Agent {
     this.fresh = !hasCode(this.map);
     request.content = withScope(input, { hasCode: !this.fresh }) + added.text;
     this.wantsWeb = WANTS_WEB.test(input);
+    this.wantsLook = WANTS_LOOK.test(input) || this.lookTurn === true;
+    // Offering the tools was not enough: Flash-Lite said "Changing the look"
+    // and stopped. Said on the request itself, it calls them.
+    if (this.wantsLook) {
+      request.content += '\n\n(From ucode: to change how ucode itself looks, call change_look; to change the ' +
+        'terminal window, call change_terminal. Call them now - do not just say you will - then say in one line what changed.)';
+    }
     await this.persist();
 
     // A busy model was swapped for a fallback earlier; after a few minutes the
@@ -1463,13 +1519,13 @@ export class Agent {
    * wrong turns available to a model deciding what to do next.
    */
   toolsNow() {
-    const all = [...tools, loadSkillTool, planTool, delegateTool];
+    const all = [...tools, loadSkillTool, planTool, delegateTool, ...(this.wantsLook ? [lookTool, terminalTool] : [])];
     const live = this.fresh
       ? all.filter((t) => !LOOKUP_TOOLS.has(t.name) && !(t.name === 'web_search' && !this.wantsWeb))
       : all;
     // MCP tools can do anything their server does, so a read-only turn gets none.
     if (this.ui.mode !== 'plan' && !this.readOnly) return [...live, ...(this.mcp?.tools() ?? [])];
-    return live.filter((t) => !WRITES.has(t.name));
+    return live.filter((t) => !WRITES.has(t.name) && t !== lookTool && t !== terminalTool);
   }
 
   /**
@@ -2447,6 +2503,8 @@ export class Agent {
     if (call.name === 'load_skill') return this.loadSkill(call.args?.name);
     if (call.name === 'update_plan') return this.updatePlan(call.args?.items);
     if (call.name === 'delegate') return this.delegate(call.args?.tasks);
+    if (call.name === 'change_look') return this.changeLook(call.args ?? {});
+    if (call.name === 'change_terminal') return this.changeTerminal(call.args ?? {});
     if (this.mcp?.has(call.name)) return this.callMcp(call);
 
     // The snapshot /undo goes back to has to be on disk before anything changes.
@@ -2465,6 +2523,57 @@ export class Agent {
     return out;
   }
 
+  /** change_look: ucode's own colours, spinner and byline, saved and shown at once. */
+  changeLook(args) {
+    const changes = {};
+    for (const key of ['accent', 'light', 'deep', 'spinner', 'byline']) {
+      if (args[key] !== undefined) changes[key] = args[key];
+    }
+    if (!args.reset && !Object.keys(changes).length) {
+      throw new ToolFailure({
+        kind: 'bad_args', attempted: 'changing how ucode looks',
+        failed: 'Nothing to change was given.', fix: 'Pass accent, spinner or byline - or reset: true.',
+      });
+    }
+    for (const key of ['accent', 'light', 'deep']) {
+      if (changes[key] && !normaliseColour(changes[key])) {
+        throw new ToolFailure({
+          kind: 'bad_args', attempted: 'changing ucode\'s colour',
+          failed: `"${changes[key]}" is not a colour ucode can read.`, fix: 'Use a hex like "#ff8c2b" or a name like "orange".',
+        });
+      }
+    }
+    const now = saveLook(changes, { reset: Boolean(args.reset) });
+    this.showHeader({ clear: false });
+    this.ui.render?.();
+    return {
+      content: `ucode now looks like this: accent ${now.accent}, spinner ${now.spinner}, byline "${now.byline}". It is saved and already on screen.`,
+      summary: `accent ${now.accent} · ${now.spinner}`,
+    };
+  }
+
+  /** change_terminal: the terminal window itself, after the user says yes. */
+  async changeTerminal(args) {
+    const name = TERMINAL_NAMES[detectTerminal()];
+    if (args.reset) {
+      await confirm(`put ${name} back the way it was`, 'Undoes the changes ucode made to it.', 'write');
+      const done = await resetTerminal();
+      return { content: done.message, summary: done.ok ? 'terminal reset' : 'nothing to reset' };
+    }
+    const wanted = Object.entries(args).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => `${k} ${v}`);
+    await confirm(`change ${name}: ${wanted.join(', ')}`, 'ucode keeps a backup; "/theme terminal reset" puts it back.', 'write');
+    let done;
+    try {
+      done = await customizeTerminal(args);
+    } catch (err) {
+      throw new ToolFailure({ kind: 'bad_args', attempted: `changing ${name}`, failed: err.message, fix: 'Correct the values and try again.' });
+    }
+    if (!done.ok) {
+      throw new ToolFailure({ kind: 'not_supported', attempted: `changing ${name}`, failed: done.message, fix: 'Tell the user what this terminal allows instead.' });
+    }
+    return { content: done.message, summary: 'terminal changed' };
+  }
+
   /** A tool from an MCP server: asked about first, unless always allowed. */
   async callMcp(call) {
     const subject = `mcp:${call.name}`;
@@ -3311,6 +3420,7 @@ export class Agent {
       case '/review':   return this.cmdReview();
       case '/mcp':      return this.cmdMcp();
       case '/permissions': return this.cmdPermissions(arg);
+      case '/theme':    return this.cmdTheme(arg);
       case '/mic':
         if (this.ui.onMic) return this.mic('toggle');
         return this.ui.note('the mic works in the full-screen view — start ucode in a terminal window');
@@ -3426,6 +3536,51 @@ export class Agent {
     this.ui.blank();
   }
 
+  /**
+   * /theme                   how ucode looks now, and what can change
+   * /theme reset             ucode's own blue again
+   * /theme terminal reset    the terminal back as it was
+   * /theme orange | #ff8c2b  a new accent, at once
+   * /theme <anything else>   asked for in words: "/theme make the terminal navy with a bigger font"
+   */
+  async cmdTheme(arg) {
+    const said = arg.trim();
+    if (!said) {
+      this.ui.blank();
+      this.ui.write(`  ${blue('accent')}   ${look.accent}   ${dim('light')} ${look.light}   ${dim('deep')} ${look.deep}`);
+      this.ui.write(`  ${blue('spinner')}  ${look.spinner}  ${dim(`(${Object.keys(SPINNERS).join(', ')})`)}`);
+      this.ui.write(`  ${blue('byline')}   ${look.byline}`);
+      this.ui.write(`  ${blue('terminal')} ${TERMINAL_NAMES[detectTerminal()]}`);
+      this.ui.blank();
+      this.ui.write(dim('  /theme orange · /theme reset · /theme terminal reset · or just ask: "make ucode green and my terminal navy"'));
+      this.ui.blank();
+      return;
+    }
+    if (/^reset$/i.test(said)) {
+      saveLook({}, { reset: true });
+      this.showHeader({ clear: false });
+      this.ui.note('ucode is back to its own blue');
+      return;
+    }
+    if (/^terminal\s+reset$/i.test(said)) {
+      const done = await resetTerminal();
+      this.ui.note(done.message);
+      return;
+    }
+    if (/^\S+$/.test(said) && normaliseColour(said)) {
+      saveLook({ accent: said });
+      this.showHeader({ clear: false });
+      this.ui.note(`ucode is ${look.accent} now — saved for next time too`);
+      return;
+    }
+    this.lookTurn = true;
+    try {
+      await this.turn(`Change how ucode or this terminal looks: ${said}`);
+    } finally {
+      this.lookTurn = false;
+    }
+  }
+
   /** /permissions [ask|auto]: whether commands are asked about, and what is always allowed. */
   async cmdPermissions(arg) {
     const want = arg.trim().toLowerCase();
@@ -3518,6 +3673,7 @@ ${out.content}` });
       ['/init', `read the project and write ${MEMORY_FILE} for it`],
       ['/mcp', 'connected MCP servers and their tools'],
       ['/permissions', 'ask before commands, or run them; what is always allowed'],
+      ['/theme [what]', 'change how ucode or your terminal looks — or just ask in words'],
       ['/stats', 'time, steps and tokens this session'],
       ['/doctor', 'check that everything ucode needs is working'],
       ['/look [url]', 'open the running app and report what is on the page'],

package/src/core/terminal.js

@@ -0,0 +1,232 @@
+/**
+ * terminal.js — changing the terminal ucode runs in, when the user asks:
+ * "make my terminal dark green", "bigger font", "a bit see-through".
+ *
+ * Each terminal keeps its look somewhere different, so each gets its own way:
+ *
+ *   Windows Terminal  its settings.json, which it reloads the moment it is saved.
+ *                     Kept: every new tab looks the same. The file as it was is
+ *                     backed up first, and `reset` puts it back.
+ *   Terminal.app      AppleScript on the window ucode is in: colours, cursor,
+ *                     font and size. That window only; the old values are kept
+ *                     so `reset` can restore them.
+ *   iTerm2            its escape sequence for colours, this session only.
+ *   anything else     the standard xterm escapes for colours, this session only.
+ *
+ * Nothing here runs unless the user asked, and the loop asks before it does.
+ */
+
+import { execFile } from 'node:child_process';
+import { promises as fs, existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { jsonrepair } from 'jsonrepair';
+import { normaliseColour, hexRGB } from '../ui/theme.js';
+
+export const BACKUP_DIR = path.join(os.homedir(), '.ucode', 'terminal-backup');
+const backups = () => process.env.UCODE_TERMINAL_BACKUP || BACKUP_DIR;
+
+/** Which terminal this is, from what it puts in the environment. */
+export function detectTerminal(env = process.env, platform = process.platform) {
+  if (env.WT_SESSION) return 'windows-terminal';
+  if (env.TERM_PROGRAM === 'Apple_Terminal') return 'apple-terminal';
+  if (env.TERM_PROGRAM === 'iTerm.app' || env.LC_TERMINAL === 'iTerm2') return 'iterm';
+  if (env.TERM_PROGRAM === 'vscode') return 'vscode';
+  if (platform === 'win32') return 'windows-console';
+  return 'other';
+}
+
+export const TERMINAL_NAMES = {
+  'windows-terminal': 'Windows Terminal',
+  'apple-terminal': 'Terminal',
+  iterm: 'iTerm2',
+  vscode: 'the VS Code terminal',
+  'windows-console': 'the Windows console',
+  other: 'this terminal',
+};
+
+/** Where Windows Terminal keeps its settings: the Store build, Preview, or unpackaged. */
+export function windowsTerminalSettings(env = process.env) {
+  const local = env.LOCALAPPDATA ?? path.join(os.homedir(), 'AppData', 'Local');
+  const candidates = [
+    path.join(local, 'Packages', 'Microsoft.WindowsTerminal_8wekyb3d8bbwe', 'LocalState', 'settings.json'),
+    path.join(local, 'Packages', 'Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe', 'LocalState', 'settings.json'),
+    path.join(local, 'Microsoft', 'Windows Terminal', 'settings.json'),
+  ];
+  return candidates.find((f) => existsSync(f)) ?? null;
+}
+
+/** What was asked for, cleaned: colours as #rrggbb, a sane size and opacity. */
+export function cleanRequest(req = {}) {
+  const out = {};
+  for (const key of ['background', 'foreground', 'cursor']) {
+    if (req[key] === undefined || req[key] === null || req[key] === '') continue;
+    const colour = normaliseColour(req[key]);
+    if (!colour) throw new Error(`"${req[key]}" is not a colour ucode can read — use a name like "navy" or a hex like #1e1e2e`);
+    out[key] = colour;
+  }
+  if (req.font_size !== undefined && req.font_size !== null && req.font_size !== '') {
+    const size = Number(req.font_size);
+    if (!Number.isFinite(size) || size < 6 || size > 48) throw new Error('font_size should be a number from 6 to 48');
+    out.font_size = Math.round(size);
+  }
+  if (req.font) out.font = String(req.font).replace(/["\\\r\n]/g, '').slice(0, 60);
+  if (req.opacity !== undefined && req.opacity !== null && req.opacity !== '') {
+    const opacity = Number(req.opacity);
+    if (!Number.isFinite(opacity) || opacity < 20 || opacity > 100) throw new Error('opacity should be a number from 20 to 100');
+    out.opacity = Math.round(opacity);
+  }
+  return out;
+}
+
+/** Windows Terminal: set the look on the defaults, and on any profile that overrides it. */
+export function applyToWindowsTerminal(settings, want) {
+  const next = structuredClone(settings);
+  if (Array.isArray(next.profiles)) next.profiles = { defaults: {}, list: next.profiles };
+  next.profiles ??= {};
+  next.profiles.defaults ??= {};
+  const set = (profile) => {
+    if (want.background) profile.background = want.background;
+    if (want.foreground) profile.foreground = want.foreground;
+    if (want.cursor) profile.cursorColor = want.cursor;
+    if (want.font || want.font_size) {
+      profile.font = { ...(profile.font ?? {}), ...(want.font ? { face: want.font } : {}), ...(want.font_size ? { size: want.font_size } : {}) };
+    }
+    if (want.opacity !== undefined) {
+      profile.opacity = want.opacity;
+      profile.useAcrylic = want.opacity < 100;
+    }
+  };
+  set(next.profiles.defaults);
+  // A profile with its own value would hide the default, so it changes too.
+  const keys = ['background', 'foreground', 'cursorColor', 'font', 'opacity'];
+  for (const profile of next.profiles.list ?? []) {
+    if (keys.some((k) => profile[k] !== undefined)) set(profile);
+  }
+  return next;
+}
+
+const run = (file, args) => new Promise((resolve) => {
+  execFile(file, args, { windowsHide: true, timeout: 15_000 }, (err, stdout, stderr) =>
+    resolve({ ok: !err, out: String(stdout ?? '').trim(), err: String(stderr || err?.message || '').trim() }));
+});
+
+/** AppleScript's colours run 0-65535. */
+const appleColour = (hex) => `{${hexRGB(hex).map((v) => v * 257).join(', ')}}`;
+const TAB = 'selected tab of front window';
+
+async function appleTerminal(want) {
+  const backup = path.join(backups(), 'apple-terminal.json');
+  if (!existsSync(backup)) {
+    const get = await run('osascript', ['-e', `tell application "Terminal" to get {background color, normal text color, cursor color, font name, font size} of ${TAB}`]);
+    if (get.ok) {
+      await fs.mkdir(backups(), { recursive: true });
+      await fs.writeFile(backup, JSON.stringify({ raw: get.out }));
+    }
+  }
+  const lines = [];
+  if (want.background) lines.push(`set background color of ${TAB} to ${appleColour(want.background)}`);
+  if (want.foreground) lines.push(`set normal text color of ${TAB} to ${appleColour(want.foreground)}`);
+  if (want.cursor) lines.push(`set cursor color of ${TAB} to ${appleColour(want.cursor)}`);
+  if (want.font) lines.push(`set font name of ${TAB} to "${want.font}"`);
+  if (want.font_size) lines.push(`set font size of ${TAB} to ${want.font_size}`);
+  if (!lines.length) return { ok: false, message: 'Terminal can change colours, the cursor, the font and its size here — not the opacity.' };
+  const script = ['tell application "Terminal"', ...lines.map((l) => `  ${l}`), 'end tell'].join('\n');
+  const done = await run('osascript', ['-e', script]);
+  return done.ok
+    ? { ok: true, message: `Changed this Terminal window${want.opacity !== undefined ? ' (opacity is not something Terminal lets ucode set)' : ''}.` }
+    : { ok: false, message: `Terminal refused: ${done.err}. macOS may need ucode's terminal allowed under Privacy & Security > Automation.` };
+}
+
+/** The escape sequences for colours: iTerm2's own, or the xterm ones nearly everything reads. */
+export function colourEscapes(kind, want) {
+  const hex = (h) => h.slice(1);
+  if (kind === 'iterm') {
+    return [
+      want.background && `\x1b]1337;SetColors=bg=${hex(want.background)}\x07`,
+      want.foreground && `\x1b]1337;SetColors=fg=${hex(want.foreground)}\x07`,
+      want.cursor && `\x1b]1337;SetColors=curbg=${hex(want.cursor)}\x07`,
+    ].filter(Boolean).join('');
+  }
+  return [
+    want.foreground && `\x1b]10;${want.foreground}\x07`,
+    want.background && `\x1b]11;${want.background}\x07`,
+    want.cursor && `\x1b]12;${want.cursor}\x07`,
+  ].filter(Boolean).join('');
+}
+
+/**
+ * Change the terminal. Resolves to { ok, message } and never throws on a
+ * terminal that cannot do it; throws only on a request that makes no sense.
+ */
+export async function customizeTerminal(request, { env = process.env, platform = process.platform, write = (s) => process.stdout.write(s) } = {}) {
+  const want = cleanRequest(request);
+  if (!Object.keys(want).length) throw new Error('Say what to change: background, foreground, cursor, font, font_size or opacity.');
+  const kind = detectTerminal(env, platform);
+
+  if (kind === 'windows-terminal') {
+    const file = windowsTerminalSettings(env);
+    if (!file) return { ok: false, message: 'Could not find Windows Terminal\'s settings.json.' };
+    const text = await fs.readFile(file, 'utf8');
+    if (!text.trim()) return { ok: false, message: 'Windows Terminal\'s settings.json is empty, so it was left alone.' };
+    let settings;
+    try {
+      settings = JSON.parse(jsonrepair(text.replace(/^/, '')));
+    } catch {
+      return { ok: false, message: 'Windows Terminal\'s settings.json could not be read, so it was left alone.' };
+    }
+    await fs.mkdir(backups(), { recursive: true });
+    const backup = path.join(backups(), 'windows-terminal.json');
+    if (!existsSync(backup)) await fs.writeFile(backup, JSON.stringify({ file, text }));
+    await fs.writeFile(file, `${JSON.stringify(applyToWindowsTerminal(settings, want), null, 4)}\n`);
+    return { ok: true, message: 'Changed Windows Terminal — every tab, and it stays. "/theme terminal reset" puts it back.' };
+  }
+
+  if (kind === 'apple-terminal') return appleTerminal(want);
+
+  if (kind === 'windows-console') {
+    return { ok: false, message: 'The old Windows console cannot be changed from here. Windows Terminal (free in the Microsoft Store) can.' };
+  }
+
+  const escapes = colourEscapes(kind, want);
+  if (!escapes) return { ok: false, message: `${TERMINAL_NAMES[kind]} only lets ucode change its colours, not the font or opacity.` };
+  write(escapes);
+  const skipped = want.font || want.font_size || want.opacity !== undefined ? ' The font and opacity are not something it lets ucode set.' : '';
+  return { ok: true, message: `Changed ${TERMINAL_NAMES[kind]}'s colours for this session.${skipped}` };
+}
+
+/** Put the terminal back as it was before ucode changed it. */
+export async function resetTerminal({ env = process.env, platform = process.platform, write = (s) => process.stdout.write(s) } = {}) {
+  const kind = detectTerminal(env, platform);
+  if (kind === 'windows-terminal') {
+    const backup = path.join(backups(), 'windows-terminal.json');
+    if (!existsSync(backup)) return { ok: false, message: 'ucode has not changed Windows Terminal, so there is nothing to put back.' };
+    const { file, text } = JSON.parse(await fs.readFile(backup, 'utf8'));
+    await fs.writeFile(file, text);
+    await fs.rm(backup, { force: true });
+    return { ok: true, message: 'Windows Terminal is back the way it was.' };
+  }
+  if (kind === 'apple-terminal') {
+    const backup = path.join(backups(), 'apple-terminal.json');
+    if (!existsSync(backup)) return { ok: false, message: 'ucode has not changed this Terminal window.' };
+    const { raw } = JSON.parse(await fs.readFile(backup, 'utf8'));
+    const n = raw.split(/,\s*/);
+    // {r,g,b} three times, then the font name and size.
+    if (n.length >= 11) {
+      const colour = (i) => `{${n.slice(i, i + 3).join(', ')}}`;
+      await run('osascript', ['-e', [
+        'tell application "Terminal"',
+        `  set background color of ${TAB} to ${colour(0)}`,
+        `  set normal text color of ${TAB} to ${colour(3)}`,
+        `  set cursor color of ${TAB} to ${colour(6)}`,
+        `  set font name of ${TAB} to "${n[9].replace(/"/g, '')}"`,
+        `  set font size of ${TAB} to ${Number(n[10]) || 12}`,
+        'end tell',
+      ].join('\n')]);
+    }
+    await fs.rm(backup, { force: true });
+    return { ok: true, message: 'This Terminal window is back the way it was.' };
+  }
+  write(kind === 'iterm' ? '\x1b]1337;SetColors=preset=Default\x07' : '\x1b]110\x07\x1b]111\x07\x1b]112\x07');
+  return { ok: true, message: 'The terminal\'s own colours are back.' };
+}

package/src/tools/index.js

@@ -722,6 +722,10 @@ export function describe(name, args = {}) {
       return `Searching the web for ${clip(args.query, 60)}`;
     case 'load_skill':
       return `Loading the ${clip(args.name, 40)} skill`;
+    case 'change_look':
+      return args.reset ? 'Putting ucode\'s look back' : 'Changing how ucode looks';
+    case 'change_terminal':
+      return args.reset ? 'Putting the terminal back' : 'Changing the terminal';
     default:
       return `${name} ${clip(JSON.stringify(args), 60)}`;
   }

package/src/ui/activity.js

@@ -12,7 +12,7 @@
  */
 
 import chalk, { Chalk } from 'chalk';
-import { dim, sky, theme, clip, SPINNER, bannerRGB, bannerPaint } from './theme.js';
+import { dim, sky, theme, clip, SPINNER, bannerRGB, bannerPaint, look, hexRGB } from './theme.js';
 
 /** One painter per colour level, so a test can ask for truecolour on a pipe. */
 const painters = new Map();
@@ -289,7 +289,7 @@ export function spinnerGlyph(frame, t, { level = chalk.level } = {}) {
   const glyph = SPINNER[((frame % SPINNER.length) + SPINNER.length) % SPINNER.length];
   if (level < 2) return theme.blue(glyph);
   const k = (Math.sin((Math.max(0, t) / 1000) * Math.PI * 2) + 1) / 2;
-  const [r, g, b] = mix([0x2f, 0x6f, 0xe0], [0x9f, 0xc6, 0xff], k);
+  const [r, g, b] = mix(hexRGB(look.deep), hexRGB(look.light), k);
   return painter(level).rgb(r, g, b)(glyph);
 }
 

package/src/ui/plain.js

@@ -14,7 +14,7 @@ import chalk from 'chalk';
 import {
   theme, blue, sky, dim, boxTop, boxBottom, boxRow,
   BANNER, BANNER_WIDTH, SPINNER, clip, shortenPath, asLabel, padVis, visLen, planLine, bannerPaint, modeChip, narrationMark, groupKind,
-  tidyReply, trimAnswer,
+  tidyReply, trimAnswer, look,
 } from './theme.js';
 import { formatDuration, doneLine } from './activity.js';
 import { renderer, render } from './markdown.js';
@@ -101,7 +101,7 @@ export class Plain {
       ['keys', '/help'],
       ['', ''],
       ['', ''],
-      ['', 'made with ❤ by om dixit'],
+      ['', look.byline],
     ];
 
     // There is no input box to hang the status off here, so it goes on the

package/src/ui/screen.js

@@ -37,7 +37,7 @@ import { homedir } from 'node:os';
 import path from 'node:path';
 import chalk from 'chalk';
 import {
-  theme, blue, sky, deep, dim, edge, ADDED, REMOVED, BANNER, BANNER_WIDTH, SPINNER,
+  theme, blue, sky, deep, dim, edge, ADDED, REMOVED, BANNER, BANNER_WIDTH, SPINNER, look,
   boxTop, boxBottom, boxRow, visLen, padVis, clip, wrapAnsi,
   shortenPath, asLabel, ensureColour, planLine, bare, narration, narrationMark, groupKind, groupLabel, groupTarget, runLine, planRows, tidyReply, trimAnswer,
   bannerPaint, RAIL, modeChip, ADD_CHIP, micChip, asNarrationLine } from './theme.js';
@@ -819,7 +819,7 @@ export class Screen {
     ].filter(Boolean).slice(0, BANNER.length - 1);
 
     while (facts.length < BANNER.length - 1) facts.push(['', '']);
-    facts.push(['', 'made with ❤ by om dixit']);
+    facts.push(['', look.byline]);
 
     const rows = BANNER.map((art, i) => {
       const [label, text] = facts[i] ?? ['', ''];

package/src/ui/theme.js

@@ -9,12 +9,17 @@
  */
 
 import chalk from 'chalk';
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 
 // One hue, three weights. Anything that needs a fourth is asking for emphasis
-// it has not earned.
-export const blue = chalk.hex('#4d8dff');   // structure: borders, the caret, the wordmark
-export const sky = chalk.hex('#8fbcff');    // secondary: labels that still matter
-export const deep = chalk.hex('#2f6fe0');   // pressed, quiet, behind
+// it has not earned. The hue is the user's to change ("make ucode orange"):
+// these are `let`, so every module that imported them sees a new look the
+// moment applyLook() runs - see the "Your look" section below.
+export let blue = chalk.hex('#4d8dff');   // structure: borders, the caret, the wordmark
+export let sky = chalk.hex('#8fbcff');    // secondary: labels that still matter
+export let deep = chalk.hex('#2f6fe0');   // pressed, quiet, behind
 export const dim = chalk.dim;
 
 /**
@@ -25,7 +30,7 @@ export const dim = chalk.dim;
  * terminal fonts visibly thicker, which is enough to separate "where you type"
  * from "what you are reading" without a second colour.
  */
-export const edge = chalk.hex('#4d8dff').bold;
+export let edge = chalk.hex('#4d8dff').bold;
 
 /**
  * The colour level to use for a stream, or null to leave chalk's guess alone.
@@ -87,8 +92,8 @@ export const BANNER_WIDTH = Math.max(...BANNER.map((r) => r.length));
  * the page. chalk downshifts the hex to whatever the terminal actually has, so
  * on a 16-colour terminal this is flat blue again rather than nothing.
  */
-const GRADIENT_TOP = [0x8f, 0xbc, 0xff];      // sky, at the crown
-const GRADIENT_BOTTOM = [0x2f, 0x6f, 0xe0];   // deep, in the shadow
+let GRADIENT_TOP = [0x8f, 0xbc, 0xff];      // sky, at the crown
+let GRADIENT_BOTTOM = [0x2f, 0x6f, 0xe0];   // deep, in the shadow
 
 export function bannerRGB(row, rows = BANNER.length) {
   const t = rows > 1 ? Math.min(1, Math.max(0, row / (rows - 1))) : 0;
@@ -121,14 +126,14 @@ export const RAIL = '▌';
  * once: it is the width of the word, the way a diff's tint is the width of the
  * line it marks.
  */
-export const BUILD_CHIP = chalk.bgHex('#4d8dff').hex('#0b1220').bold;
-export const PLAN_CHIP = chalk.bgHex('#24344f').hex('#8fbcff').bold;
+export let BUILD_CHIP = chalk.bgHex('#4d8dff').hex('#0b1220').bold;
+export let PLAN_CHIP = chalk.bgHex('#24344f').hex('#8fbcff').bold;
 
 export const modeChip = (mode) =>
   mode === 'plan' ? PLAN_CHIP(' PLAN ') : BUILD_CHIP(' BUILD ');
 
 /** The "+ file" button beside the mode chip, in the quieter of the two chip styles. */
-export const ADD_CHIP = PLAN_CHIP(' + file ');
+export let ADD_CHIP = PLAN_CHIP(' + file ');
 
 /** The mic button beside it: quiet when idle, red while it is listening. */
 const LISTEN_CHIP = chalk.bgHex('#e5484d').hex('#ffffff').bold;
@@ -138,7 +143,7 @@ export const micChip = (state) =>
       : PLAN_CHIP(' mic ');
 
 /** The spinner. Braille dots, because they animate in place without jitter. */
-export const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export let SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 
 // ---------------------------------------------------------------------------
 // Boxes
@@ -870,3 +875,127 @@ function withinRoom(text, room = ANSWER_ROOM) {
   }
   return (out.trim() || text.slice(0, room)).trim();
 }
+
+// ---------------------------------------------------------------------------
+// Your look
+// ---------------------------------------------------------------------------
+
+/**
+ * ucode's look is the user's to change, by asking: "make yourself orange",
+ * "a calmer spinner", "put my name under the logo". It is a small file of
+ * choices rather than an edit to this one, so it survives every update and can
+ * never break ucode - a value that does not parse is simply ignored.
+ *
+ *   { "accent": "#ff8c2b", "light": "#ffb454", "deep": "#c2410c",
+ *     "spinner": "dots", "byline": "made by me" }
+ *
+ * Only accent is needed; light and deep are worked out from it.
+ */
+export const LOOK_FILE = process.env.UCODE_LOOK_FILE || path.join(os.homedir(), '.ucode', 'theme.json');
+
+export const SPINNERS = {
+  dots: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+  line: ['-', '\\', '|', '/'],
+  arc: ['◜', '◠', '◝', '◞', '◡', '◟'],
+  circle: ['◐', '◓', '◑', '◒'],
+  square: ['◰', '◳', '◲', '◱'],
+  bounce: ['⠁', '⠂', '⠄', '⠂'],
+  pulse: ['·', '•', '●', '•'],
+  star: ['✶', '✸', '✹', '✺', '✹', '✸'],
+};
+
+export const DEFAULT_LOOK = Object.freeze({
+  accent: '#4d8dff', light: '#8fbcff', deep: '#2f6fe0', spinner: 'dots', byline: 'made with ❤ by om dixit',
+});
+
+const NAMED = {
+  red: '#ef4444', orange: '#f97316', amber: '#f59e0b', gold: '#eab308', yellow: '#facc15', lime: '#84cc16',
+  green: '#22c55e', emerald: '#10b981', teal: '#14b8a6', cyan: '#06b6d4', sky: '#0ea5e9', blue: '#4d8dff',
+  indigo: '#6366f1', violet: '#8b5cf6', purple: '#a855f7', magenta: '#d946ef', pink: '#ec4899', rose: '#f43f5e',
+  white: '#f5f5f5', grey: '#9ca3af', gray: '#9ca3af', silver: '#c0c0c0', black: '#111111', brown: '#a16207',
+  coral: '#ff7f50', salmon: '#fa8072', navy: '#1e3a8a', maroon: '#9f1239', olive: '#65a30d', mint: '#6ee7b7',
+  lavender: '#c4b5fd', peach: '#fdba74', crimson: '#dc143c', turquoise: '#40e0d0',
+};
+
+/** '#abc', '#aabbcc', 'rgb(1,2,3)' or a colour name, as '#rrggbb' - or null. */
+export function normaliseColour(value) {
+  const v = String(value ?? '').trim().toLowerCase();
+  if (NAMED[v]) return NAMED[v];
+  const short = /^#?([0-9a-f])([0-9a-f])([0-9a-f])$/.exec(v);
+  if (short) return `#${short[1]}${short[1]}${short[2]}${short[2]}${short[3]}${short[3]}`;
+  const long = /^#?([0-9a-f]{6})$/.exec(v);
+  if (long) return `#${long[1]}`;
+  const rgb = /^rgb\(\s*(\d{1,3})[\s,]+(\d{1,3})[\s,]+(\d{1,3})\s*\)$/.exec(v);
+  if (rgb && rgb.slice(1).every((n) => Number(n) <= 255)) {
+    return `#${rgb.slice(1).map((n) => Number(n).toString(16).padStart(2, '0')).join('')}`;
+  }
+  return null;
+}
+
+export const hexRGB = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
+const rgbHex = (rgb) => `#${rgb.map((v) => Math.round(v).toString(16).padStart(2, '0')).join('')}`;
+
+/** Part of the way from one colour to another: t = 0 is a, 1 is b. */
+export const mixHex = (a, b, t) => rgbHex(hexRGB(a).map((v, i) => v + (hexRGB(b)[i] - v) * t));
+
+/** The look in the file, or nothing. Never throws. */
+export function readLook(file = LOOK_FILE) {
+  try {
+    const data = JSON.parse(readFileSync(file, 'utf8'));
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The current look, filled out: what applyLook settled on. */
+export let look = { ...DEFAULT_LOOK };
+
+/** Put a look on screen. Missing or broken values fall back to the default. */
+export function applyLook(wanted = {}) {
+  const accent = normaliseColour(wanted.accent) ?? DEFAULT_LOOK.accent;
+  const own = accent !== DEFAULT_LOOK.accent;
+  const light = normaliseColour(wanted.light) ?? (own ? mixHex(accent, '#ffffff', 0.45) : DEFAULT_LOOK.light);
+  const deepHex = normaliseColour(wanted.deep) ?? (own ? mixHex(accent, '#000000', 0.25) : DEFAULT_LOOK.deep);
+  const spinner = SPINNERS[wanted.spinner] ? wanted.spinner : DEFAULT_LOOK.spinner;
+  const byline = typeof wanted.byline === 'string' ? wanted.byline.replace(/[\x00-\x1f]/g, '').slice(0, 40) : DEFAULT_LOOK.byline;
+
+  look = { accent, light, deep: deepHex, spinner, byline };
+  blue = chalk.hex(accent);
+  sky = chalk.hex(light);
+  deep = chalk.hex(deepHex);
+  edge = chalk.hex(accent).bold;
+  theme.blue = blue;
+  theme.sky = sky;
+  theme.deep = deep;
+  GRADIENT_TOP = hexRGB(light);
+  GRADIENT_BOTTOM = hexRGB(deepHex);
+  BUILD_CHIP = chalk.bgHex(accent).hex('#0b1220').bold;
+  PLAN_CHIP = chalk.bgHex(mixHex(deepHex, '#0b1220', 0.65)).hex(light).bold;
+  ADD_CHIP = PLAN_CHIP(' + file ');
+  SPINNER = SPINNERS[spinner];
+  return look;
+}
+
+/**
+ * Change the look and keep it: `changes` are merged into what is saved, a key
+ * set to null goes back to its default, and { reset: true } starts over.
+ */
+export function saveLook(changes = {}, { reset = false, file = LOOK_FILE } = {}) {
+  const merged = reset ? {} : { ...readLook(file) };
+  for (const [key, value] of Object.entries(changes)) {
+    if (!(key in DEFAULT_LOOK)) continue;
+    if (value === null || value === '') delete merged[key];
+    else merged[key] = value;
+  }
+  // An accent alone gets its own light and dark steps, not the old ones.
+  if ('accent' in changes && !('light' in changes)) delete merged.light;
+  if ('accent' in changes && !('deep' in changes)) delete merged.deep;
+  mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(merged, null, 2)}\n`);
+  renameSync(temp, file);
+  return applyLook(merged);
+}
+
+applyLook(readLook());