Settings Overview

By the end of this page, you’ll know which section of the Settings dialog to open for any given knob, and where to go for the in-depth reference for each one.

Prerequisites

Viberia is installed and running. If not, see Installation & Setup.
Open the Settings dialog from the gear icon on the HudShelf, or with the Settings menu item.

How this page is organized

Settings opens as a left-rail dialog with twelve sections. They’re listed below in the order they appear. Each section is a short tour — for the deep dive, follow the link to the feature page.

1. Appearance

Controls the look of the app — themes, fonts, and visual flourishes for the world map and panels.

Setting	What it does
Theme	Light, dark, or system. Affects panels, dialogs, and the HUD.
Font	Selects the typography used in chat and panels.
Project labels	Toggles the floating labels above each territory.
Liquid-glass tier	Tunes the strength of the frosted-glass effects on panels. Lower it on older machines.

2. Sound

Controls SFX produced by the app — building drops, notification chimes, agent status changes.

Setting	What it does
Enable SFX	Master mute switch.
Volume	Slider from 0 to 100.

Note: Sound is purely cosmetic; turning it off doesn’t disable any functional alert. Status notifications still appear visually.

3. Graphics

Controls how hard the renderer works on the world map. The defaults are tuned for modern machines, but you can scale down for laptops on battery.

Setting	What it does
Quality preset	Low / Medium / High / Ultra. Bundles the settings below.
FPS cap	Maximum frames per second.
Water shader octaves	Detail of the animated sea. Lowering reduces GPU load.
DPR (device pixel ratio)	Overrides the canvas density.

See World Map for the visual context.

4. Usage Tracker

Controls the Token Tracker widget in the bottom-right corner of the world view. The widget shows your usage across model providers.

Setting	What it does
Enable token tracker	Show or hide the widget entirely.
Refresh interval	How often the widget polls for usage updates.
Providers shown	Toggle which providers (Claude / Codex / Gemini) appear in the gauge.

Keyboard shortcut to toggle the widget: Cmd+Shift+U. See Token Tracker.

5. Agent Defaults

Sets the defaults every new agent inherits when you spawn it. Per-agent overrides on an Agent Window always win.

Setting	What it does
Default permission mode	Standard or YOLO. See Permissions.
Default models per role	Pick which model each role tier (Planner / Developer / Reviewer / Dean / CoS / Researcher / etc.) uses by default.

Note: Role-tier defaults are useful when you want, say, every Planner to run on a higher-reasoning model while every Developer runs on a cheaper one.

6. Skills

Manages the slash commands available to your agents.

Setting	What it does
Enable / disable skill	Toggle individual installed skills on or off globally.
Reload definitions	Re-read skills from `~/.viberia/skills/` after editing one by hand.

To install a new skill, run /learn-skill in any agent chat — Viberia knows how to install from a GitHub URL or a free-form description. See Skills for the complete catalog and install flow.

7. CLI Configuration

The paths Viberia uses to invoke each model provider’s command-line tool. Without these, no agent can run.

Setting	What it does
Claude CLI path	Path to the `claude` binary.
Codex CLI path	Path to the `codex` binary.
Gemini CLI path	Path to the `gemini` binary.
Test	Per-provider button that verifies the binary responds.

Each provider has its own integration page with sign-in and model notes:

8. Permissions

Controls how Viberia handles tool calls (filesystem, shell, MCP) requested by your agents.

Setting	What it does
Default mode	Standard (prompt per tool) or YOLO (auto-allow everything).
Full Disk Access (macOS)	Status indicator + button that jumps to System Settings. Required for agents to read and write outside of Viberia’s own scratch space.
Per-agent allowlists	Review and edit decisions you’ve previously locked in via “Allow always”.

See Permission Modes for the full mental model and per-tool details.

9. MCP Servers

The global list of Model Context Protocol servers your agents can use. MCP is how Viberia extends agent capability — file systems, Linear, databases, custom tooling.

Setting	What it does
Server list	Add, edit, enable, disable, or remove servers.
Add via `/learn-mcp`	Use the skill in any chat to install canonical configs for linear, filesystem, postgres, slack, sentry, brave-search, sqlite, google-drive, or git.

User-level MCP servers configured here are inherited by every building and agent. You can also configure MCP servers at building scope (Building Window → MCP) or agent scope (Agent Window → Settings → MCP). See MCP Servers for the three-scope model.

10. Privacy & Analytics

Controls what data, if any, leaves your machine.

Setting	What it does
Master analytics toggle	One switch that gates everything below. Off by default in production builds.
Per-category opt-in	Granular controls for product analytics and crash reporting.
Crash reporting	When on, anonymized crash reports go to our crash-reporting service. Off when the master toggle is off.

Note: Toggling the master switch off mid-session immediately closes the in-app analytics client. Some backend telemetry processes apply consent changes on next restart — restart Viberia for full effect.

11. OpenClaw

Experimental MCP toggle for advanced users.

Setting	What it does
Enable OpenClaw	Turns on the experimental MCP integration. Off by default.

Warning: OpenClaw is experimental and is not covered by the standard support guarantees. Leave it off unless you know you need it.

12. Tutorial

Resets or re-runs the 14-scene first-launch tutorial.

Setting	What it does
Re-run tutorial	Triggers the tutorial state machine from scene 1 on next launch.
Reset progress	Clears all tutorial state without immediately re-running it.

The tutorial uses a sandbox project under ~/Viberia/Tutorial-Demo/ by default if you took the quick path. Re-running won’t disturb your real projects. See Tutorial for what the tutorial actually covers, scene by scene, and Your First Project for the written walkthrough of the same flow.

What just happened

You now have a map of every Settings section, ordered exactly as they appear in the dialog. For any specific setting, the feature page linked from each section is the authoritative reference.

Next: Browse the Concepts section to deepen your mental model, or jump straight into Features.