Configuration

Settings File

User settings are persisted to ~/.cast/settings.json. This file is loaded on startup and saved after changes (model switch, reasoning change, persona change, etc.).

Settings Schema

Settings are written atomically (temp file + rename) to prevent corruption from crashes mid-write.

cast run and background tasks

Background tasks live in the daemon, not in the client. A cast run that created its own session now stops the tasks it started when it exits, and says which ones — the TUI has always done the same on exit. A run that attached to an existing session (--continue / --session) leaves them alone: those tasks belong to whoever started them. --keep-background opts out for the deliberate "start the dev server and leave it running" case, and then the run names what it is leaving behind instead. Under --format json this is a background_tasks_killed or background_tasks_running event.

The Project Root

Rules, project memory, and project-scoped history search are all keyed on the project root: the nearest ancestor directory containing .git, or — when there is no checkout — the topmost one containing .cast/. A nested checkout (a submodule, a vendored copy) is its own project, since its own .git says so, while a subdirectory's .cast/rules stays what it is documented to be: rules scoped to that subtree, not a project of its own.

The home directory is never a project root, whatever it contains: ~/.cast is the global configuration directory, and a dotfiles repository in $HOME would otherwise make everything under it one project sharing one memory.

/reload re-reads the root, so git init mid-session takes effect.

Context files (AGENTS.md / CLAUDE.md)

AGENTS.md (or CLAUDE.md) is read from the working directory and every ancestor, and its content goes into the system prompt of every request. Each file is capped at 64KB — the same ceiling rules use — with a note in place of the rest, so a generated or dumped-into file cannot quietly cost a million tokens per request. Keep these files short and let the agent read the details on demand.

Session store maintenance

~/.cast/sessions/sessions.db holds every session's messages and events. Sessions, events and background runs are pruned on a retention policy, but SQLite never shrinks the file on its own — the freed space stays claimed. At open, cast reclaims it when it is worth the write lock: at least 64MB of free pages and a fifth of the file. The rebuilt database is then checkpointed out of the write-ahead log, without which the space is only moved — a VACUUM in WAL mode writes the whole database into the log. Measured on a real store: 547MB became 324MB in about 2.5 seconds, and the log says so when it happens. Below either threshold nothing runs.

Project Memory

See Memory for a complete guide to what memory is, where the files live, and how it is written and read. This section covers the settings.

Durable project memory is enabled by default. It is one global setting shared by the TUI and Web UI:

• TUI: use /memory, or /memory on / /memory off.
• Web UI: open Settings → Memory and switch the toggle.

When disabled, Cast does not advertise the memory tool, retrieve memory into prompts, or run the background memory writer. The Web UI also removes Memory from the right sidebar. Existing records remain in SQLite and become available again if memory is re-enabled.

Environment Variables

Provider URL and API key are configured only via ~/.cast/settings.json (first-run prompt, or /provider in-session). cast does not read PROVIDER_BASE_URL / PROVIDER_API_KEY environment variables or a project .env — editing those changes nothing.

.cast/ Directory Structure

copy~/.cast/
  settings.json         # User settings
  AGENTS.md             # Global context file (optional)
  mcp.json              # Global MCP server config
  sessions/sessions.db  # SQLite session database (legacy JSON files are imported once)
  skills/               # Global skills
  rules/                # Global rules
  personas/             # Global personas

~/.agents/skills/          # skills.sh universal global
~/.config/agents/skills/   # Compatible universal-global location

<project>/.cast/
  plans/<session-id>/   # Session plan files
  skills/               # Project-local skills
  rules/                # Project-local rules
  personas/             # Project-local personas
  mcp.json              # Project-local MCP config
  hooks.json            # Project-local hooks
  ssh.json              # Project-local SSH hosts

<project>/.agents/skills/  # skills.sh universal project (npx skills add -a universal)

Project Trust

A single trust decision gates all project-local resources: skills (.cast/skills/ and .agents/skills/), MCP servers, context files, personas, rules, hooks, and .cast/ssh.json. cast asks once per project; the decision is saved in settings.json under projectTrust.

Global resources (~/.cast/, ~/.agents/skills/, ~/.config/agents/skills/) always load without a trust check — you put them there yourself.

Permission Modes

Change with:

• --bypass-permissions flag (this run only)
• /permissions command (persists to settings)
• /permissions default or /permissions bypass (direct set)

See Tools for the list of dangerous patterns.

Provider Configuration

On first run, cast asks for your provider URL and API key. Both are saved to ~/.cast/settings.json.

You can save multiple providers and switch between them:

Providers are stored in the providers array in settings.json. The active provider's URL and key are also saved in the top-level providerUrl / apiKey fields for startup.

Supported providers: anything that speaks the OpenAI API. Common URLs: