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, so editing those changes nothing.

.cast/ Directory Structure

~/.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, or --dangerously-skip-permissions as in Claude Code (this run only)
• /permissions command (persists to settings)
• /permissions default or /permissions bypass (direct set)

See Tools for the list of dangerous patterns.

Permission Rules

permissions in ~/.cast/settings.json decides per tool call whether to run it, ask first, or refuse:

{
  "permissions": {
    "allow": ["bash(npm test*)", "bash(git status)", "write(docs/**)"],
    "ask": ["bash(git push*)", "write(package.json)", "mcp_github_*"],
    "deny": ["bash(git push --force*)", "write(.env*)", "edit(/etc/**)"],
    "approved": ["bash(rm -rf build)"]
  }
}

A rule is a tool name, or a tool name with a pattern in parentheses. The pattern is matched against the call's subject:

In a command pattern * matches anything, spaces included. In a path pattern * stays within one directory and ** crosses them. Tool names take * too, so mcp_github_* covers every tool of that MCP server. A rule with a pattern never matches a tool without a subject.

• deny beats approved, which beats ask, which beats allow, regardless of order, so a broad allow can't cancel a deny. A denied call is not run, and the model is told to ask you instead of working around it. Deny applies in bypass mode too.
• ask shows the same prompt as a dangerous command: in the TUI, in the web UI, or in an ACP editor. With nobody to ask (bypass mode) the call runs. cast run without a terminal refuses it.
• allow answers the dangerous-command prompt ahead of time: bash(rm -rf build) runs without asking.

Always allow in the prompt appends an exact rule for that call to approved, for example bash(rm -rf build) or write(src/a.ts). approved outranks ask, so the rule that asked doesn't ask about that call again, and a deny still wins over it. Wildcard characters in the saved subject match only one character, so the saved rule never grows beyond the call you approved. Delete an entry from approved to be asked again. Outside the project, file tools ask first. A read, write, edit, ls, glob or grep that reaches a path outside the session's directory and its project root is asked about, like an ask rule; symlinks are followed, so a link inside the project can't lead out unnoticed. Reads may reach what cast itself hands the agent without asking: saved tool output (~/.cast/tool-output), uploaded files (~/.cast/inputs) and the loaded skills' own files. Control it with external_directory(<glob>) rules on the absolute path (a leading ~/ is your home directory, in every path rule):

{ "permissions": { "allow": ["external_directory(/data/**)"], "deny": ["external_directory(/etc/**)", "external_directory(~/.ssh/**)"] } }

Always allow on that prompt saves external_directory(<that directory>/**). A tool's own allow rule that covers the path (write(/tmp/**)) counts as the answer too. In bypass mode nothing is asked, and a deny still applies. bash is not checked: a shell command's paths can't be known before it runs, so guard those with bash(...) rules.

A prompt outlives the process that asked. While a confirmation waits, it is also kept in the session. If cast stops before you answer (you quit a local TUI, or the daemon stops), the next TUI or browser that opens the session shows the same prompt, marked with how long ago it was asked. Approving it starts a turn that tells the agent the call was approved and lets exactly that call through without asking again; the agent re-runs the step if it is still needed. Blocking it, or sending a new message instead, drops it. A reloaded page or a reattached TUI gets a prompt that is still live the same way, and a prompt answered in one client closes in the others. Questions and plan approvals are saved in the session and come back the same way.

Rules are per tool: deny: ["write(.env*)"] doesn't stop bash from writing the same file, so pair it with a bash rule when that matters. Rules are read on every call and apply at once. Subagents follow the same rules. In an ACP editor, "Allow for this session" is kept for the session only and isn't saved.

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: