Ember docs

Install #

Ember runs on Windows 10 and 11, x64. It is free, needs no account, and installs just for you, without an admin prompt.

All three always point at the latest release on GitHub Releases, where you also find SHA256SUMS.txt to check the files. The portable builds keep their settings in ~/.ember like the installed one, so nothing is written next to the exe.

Ember replaces the window, not your shell. It starts PowerShell 7 (pwsh.exe) through the same ConPTY Windows Terminal uses, so your profile, modules, oh-my-posh and PSReadLine behave as before. If PowerShell 7 is not installed, it falls back to Windows PowerShell.

First launch #

The first time Ember opens it shows a short welcome in four steps. You can skip it and come back any time with welcome in the command line (CtrlK).

1. Welcome. What Ember adds on top of your shell.
2. Which agent do you work with? Ember lists the six supported CLIs and marks the ones it found on your PATH. Missing ones have an Install button that runs the install command in a tab. The one you pick is also the one Ember uses for the orchestrator and the map.
3. Make it yours. The house pair, Ember Night and Ember Day, then a few of the other 49 colour palettes, and a switch between full motion and a lighter setting for older laptops.
4. Six keys. CtrlK, CtrlShiftT, CtrlShiftJ, CtrlShiftG, CtrlShiftS and F1, plus an option to start your agent in the first tab when you finish.

On first launch Ember also writes ~/.ember/config.json with the defaults, puts its commands (ember, notes, todo, desk) in ~/.ember/bin on the PATH of every shell it opens, and installs its skills.

Every launch starts with one fresh shell. Ember does not restore tabs or old scrollback from the last run.

Choosing a CLI #

Ember hosts the agent CLI you already use. You can run any of them in any tab. The one chosen in Settings › Agent is the one Ember itself calls for the orchestrator and the map.

"Automatic" means that when you start the CLI by its usual name in an Ember tab, Ember attaches its panel server for that session only. Nothing is added to the CLI's global config. Cursor Agent has no flag for this, so to use the panel with it you would add the server to ~/.cursor/mcp.json yourself; Ember writes the launcher for it to ~/.ember/bin/ember-mcp.cmd.

Claude Code gets the most: live transcripts (used by the overview and the orchestrator's reports), the status line under each session, and optional plan usage in the sidebar. Claude Code and Codex are tested end to end; the others follow their documented flags.

No API keys #

Ember never talks to a model itself and has no field for an API key anywhere. Every AI feature runs through a CLI on your machine, signed in with your own plan:

• The orchestrator and the map run a headless turn of the CLI chosen in Settings › Agent.
• Check todos runs your local Claude Code with the /check-todos skill.
• The panel is drawn by whatever agent is running in that tab.

Usage counts against that CLI's plan, the same as when you use it anywhere else. Ember stores no credentials.

Sessions and the sidebar #

Each session is a card in the left sidebar rather than a tab in a strip, because each one carries state. CtrlShiftT or the + next to "Sessions" opens a new one; CtrlB hides the sidebar.

Above the sessions are four buttons that are always there: Overview, Todo, Notes and Map. Each is a place of its own, not a session card. The one you are on is tinted with the accent. Overview carries an amber count of the sessions waiting on you, and Todo the number of open items. Their shortcuts (CtrlShiftS, CtrlShiftD, CtrlShiftG) go there, and pressed again take you back to the session you came from.

What a card shows

• Status. Working, waiting on you, idle or exited, read from the screen of the program in that tab. When an agent CLI is running, the card shows Cinder, a small ember sprite: burning while the agent works, dozing while it waits, raising a hand when it needs you, waving when it has just finished.
• Attention. When a session needs you (a question, a permission prompt, a finished answer), its card tints amber and a short chime plays. Nothing goes to the Windows notification centre.
• Project. Git branch and dirty-file count for the session's folder, and a chip for any localhost URL a dev server printed (click to open).
• Claude status. For Claude Code sessions: model, context used and session cost, e.g. Fable · 8% · $0.01.
• Unread dot on background sessions that printed output.

Working with cards

• Rename with F2 or a double-click. An empty name hands the title back to the shell.
• Close by pressing and holding the card's × for half a second, so a stray click can't close a terminal. CtrlShiftW closes immediately.
• Reorder by dragging cards.
• Switch with CtrlTab, CtrlShiftTab, or CtrlAlt1…9.

The strip at the bottom

Under the cards is a small status strip:

• CLAUDE (off by default): your Claude plan's five-hour and weekly limits. Turn it on in Settings › Agent. It reads the login Claude Code already keeps on this machine, once a minute; no model runs. PLAN ? means that login has expired; running claude once refreshes it.
• MACHINE: processor load, memory, and battery on laptops.
• COMPUTER: appears only once an agent has used computer use, with its STOP switch.

The title bar also has a Visualize button when the focused tab runs Claude Code (it asks that session to put what it just said on the panel), a moon or sun that switches between Ember Night and Ember Day, and a panel button that carries a dot when a background session drew on a panel you have closed.

Shells

New sessions start the default profile, PowerShell 7. Windows PowerShell (winps) and Command Prompt (cmd) are also defined. To change the default, run ember set defaultProfile cmd, or edit the profiles list in config.json to add your own (a command, args and an accent colour).

Splits and panes #

• AltShift+ puts a new pane to the right, AltShift- puts one below. The new pane opens in the same folder.
• Drag the seam between panes to resize.
• Alt + arrow keys move focus between panes.
• CtrlShiftZ zooms the focused pane to fill the session and back.
• CtrlShiftA broadcasts your typing to every pane in the session. The stage gets an amber border while it is on.

Splits are one level deep: a row or a column of panes, not nested quadrants.

Command line and palette #

CtrlK (or CtrlShiftP) opens one line that runs every action Ember has. Type the words and press Enter: new, split, todo, theme nord, rename api, o run the tests. Matching is fuzzy, so spd finds "Split pane down". Every button in the app runs one of these commands; hover it to see which.

A first character switches the line into a picker:

Inside a note, the todo list or the map, the line also knows that surface's own words (see those sections).

The ember command

The same actions work from any Ember shell as ember <words>. A command acts on the tab that typed it, which means an agent running in that tab can split a pane, open the panel or hand the orchestrator a task with the same words you would.

ember                        the full list, from the running app
ember new [dir]              new session (short: n)
ember split right|down       split this tab (s / sd)
ember close                  close the focused pane (x)
ember rename <name>          name this tab (r)
ember focus <n|name>         switch tab (f)
ember list                   the open tabs
ember panel show|hide        the panel (p)
ember visualize              ask the Claude in this tab to draw what it just said (v)
ember orch "<text>"          hand something to the orchestrator; prints its answer (o)
ember overview               every session on one screen (ov)
ember map [project]          the architecture map
ember todo                   the todo list (t)
ember theme <name>           apply a theme (th)
ember settings [tab]         open Settings
ember zen                    hide all chrome
ember set <path> <value>     change one setting, e.g. ember set window.opacity 60
ember get <path>             print one setting
ember diag [n]               the last lines of Ember's diagnostic log

ember set, ember get and ember diag edit or read files directly, so they work even when the app isn't running.

Keyboard shortcuts #

F1 shows these inside the app.

CtrlK is readline's kill-line in some shells; Ember takes it for the command line. CtrlShiftP does the same thing without taking anything from the shell.

Terminal tools #

Command blocks

Each command and its output is treated as one block. Ctrl↑ / Ctrl↓ move by command instead of by line. A rail on the right edge has one tick per command, red where a command failed; click a tick to jump there. While you scroll through long output, a sticky header names the command that produced it.

Shell integration

On by default. Ember wraps your PowerShell prompt (it doesn't replace it, so oh-my-posh keeps working) so it reports the working directory and each command's exit code. That is what powers the git badge, the red failure ticks, the task runner, and splits that open in the same folder. Turn it off in Settings › Behaviour if it conflicts with something in your profile.

Also in the terminal

• Copy last output (CtrlShiftO) copies what the last command printed, without the prompt.
• Task runner: CtrlK then ! lists package.json scripts and Makefile targets.
• Port rescue: after an "address already in use" error, the command line offers to stop whatever holds the port.
• Reset terminal modes (reset in the command line) fixes stray mouse codes a crashed program left behind.
• Sound: short synthesized cues for switching, opening, closing, attention, and success or failure of commands that ran longer than about a second. Settings › Behaviour turns them off.

The panel #

Every tab has a panel on its right that the agent in that tab can draw on. It stays closed until something is put there, then opens. CtrlShiftJ or the title-bar button shows and hides it; drag its left edge to resize it.

The agent reaches it through four tools Ember gives the session:

You don't have to ask. With the visualize skill installed, Claude Code draws on its own whenever an answer has a shape: a diagram for a flow, a table for a comparison, a mockup for UI. To ask for it explicitly, say "show me", type /visualize, or press Visualize in the title bar.

Answering from the panel

• Buttons. A button on the panel types its text into the session beside it and presses Enter. Some buttons only fill the prompt and leave Enter to you; agents use those for anything destructive.
• Questions. An ask_panel card sends the answer you pick, or whatever you type in its box, as your next message.
• Pointing. CtrlShiftE (or the target icon in the panel bar) turns on select mode. Hover highlights a block (a table cell selects its whole row); click it to get a small box with quick prompts. What goes to the session quotes what you picked, e.g. On the panel, row 2 — "Golf | 2016 | 7200": is this one worth it. This works on web pages opened in the panel too.

Settings › Agent has the panel's default width and whether it opens by itself the first time something is drawn.

The orchestrator #

One agent that can see every session and give them work. Open it with CtrlShiftM or the orchestrator button in the sidebar; it opens under the session cards and you type to it. From a shell, ember orch "…" sends it a message and prints the answer.

Examples of what to say: "ship the login fix and update the docs", "what is the api session doing?", "start a session in ~/web and make the header sticky".

How it routes work

The orchestrator is not a model Ember calls. Each turn is one headless run of the CLI chosen in Settings › Agent, with a small set of tools that act on Ember's tabs:

It answers questions itself by reading files, and never edits files or runs commands itself: changes always go to a session, where you can see them. It prefers an idle session and opens a new one when all are busy or the work belongs in another folder.

When a session finishes a task you get a toast and the orchestrator reports what it said. For Claude Code the end of the turn is read from its transcript; for other CLIs, from the card going from working to quiet. If a newly started CLI stops on its own prompt (folder trust, sign-in), Ember tells you rather than typing into it.

The conversation is kept in the window, so it lasts until you close Ember.

The overview #

Every session on one screen, built to work from. Overview, Todo, Notes and Map are four buttons at the top of the sidebar, always there. Open the overview with one of them, CtrlShiftS, or ember overview (ov); the shortcut again takes you back to the session you came from.

• The numbers along the top: sessions working and waiting, tokens (and how much came from cache), spend, lines added and removed, the fullest context window, your plan's usage, and a sparkline of the last hour.
• A card per session, in tab order: state, folder, what its Claude last said, the tool it is on, and a line of facts (branch, model, tokens, +/− lines, cost, context).
• When a session asks permission, its card shows the question as the terminal draws it, with the options as buttons. Click 1, 2, 3, Enter or Esc to answer without leaving the page.
• A reply you have not seen stays open in full on its card. ⤢ or Space opens any card in place with its whole last reply and recent actions. Arrows move between cards, Enter goes to one, and typing starts an answer.
• The rail: your todo list (tick or add items), your recent notes, and a quiet activity log of every edit, command and finished turn across all sessions.
• Along the bottom, the orchestrator's last reply and a line to answer it.

Tokens, changes and replies come from Claude Code's own transcripts, read in full when a session announces itself, so the totals cover the whole session.

The map #

A zoomable architecture picture of a project that your agent keeps up to date. Open it with the Map button at the top of the sidebar, CtrlShiftG or map; it starts with the list of your mapped projects.

Setting up a project

New project asks for a name and a sentence or two about what belongs to it: folders, repos, a Heroku app, a domain, or just "everything about the checkout service". Your chosen CLI surveys it once, read-only, which takes a few minutes, and draws the map: areas, then repos, apps, services, datastores and external services, then the parts inside them, with the connections between them.

Using it

• Scroll to zoom. A box opens into its parts once it is big enough on screen. Drag to move, double-click to dive in, F to fit, / to find.
• Hover a part to dim everything except its connections. Click a part or a line for a card with its health, where it runs, what changed, risks, open PRs, connections and the flows through it.
• Flows traces a journey (a checkout, a deploy) step by step. From any part, if it goes down shows everything that depends on it.
• Changes lists the map's history; Timeline scrubs back to earlier versions; Replay plays everything since you last looked. New parts are marked NEW and changed ones show a count.
• Parts an agent is editing right now get a ring in that session's colour and a chip naming the tab.
• Right-click anything to ask about it. The answer comes from your agent with read-only tools in that part's folder. The Change it button opens a normal session in the part's folder, briefed with your request.

How it stays current

Every few minutes Ember runs a cheap check, with no AI, of what the project watches: local git commits, GitHub pushes, Heroku releases, live URLs. Only when something moved does your agent run, and it updates the existing map rather than redrawing it, so parts stay where you learned them. Each project lives in ~/.ember/maps/<project>/ with every version kept.

The map itself is read-only; changes to your code always happen in a session you can see.

Notes #

Type notes in any Ember shell for the list, or note for a new page (note buy milk starts one with that text). Typed in a shell, notes open over that tab; the shell keeps running underneath, and Esc (or the back command in the command line) brings it back as it was. In a note, Esc first goes to the list, then to the shell. The Notes button at the top of the sidebar opens them as a place of their own.

• There is no save key. The editor saves 400 ms after you stop typing.
• The first line is the note's title and its file name. Rename a note by editing its first line.
• /todo on a line turns what follows into checklist items.
• In the command line inside a note: new, open <name>, del [name], list, view text|list, folder, back.

Notes are ordinary .md files in Documents\Ember Notes (set EMBER_NOTES_DIR to move them). Any editor can open them, Ember holds no lock on them, and deleting sends a note to the Recycle Bin. The folder is watched, so a note changed elsewhere updates in front of you.

The notes command

It's a real command on the PATH of every Ember shell (PowerShell, cmd and Git Bash), so an agent can read and write your notes with no extra tool:

notes                        open the Notes tab
notes list [--json]          every note, newest first
notes read <note>            print one
notes new [--open] [text…]   create one; the text is its first line
notes write <note> [text…]   replace its content (text, or stdin)
notes append <note> [text…]  add to the end (text, or stdin)
notes delete <note>          to the Recycle Bin
notes open [note]            show it in an Ember tab
notes dir                    print the folder

<note> is the file name or a unique part of the title.

The todo list #

Its own surface, separate from the notes. Open it with the Todo button at the top of the sidebar or CtrlShiftD; the shortcut again goes back to your session. todo typed in an Ember shell opens the list over that shell. The overview shows the open items too, and you can tick or add them there.

Ticked items are never deleted, only cleared: Clear done moves them to an archive under a heading for the day. The archive shows below the list as archive · n, and each archived item has a ↩ to bring it back.

In the command line on the list: add <text>, done <words>, dismiss <words> (remove without ticking), open <words> (open where an item came from, such as a Jira ticket or a PR), claude <words> (hand an item to a new Claude session), clear done, archive, check, sources.

From any shell, and from any agent:

todo add "<text>"            add an item
todo done <words>            tick the first open item containing the words
todo list [--all]            open items (--all adds ticked and archived)
todo clear done              archive the ticked items
todo archive                 print the archive
todo check                   run Check todos

The list is a plain file, Todo.md, next to your notes, one - [ ] item per line; the archive is Todo.archive.md. With the ember skill installed, Claude adds to it when you mention something for later, or when a turn leaves a step only you can take, and ticks items it sees get done.

Check todos #

The Check todos button on the list, todo check, or /check-todos in a Claude Code session goes through what arrived since the last check in your mail, Slack, Jira and GitHub and:

• adds what you have to act on, and
• ticks open items those sources show as handled: a thread you replied to, a PR that merged, a ticket that closed.

It runs your local Claude Code once, with the tools that Claude already has. There's nothing to set up in Ember; the sources work if your Claude can reach them:

Choose which sources this machine checks in Settings › Todo (the list's Manage sources button goes there). todo check gmail checks one source for a single run. The first run looks back three days; later runs read only what is newer than the previous check.

There's no schedule and no cloud service: it runs when you press the button.

Settings #

Ctrl, opens Settings (or ember settings [tab]). Every control previews live. The panel edits ~/.ember/config.json, and Ember applies any change to that file on save, so editing the file by hand does exactly the same thing. A half-written file is ignored until it is valid again.

At the top: a Filter settings box that searches every tab, and Reset to defaults, which asks for a second click because it can't be undone.

Look

Theme. A grid of 51 palettes, led by the house pair: Ember Night (the default) and Ember Day. The sun/moon button in the title bar, or ember mode night|day, switches between them, and remembers if you pick a different theme for either side. Then Ember's own, ports of well-known themes (Tokyo Night, Catppuccin, Dracula, Nord, Gruvbox, Kanagawa, Rosé Pine, Solarized and more), light themes and single-colour retro sets. A theme re-tints the whole window, not only the terminal.

Motion

Speed has two presets. Full turns on the breathing caret, its trail and glow, and output motion. Fast turns those four off, which saves CPU on older machines. The text is the same either way.

Agent

Your agent lists the six supported CLIs, shows which are installed (Ember checks again every time you open this tab), and has Install and sign-in buttons that run in a new tab. The one you select is used for the orchestrator and the map. Default: Claude Code.

Todo

Which sources Check todos reads on this machine: Check Gmail, Check Outlook, Check Slack, Check Jira, Check GitHub. All are on by default. A work laptop might have Outlook, Slack and Jira; a personal one Gmail and GitHub.

Behaviour

Labs

One switch, Labs, for experimental features. Today that's only the phone link. Default: off.

Only in config.json

A few options have no control in the panel. Set them with ember set <path> <value> or in the file:

Skills #

Ember ships three Claude Code skills. You don't need to install them by hand: Ember copies them into ~/.claude/skills/ every time it starts, and also into ~/.codex/skills/ if Codex is on the machine. Because they live in your own skills folder, they work in any Claude Code session on the machine, not only inside Ember.

Editing them

Each installed SKILL.md starts with a comment line saying it was installed by Ember. While that line is there, Ember keeps the file up to date with the version it ships. Delete that line and the file is yours: Ember won't overwrite it again.

Installing them by hand

To use the skills on a machine without Ember, copy the folders from resources/skills in the repository into ~/.claude/skills/, so you end up with ~/.claude/skills/ember/SKILL.md and so on. The panel, notes, todo and desk only exist inside Ember, and the skills say so to the agent when they're missing.

For Check todos, also connect the sources you want in Claude Code itself (the Gmail or Atlassian connectors, a Slack or Microsoft 365 tool, a signed-in gh). Ember doesn't install those.

Computer use #

An agent running in an Ember tab can operate other apps on your desktop: open programs, click buttons, fill in fields, read text from windows and take screenshots. It does this with the desk command, which exists only inside Ember shells.

Turning it on

There's no setting. It needs Python 3 on the machine (from python.org, reachable as py or python). The first time an agent runs desk, Ember starts a small background helper and, if its Python libraries are missing (pyautogui, pywinauto, mss, Pillow, pyperclip), installs them for your user with pip. If Python isn't installed, the COMPUTER row in the sidebar says so. The helper stops when Ember closes.

The ember skill already teaches Claude the commands, so in practice you ask for the result ("open Calculator and work out 7 × 6", "fill this form in the browser") and Claude uses desk.

What you see

• A second cursor. While the agent works, Ember draws the agent's own orange pointer where the action is happening. Your mouse stays yours.
• The COMPUTER row in the sidebar strip shows what is being done and a STOP switch.
• A "Stop Claude" pill on screen next to the drawn cursor.

Stopping it

STOP in the sidebar, the on-screen pill, or desk halt all do the same: the helper process is killed and every desk command answers HALTED until you press Resume (the same switch) or run desk resume. The halt is saved to disk and survives a restart of Ember.

Commands

desk do "focus X; press X ^OK$; shot"         several steps in one call, stops at the first failure
desk shot [--window T|--full] [--scale 0.5]    screenshot to a file
desk windows                                   visible windows (* = foreground)
desk focus TITLE | desk wait TITLE             raise a window / wait for one
desk run CMD [ARGS...]                         launch a program
desk tree TITLE [--depth N]                    the window's controls (UI Automation)
desk find TITLE NAME | desk press TITLE NAME   find or click a control by name
desk settext TITLE NAME TEXT                   fill an input
desk read TITLE [NAME]                         text of a window or control
desk click X Y | move | drag | scroll          raw mouse input
desk type TEXT | desk key ctrl+s               raw keyboard input
desk clip [TEXT]                               read or set the clipboard
desk halt | desk resume | desk status          the STOP switch

TITLE matches part of a window title, or an exact title as ^Title$. A log of what the helper did is kept in ~/.ember/desk.log.

Labs: the phone link #

Off by default, and experimental. With Labs on in Settings, the command line gets Connect your phone (devices). It puts this machine on an Ember account with a QR code, so a phone companion, or another machine, can reach the orchestrator here. Traffic goes through a relay Deep Answer Labs runs; the relay routes by a hash of the account key and never sees the key. The account key is stored in ~/.ember/account.json; treat the QR like a house key.

The phone app itself isn't published yet (its source is in mobile/ in the repository). Unless you're testing it, leave Labs off.

Files and privacy #

Set EMBER_HOME to keep Ember's files somewhere other than ~/.ember, and EMBER_NOTES_DIR for the notes.

Ember has no account and no telemetry. Your work goes wherever your CLI already sends it. The calls Ember makes on its own belong to features you can see: the plan-usage poll (off by default), the map's change checks against your repos and hosts, and the phone relay (Labs, off by default). The uninstaller leaves ~/.ember and your notes in place; delete them by hand if you want them gone.

Troubleshooting #

Text looks garbled or doubled, as if another window shows through.

That is usually what's behind the window showing through the glass, not broken output. Raise Opacity in Settings › Look, or switch Backdrop to acrylic or mica. With none there is no blur at all, so busy windows behind Ember stay readable through it.

The window turns flat grey when I click away.

Windows only draws acrylic and mica for the active window. Lower Opacity when inactive so Ember fades to see-through instead, or use Backdrop none, which looks the same focused or not.

Ember feels slow or my laptop runs hot.

Choose Fast under Settings › Motion › Speed; the breathing caret is the main cost when idle. Keep Shed effects when slow on. Very high resolutions at high refresh rates (a 4K display at 144 Hz or more) cost the most, since the whole window is composited every frame. On laptops with two GPUs, Ember asks Windows for the high-performance GPU from its second launch; you can change that in Windows Settings › Display › Graphics.

Typing lags while an agent is streaming.

Most of that comes from the CLI and ConPTY rather than the window: a program writing a lot of output reads keys more slowly. Fewer background tabs streaming at once and the Fast preset both help.

The panel stays empty.

The panel is attached when you start the CLI by its usual name (claude, codex, …) in an Ember tab. A CLI started some other way, for example from a script or another terminal, has no panel; open a new tab and start it again. Also check Open the panel on first use in Settings › Agent, or press CtrlShiftJ. For Cursor Agent, see Choosing a CLI.

The sidebar shows PLAN ?.

Claude Code's saved login has expired. Run claude once and it refreshes. Or turn plan usage off in Settings › Agent.

Stray characters appear when I move the mouse.

A program exited without turning off mouse reporting. Run reset from the command line (CtrlK).

desk says it's unavailable.

Install Python 3 from python.org and try again. If pip couldn't install the libraries, run the python -m pip install … line the COMPUTER row shows. HALTED means STOP is on: desk resume. desk only works in a shell Ember started.

Check todos says no sources are ticked, or finds nothing.

Tick sources in Settings › Todo, and make sure Claude Code itself has the matching connector or tool; run /check-todos in a Claude session to see its full answer.

My git badge, red failure marks or task runner are missing.

They need shell integration (Settings › Behaviour) and a PowerShell profile. Command Prompt reports no working directory.

Something else is wrong.

Run ember diag for Ember's recent log, and open an issue on GitHub with it.