Customize Omniscio

What it is

Omniscio already lets you pick a theme, which recolours a fixed list of colours. Custom CSS is the open-ended version: one stylesheet of your own that can change nearly any look of any screen — colours, spacing, rounded corners, fonts, even hiding a part you never use. It is applied after the app's own styling, so it wins, and it shows up the moment you save.

Three ideas run through this guide:

• One stylesheet. Everything lives in a single file called custom.css. The Settings editor, your own text editor and your AI agent all change that same file, so they can never disagree about what is applied.
• Name tags. Every visible part of the app carries a stable name tag you can aim at, so you never have to guess how the screen is built.
• Colour variables. The same colour and shape variables a theme sets are available to your stylesheet — one line can restyle the whole app.

Your agent is a full author, not a guest. It can read and write the stylesheet, the Settings card shows who last changed it and when, and Undo brings back the version from before the last save. A change made by an agent applies at once with no approval prompt — Undo and the off switches below are the safety net, not a confirmation dialog.

Two limits to know up front. Custom CSS can never load anything from the internet: web images, web fonts and imported stylesheets are removed, and the card tells you how many. And the stylesheet is capped at 512 KB: saving a bigger one is refused, and the end of a bigger hand-edited file is ignored, with a warning.

Where to find it

• Settings → Appearance → Custom CSS. A text box for your CSS, plus Save & Apply, Undo (greyed out until there is a previous version), Edit the file (opens the stylesheet in your own editor, creating an empty one the first time) and an On / Off switch. A status line underneath says whether custom CSS is Live or why it is off, who last changed it ("You", "The command line", or the name of the agent session) and how long ago, and it lists any warning.
• The file itself. styles/custom.css inside the Omniscio data folder. Edit it in any editor and save; the change appears within about a third of a second, with no button to press.
• The shortcut. Ctrl+Alt+Shift+C turns custom CSS off, and on again. A short message tells you which one happened. Like other shortcuts, it can be changed in Settings → Keybindings.
• Your agent. Everything above can be done by an agent through Omniscio's local control interface — see For agents below.

How it behaves

Edit it yourself

Open the card, type or paste CSS and press Save & Apply. The change appears in every open window straight away; nothing restarts. To step back, press Undo: it restores whatever your last save replaced, and Undo is itself undoable. Undo remembers one step, so save often while you experiment.

Ask your agent

Describe what you want in plain words — "make the sidebar dark blue", "make the session rows roomier", "hide the breadcrumb at the top" — and the agent finds the right name tag or variable, writes the CSS and checks the result. The status line names the session that made the change, so "why did my screen change?" always has an answer. If you don't like it, say "undo that", or press Undo yourself.

What you can aim at

Name tags. Aim at one part of the screen with a selector of this shape:

[data-ui-anchor="session-input"] {
  border-radius: 14px;
}

That rounds off the message box at the bottom of a session. Names read like what they are — sidebar-projects-list (the left sidebar), session-input (the message box), view-breadcrumb (the location trail in the title bar), settings-appearance-custom-css-card (this very card) — and they are meant to stay the same from release to release, though a part of the app that gets redesigned can change its tags. There are thousands of them. You rarely need to know them: ask your agent to find the right one — it can search the full list by a word such as "sidebar", and see which tags are on screen right now. A tag only matches while that part of the app is actually showing. Ordinary selectors work too; name tags are just the steadiest way to say "this part".

Colour variables. The app paints itself from named values called CSS variables — the same ones a theme changes. Set one on :root and it changes everywhere; set it on a name tag and it changes only that region and what is inside it. Two things trip people up:

• Many colours are three numbers, not a colour name: red, green and blue separated by spaces, such as 99 102 241. The app mixes in transparency itself, so the main accent colour and every grey in the surface ramp are read in that form. Set the three-number version (--accent-rgb, --color-surface-100-rgb) and set the plain one too (--accent, --color-surface-100) so every part of the app agrees.
• A variable that seems ignored is being set more specifically by the active theme. Put !important after the value (--accent-rgb: 20 184 166 !important;) and your value wins.

The variables you will reach for most:

Variable	What it controls
--accent-rgb, --accent	The accent colour: buttons, highlights, selection.
--accent-glow	The glow drawn with the accent colour.
--panel-bg, --panel-bg-hover, --panel-bg-active	The background of panels such as the sidebar, and its hover and active states.
--panel-border	The thin line around panels.
--color-surface-50 … --color-surface-950, each with a -rgb twin	The grey ramp the app is built on: steps 50–300 are the backgrounds and panels, the high steps (800–950) are the body and heading text.
--font-family-body, --font-family-mono	The main typeface, and the code typeface.
--status-*-rgb, for example --status-needs-you-rgb, --status-error-rgb	The colours of status dots and badges, one variable per status, three numbers each.
--card-bg, --badge-bg, --badge-color, --tooltip-bg, --tooltip-border, --tooltip-fg	Cards, small badges and tooltips.

There are several dozen more. The complete list is the list of keys a theme file can set; Settings → Appearance → Theme Creation Guide shows it, and For agents below says how a key becomes a variable name.

The session row height — the one special rule

The session list on the desktop draws only the rows you can currently see, and it works out where each one goes from a fixed estimate instead of measuring it. If your CSS makes a row taller without moving that estimate, rows land in slots of the wrong size: long lists overlap and clip as you scroll, and no error appears. So never restyle a session row's height directly. Set the one variable --amc-session-row-height and both halves move together (recipe 2 below).

Use pixels (48px) — any other unit is ignored. The smallest row is 24px, and the standard row is 36px at the default text size. It applies to the desktop session list, not to the phone view. If a rule does restyle a session row's height, padding or margin, the card warns you; your CSS still applies, but long lists may misbehave.

Three copy-paste recipes

Paste one into the Custom CSS box and press Save & Apply, or tell your agent "add this to my custom CSS". Undo removes the last thing you added.

1. Recolour the sidebar

[data-ui-anchor="sidebar-projects-list"] {
  --panel-bg: #14213d;
  --panel-border: #2f4b7c;
}

The left sidebar paints its background and its edge line from those two variables, so giving the sidebar its own values recolours it — and only it — whatever theme you are on. Use any colour: a hex code like these, rgb(...), or a name such as navy.

2. Make session rows roomier

:root {
  --amc-session-row-height: 48px;
}

Every row in the desktop session list becomes 48px tall (the standard is 36px). Try 28px for a tighter list. See the special rule above for the pixels-only and 24px-minimum limits.

3. Hide one part of the screen

[data-ui-anchor="view-breadcrumb"] {
  display: none;
}

This hides the location trail at the top left of the title bar. The same pattern — display: none on a name tag — hides any part of the screen. Be careful what you hide: the toolbar at the top right (header-utilities) holds your pinned buttons, Settings among them, and the message box is session-input. If you ever hide something you need, press Ctrl+Alt+Shift+C to switch the whole stylesheet off, fix it, and switch it back on.

Getting unstuck — every way off

Because your CSS is applied last, one bad rule can make the app look wrong fast. Pick the door that fits how broken the screen is:

Door	Use it when	What it does
Ctrl+Alt+Shift+C	You can still press keys.	Turns custom CSS off at once; press it again to turn it back on.
The On / Off switch in Settings → Appearance → Custom CSS	You can still reach Settings.	The same switch, saved as a setting.
Undo	The last save was the problem.	Puts back the version before it.
Ask your agent: "turn off custom CSS"	You can still talk to your agent.	The agent switches it off with one command — it works even when the screen is unusable, as long as Omniscio is running.
Start Omniscio with --no-custom-css (or with AMC_DISABLE_CUSTOM_CSS set to 1)	The app is too broken to click anything.	Holds custom CSS off before the first screen is drawn; the card then says it was started that way.
Safe Mode	Everything is misbehaving.	Starts Omniscio with the customization layer off, along with everything automatic.

Turning custom CSS off never deletes your stylesheet — the file is left exactly as it was, so you can fix it and switch it back on. One honest limit: the shortcut and the switch need a working window. The launch option and the agent's command are the two that still work when the screen is unusable.

What the app will not let through

• Anything from the internet. @import lines are removed; image-set() is removed; every url(...) that is not a data: image, a blob: or a #fragment is replaced by an empty one. The card says how many were removed.
• Backslashes. A sheet containing a backslash anywhere — a CSS escape such as content: "\201C" — is refused whole: nothing is applied and the card says why. Write the character itself instead of an escape.
• More than 512 KB. See the limits above.

For agents

Everything the card does is available on the local control server at http://127.0.0.1:19519. Send Authorization: Bearer $AMC_CLI_TOKEN and your session id in X-AMC-Source-Session-Id: $AMC_SESSION_ID so the change is attributed to you. Your own session token is enough: writes are open to agent sessions on purpose, with no approval prompt. See CLI control for how tokens work.

Call	What it does
GET /custom-css	The state: css (what is being applied, after cleaning), enabled, disabledBy ("setting", "safe-mode", "boot-flag" or null), filePath, author ({kind: "user" | "cli" | "session", sessionId?, at} or null), updatedAt, warnings ([{code, message}], codes remote-url, import, row-height, size) and canUndo.
PUT /custom-css	Replaces the whole stylesheet. Body is exactly {"text": "<css>"} — any other key is a 400. Up to 512 KB. Stores your text verbatim, keeps the version it replaced for one-step undo, and returns the new state.
POST /custom-css/undo	Restores the version the last write replaced. Undo is itself a write, so calling it twice redoes. With nothing to undo it changes nothing and returns the state.
POST /custom-css/disable, POST /custom-css/enable	Turn the layer off or on by flipping the persisted customCssEnabled setting (default true; read it with GET /settings/customCssEnabled). The rescue route; it takes effect on screen at once.
GET /custom-css/anchors?q=<word>	The name tags: {total, matched, truncated, anchors: [{name, description, kind}], selectorHint}. q is a case-insensitive match on the name only, not the description. At most 200 per response — if truncated is true, use a longer word.

Two neighbours help: GET /ui/snapshot lists the name tags mounted right now, with whether each is visible and where it is on screen (needs an open Omniscio window, else 503), and GET /ui/screenshot returns a PNG of the main window so you can check your result — that one accepts only the install-wide token, so an agent session's own token is refused.

A good loop:

1. GET /custom-css — note enabled and canUndo. Do not write css straight back when warnings is not empty: css is the cleaned text, which can be shorter than the file (removed web references, or a refused sheet comes back empty). Read the file at filePath if you can reach it, or ask the person, before you rewrite.
2. Find names with GET /custom-css/anchors?q=sidebar, and confirm they are on screen with GET /ui/snapshot.
3. PUT /custom-css with the full new text — the person's existing rules plus yours.
4. Read the returned warnings, and enabled. If disabledBy is "safe-mode" or "boot-flag", your CSS is being held off whatever you write — tell the person.
5. To back out: POST /custom-css/undo, or POST /custom-css/disable.

Provenance. Every write records who made it. A session token (or the session id you send in X-AMC-Source-Session-Id) is recorded as {kind: "session", sessionId}; the install-wide token with no session is cli; the Settings editor is user. The card shows it.

How it is applied. Main keeps the raw text in <data folder>/styles/custom.css (a missing file is an empty stylesheet) and a sidecar custom-css-meta.json holding the author, the time and the one previous version. The text is cleaned again whenever the file changes, and a directory watcher (300 ms debounce) picks up hand edits. Each window adds the cleaned sheet as one <style id="amc-custom-css"> at the end of <head>, so it beats the app's own rules by source order; against anything more specific — a theme that sets a variable on a more specific selector, for example — put !important on your value.

Switches. customCssEnabled (setting, default on) · action id toggleCustomCss, default Ctrl+Alt+Shift+C · launch option --no-custom-css · environment variable AMC_DISABLE_CUSTOM_CSS=1 (exactly 1) · Safe Mode (--safe-mode, AMC_SAFE_MODE=1, or a SAFE_MODE marker file in the data folder). disabledBy reports the winner in the order boot-flag, safe-mode, setting.

Cleaning rules. @import removed (import warning) · image-set() replaced by none (remote-url) · any url() not starting data:, blob: or # replaced by url("about:blank") (remote-url) · any backslash, or any remote-capable url( left after rewriting, refuses the whole sheet (css comes back "", warning remote-url) · over 512 KB is cut with a size warning · a rule that sets height, padding, margin or line-height on .sidebar-session-row or .mobile-session-row gets a row-height warning but still applies.

Session row height. --amc-session-row-height must resolve on <html> to an absolute px length (^\d+(\.\d+)?px$); the renderer rounds it, floors it at 24, republishes it inline on <html>, and feeds the same number to the list's estimate. Only .sidebar-session-row (the desktop list) reads it, as height: var(--amc-session-row-height). Set it on :root, not on the row.

Theme variables. A theme-file key becomes a variable by a fixed map (THEME_VAR_MAP in src/shared/custom-theme-types.ts): usually the key in kebab-case behind -- (panelBg → --panel-bg, accentRgb → --accent-rgb, iconTealRgb → --icon-teal-rgb). The exceptions: surface100 → --color-surface-100 (and its -rgb twin --color-surface-100-rgb, which is the one the app actually reads), fontFamily → --font-family-body, tooltipText → --tooltip-fg, statusEmberRgb → --status-ember-500-rgb, supermailRowSpacing → --supermail-row-py. Variables ending -rgb hold three space-separated numbers. The in-app Theme Creation Guide lists every key, and its text is also written to THEME_GUIDE.md inside the themes folder of the data folder.

Where it lives. The service and cleaner: src/main/services/custom-css/. The routes: src/main/services/cli/cli-server-custom-css-routes.ts. The wire types: src/shared/custom-css-types.ts. The shortcut: src/shared/keybindings/custom-css.keybindings.ts. The name-tag list: src/shared/ui-anchor-registry.generated.ts (declared next to each feature in *.ui-anchors.ts files). The card: src/renderer/src/features/settings/AppearanceCustomCssCard.tsx.

Related

• Custom CSS — the focused reference for the stylesheet layer on its own.
• Visual themes — pick or import a whole colour theme; custom CSS layers on top of whichever theme you choose.
• Safe mode — the recovery boot that also holds custom CSS off.
• Keyboard shortcuts — where to change the Ctrl+Alt+Shift+C shortcut.
• CLI control — how an agent talks to Omniscio's local control interface.

More ways to customize Omniscio are on the way; this guide grows as each one ships.