Settings and files

Where things live (Linux)

#

$XDG_CONFIG_HOME and $XDG_DATA_HOME replace ~/.config and ~/.local/share when they are set. Settings → About shows the app’s version and the real paths.

settings.json

#

{
  "version": 22,
  "connectors": { "github": true },
  "sounds": true,
  "volume": 50,
  "fold_after": 15,
  "api_provider": "openrouter",
  "api_models": { "openrouter": "anthropic/claude-opus-5.5" }
}

Agent configs Vults edits

#

Only when you click Write the file, after a dated backup and a diff you reviewed:

Vults no longer supports Gemini CLI. While hooks an earlier Vults installed in ~/.gemini/settings.json are still there, they send nothing, and Settings → Agents shows a Gemini CLI card whose only button is Remove hooks… (the same diff, dated backup and click).

Each agent’s own folder variable moves its file, read the way the agent reads it: CLAUDE_CONFIG_DIR (Claude Code, in place of ~/.claude), CODEX_HOME (Codex, in place of ~/.codex, its config.toml too), QWEN_HOME (Qwen Code, in place of ~/.qwen), COPILOT_HOME (Copilot CLI, in place of ~/.copilot), FACTORY_HOME_OVERRIDE (Factory Droid, in place of the home: its .factory goes inside), KIMI_CODE_HOME (Kimi Code, in place of ~/.kimi-code) and GEMINI_CLI_HOME (Gemini CLI keeps its .gemini inside it; read only to find the old hooks to remove). Started from the desktop, the app does not see what your shell’s startup files export, so it asks your login shell once, when it starts, and keeps only these seven; a shell that takes more than two seconds is given up on, and the usual folders stand. The Claude Code and Codex the app starts itself (the chat, the Codex usage read) get them too, so they use the same folders as in your terminal. Each card in Settings → Agents shows the file it edits. OpenCode’s OPENCODE_CONFIG_DIR is not followed yet.

A write never leaves half a file: the new text goes to a file of its own beside it, is synced to disk, and only then takes the old one’s place. A file with other names (a hard link, as some dotfiles managers and backup tools make) is written in place, so every name sees the change. A file saved with a byte-order mark or Windows line ends (CRLF) keeps them.

Entries from other tools are kept, and Remove hooks… takes out only ours. If you put another tool’s hook in the same group as ours, that group stays: an update changes only our hook in it, and Remove takes out only our hook. In Codex, a hook or group that came after one of ours we take out moves up one place, so Codex may ask you to trust it again in /hooks. An update changes our entries where they are: the file keeps its key order, so the diff shows only what changed. Hooks that run another copy of vults-hook (from another data folder) say so in Settings → Agents, and Update hooks… points them to this app’s (if your own status line is saved beside that other hook, the card offers no update and says so: remove the hooks first, see below).

A config holds a single statusLine, and Claude Code reports the plan’s usage only to it. If you have one of your own, installing saves its whole object in statusline-previous.json beside the hook and changes only its command to ours (your padding and other fields stay); the diff shows both files. Ours then hands the usage to the app, runs your command with the same input (through sh -c, up to 10 seconds) and prints exactly what it prints (up to 64 KiB), colors included. If your command is gone, fails to start or takes longer, the status line is blank that time, whatever it started in the background is stopped too, and Claude Code carries on. Remove hooks… puts your object back as it was; a statusLine you changed since is no longer ours and is left alone. Hooks installed by another data folder keep your line beside their hook: remove them before installing from this one.

Environment

#