Repository navigation
Settings
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.
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.
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.
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. |
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.
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.
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. |