desktop and web client ​

kage-desktop and the browser client are one program. The desktop app starts kage rpc and shows its sessions; the browser client attaches to the kage serve it was loaded from. Both read and write the same engine state, so a session started in one shows in the other and in the TUI.

On Linux and macOS, the kage rpc the desktop app starts connects to the shared host, the engine your editors use too, so a session open in the app and in an editor is one live session.

settings ​

Settings opens from the gear at the bottom of the sidebar. Its pages:

PageWhat it holds
GeneralTheme, input, chat and session preferences, below
Agent & SessionsThinking default, compaction and the subagent and swarm limits, written to the user config.toml
Model ProvidersBuilt-in, custom and ACP providers, and adding one
MCP ServersThe configured MCP servers with their live status, and editing them
PermissionsThe permission mode and the allow, ask and deny rules
PluginsThe installed Lua plugins, and installing one
ConnectionHow the client reaches the engine, and the kage binary the desktop app runs
KeyboardEvery shortcut, with the vim keys when vim mode is on
Archived SessionsSessions archived from their menu, to restore
AboutThe client and engine versions, the protocol, and the release check

The About page compares the engine and this client against the public releases at most once a day; Check now re-runs it, and Releases opens the releases page in your browser. The engine shipped beside the app updates with it, so a release offers one install for both.

The pages that edit engine options write the user config, as configuration describes. A project config that sets the same key still wins, and changes apply to sessions started afterwards.

general ​

The General page holds the client's own preferences.

appearance ​

The theme cards pick a bundled or user theme, or System, which follows the desktop's light or dark mode. System on a dark desktop and System on a light desktop pick the pair System draws; they set [ui] theme_dark and theme_light, which the TUI reads too. See themes for writing a theme the client draws.

input ​

SettingDefaultWhat it does
Vim modeoffNormal-mode motions over the transcript (j k gg G za / n), a : command line and a modeline. Esc leaves the composer.
Enter sendsonOff, Enter adds a newline and Ctrl+Enter sends.

chat ​

SettingDefaultWhat it does
Smooth streamingonShows a reply that arrives in bursts at a steady pace.
Turn timeline railonA minimap beside the transcript with ticks for turns, edits, approvals, failures and swarms.
Context gaugeonThe context ring in the composer opens a gauge with a Compact now action.
Swarm constellationonSwarm cards draw one star per worker, lit by its state.

Some providers send a reply in bursts: nothing for a few seconds, then hundreds of characters at once. Smooth streaming spreads each burst over the time the bursts have been arriving apart, so the text keeps moving between them. A provider that already streams smoothly shows at most a quarter of a second behind. Turn it off to show every character the moment it arrives.

sessions ​

SettingDefaultWhat it does
Group sessions by projectonLists sessions under their project folder in the sidebar.
Ask before enabling swarmonConfirms before swarm mode turns on.

external agent sessions ​

When the host supports external sessions (Linux), the new session screen's model picker lists each configured external agent as acp:<name>. Picking one opens a session on that agent instead of the kage engine, and the session keeps its conversation between turns. See external sessions. The toolbar shows the agent's name where the model picker was. Prompts, cancelling and permission answers work as usual. Changing the model or mode, forking, renaming, compacting, exporting, browsing files and swarms are refused with a notice, because the agent owns them. Pressing Ctrl+Enter sends a plain prompt, as external agents cannot be steered.

where preferences live ​

The General page's preferences, pinned and archived sessions, starred models and the last session's model choices are the client's own, not engine state, so they never reach the server. The desktop app keeps them in desktop.json in the kage config directory ($XDG_CONFIG_HOME/kage, else ~/.config/kage, else %APPDATA%\kage). The browser client keeps them in its localStorage, under kage.desktop, so each browser has its own.

The two system theme picks are the exception: they live in the engine's config, so every client and the TUI share them.