Skip to content

Settings

throw99 edited this page Nov 17, 2026 · 6 revisions

Settings holds the app's pages. It covers the side panel and the terminal area. Open it with Ctrl+Shift+, or File › Settings. On macOS, use the app menu.

The page list has two groups. The first group has the name of the Host in the window, and its pages read and change that Host. The App group stays on this computer.

Group Page Content See
Host name Agents The agents, their programs and flags, and the words for session names. Skiff agent › Settings › Agents
Host name Usage Each agent's plan limits: percent used and reset times. Usage
Host name Skippers One table with one row for each Skipper. Skiff agent › Settings › Skippers
Host name Task types The agent, the model and the instruction file for each kind of task. Skiff agent › Task types
Host name Schedules The schedules: when each one runs, the Skipper that takes the run, and the prompt file. Schedules › Settings › Schedules
Host name Sessions Every session in skiffd. skiffd › Settings › Sessions
Host name Disk use The Skiff agent's folder, Auto flush and the folder as a tree. Skiff agent › Disk use
Host name Images The image library as a gallery. Images
App Appearance Language, Menu, Avatar finish and App theme. Appearance
App Open with The apps and tools that open files and diffs. Open with
App Hosts The servers that you reach over SSH. Hosts

Ctrl+Shift+Up and Ctrl+Shift+Down go to the previous or next page. Ctrl+Shift+Right goes into the page. Ctrl+Shift+Left goes back to the page list. Esc closes Settings. On macOS, Ctrl+Shift is ⌘+Shift.

Usage

Settings › Usage shows the plan limits of each agent that the Host has. Open it with Ctrl+Shift+. (⌘+Shift+. on macOS), View › Usage or the palette. Press the key again on the page to close Settings.

Each installed agent has a band with its name and program. The band also shows the plan and the time of the last read. Under the band, each row is one limit window, with the columns Limit, Used and Resets. Every number is percent used.

The Host reads usage with each agent's own command. It opens no credential file and calls no vendor endpoint.

Agent Command
Claude Code claude -p /usage --output-format json --no-session-persistence
Codex codex app-server, then account/rateLimits/read
Antigravity agy -p /usage --output-format json
Grok grok agent stdio, then _x.ai/billing

An agent with no reader shows "No usage read." A read that fails shows its error line under the band. A changed output format is a failed read. Skiff does not guess a number.

The Host reads an agent at these times:

  • The page opens: each agent whose last read is older than 60 seconds.
  • Read now: every agent.
  • A pane of the agent ends a turn: at most once in 60 seconds.
  • An agent with a running pane: 15 minutes after its last read. After a failed read, the wait doubles, up to 30 minutes.

An agent with no running pane is read only when the page opens and on Read now.

A window is near its limit at 90% used for a window of 5 hours or less, and at 80% for a longer window. While a window is near or at its limit, the top bar shows a usage cell after Waiting and Unread. The cell shows the agent and the highest percent. At 100%, it also shows the reset time. "+N" counts the other agents near a limit. Click the cell to open Settings › Usage. The cell sets no session state and rings nothing.

Keys

F1 shows every key, from the live keymap. To change an action key, write it under [keys] in client.toml:

[keys]
palette = "ctrl+shift+k"

ctrl is ⌘ on macOS. The action names are the ids in apps/desktop/src/app/keys.ts. Before the first setting that Skiff writes to client.toml, Skiff reads [keys] from projects.toml. See Design › Interaction rules.

Appearance

The page has these rows, top to bottom:

Row Content
Language The language of the app.
Menu On Linux only: Auto, Header bar or Menu bar. Auto selects the header bar on GNOME, and the menu bar on other desktops. The change applies when the window opens again.
Avatar finish Plush, Gummy or Flat, for every Skipper face. The row shows sample faces.
App theme The themes, with their count.

Language

Select Language in Settings › Appearance. The list has Auto, English, Español and 简体中文. Auto shows the system language in its name, and uses it.

The window reads the language when it opens. Until the window opens again, the row shows "On restart".

Skiff saves the choice as language under [appearance] in client.toml. Auto removes the key. You can write a code by hand. Skiff uses the language part of it: es-MX selects Español. A language with no catalog shows English. Traditional Chinese (zh-TW, zh-HK, zh-MO, zh-Hant) shows English.

Dates, times and numbers follow the system locale when it has the same language. Otherwise they follow the language.

The words come from the word catalog. See Design › Word catalog.

App theme

Click a theme to use it for the app. A project and a session can use a different theme. See Design › Theme scope.

Skiff has 40 built-in themes. Six of them are quiet themes, with neutral text, muted terminal colors and an accent of their own:

  • Chart Room
  • Engine Room
  • Kelp
  • Morning Watch
  • Plumb Line
  • Sailcloth

Above the themes are the search, the color filter, Import themes…, Open theme folder and the count. skiff theme ls lists the same themes. See CLI › Theme commands.

The [ui] table of a theme file

A TOML theme file with a [terminal] table can also have a [ui] table. The table sets the colors of the app. If a key is missing, Skiff makes the color from the theme's other colors.

Key Sets
background, foreground The main ground and text.
sidebar, card The panel ground. sidebar comes first.
tertiary The deepest ground.
secondary, muted The raised ground. secondary comes first.
border The rules.
mutedForeground, sidebarForeground The dim text and the panel text.
primary The accent. It also sets the working state, if working is missing.
working The working state. Use it to keep that state off the accent.
warning The waiting state.
destructive Errors.

Clone this wiki locally