Settings reference

How settings are organized

Castforge has two settings areas:

• App Settings are global. They apply to Castforge as a whole, no matter which project is open. You reach them from the app settings area; the header reads "App Settings" with the note "Preferences for Castforge. Per-project settings live on each project."
• Project settings are scoped to one project. Open a project, then open its settings to change only that project's behavior.

Both areas use a left sidebar of sections (not a horizontal tab strip). This page lists both. Where a setting is marked Coming soon or tied to a future version, the control may be visible but not yet active.

App Settings (global)

The global settings sidebar has seven sections, in order:

1. General (look and feel, and new-project defaults)
2. Account
3. Connections (connect your AI CLIs)
4. Extensions (MCP servers and plugins)
5. Notifications
6. Privacy & data
7. About

General

The General section (formerly called Preferences) holds the look-and-feel controls, the defaults new projects start on, and a keyboard-shortcuts reference.

Look and feel.

New-project defaults. The settings brand-new projects start on. Existing projects keep their own values; these controls never change a project you have already opened.

Model preferences. A quiet collapsed block ("Customize models per agent") that, once opened, shows a Top, Mid, and Cheap picker for each connected agent. It sets which concrete model each tier resolves to per agent, as your account-wide default. Until you change a tier it shows the built-in model followed by "(default)"; a small Reset returns a single tier to the default. This is a pure opt-in: leaving everything unset keeps dispatch exactly as it was. Each project can override this default in its own Behavior section. See "Your AI dev team" for the full explanation of tiers and precedence.

Keyboard shortcuts. A read-only reference of keyboard shortcuts, grouped by area (Global, Workspace, Composer, Palette, Navigation), folded into General. Custom rebinding is not available in this build.

Account

The Account section shows your Castforge account and connections. It is mostly read-only.

• Profile: your avatar and email.
• Plan: your current tier (for example, "Castforge Free") and what it includes. An upgrade link is shown where applicable.
• Connected agents: each agent you have connected (GitHub Copilot, Claude, Codex, Gemini, Cursor, Local, and the rest) with its status, and a Manage link to the Connections section.
• Sessions: your current device, marked "Current."
• Castforge account: a Sign in or Sign out control depending on whether you are signed in. Signing out asks you to confirm.

Connections

The global connect surface for your AI CLIs (this section was formerly labeled "Agents"). Each agent (Claude, Codex, Gemini, and the rest) shows a card with its connection status and a connect or sign-in action that launches that CLI's own login. This is the app-wide roster of who is available; which agent fills which role is chosen per project on that project's Team & roles section.

Extensions

The global Extensions section merges the former standalone Plugins and MCP Servers tabs into one surface with two parts.

MCP servers. Register custom MCP servers so your agents can call extra tools. This part manages global servers (available to every project); a project's own Extensions section manages servers scoped to that one project, and global entries are active there too. See "Custom MCP servers" below for how the add and edit form works, since the two scopes share the same surface.

Plugins. A pointer, not a management surface. Plugins are equipped per project on each project's Extensions section, so this global part simply directs you there. A global plugin overview will arrive in a later update.

Custom MCP servers

An MCP server extends what your agents can do by exposing extra tools over the Model Context Protocol. Each entry is a card showing its name, a transport badge (HTTP or Stdio), a scope pill (Global or This project), the command or URL, the agents allowed to use it, and any environment variable key names (values are always masked and never shown).

• Add MCP Server opens a form. Pick a transport: Stdio (a local subprocess, so you give a command and its arguments) or HTTP (a remote server, so you give a URL). Name it, choose which agents (Claude, Codex, Gemini) may use it, and optionally add environment variables (for secrets or config). Environment values are stored but never displayed back.
• Edit reopens the same form for an existing server.
• Remove asks for an inline confirm before deleting the server.

Notifications

Notifications are coming soon. This section shows a single "Coming soon" note today; choosing what Castforge tells you about, and where, arrives in a later release.

Privacy & data

Your telemetry and data-consent controls, including a telemetry consent toggle and links to data and legal information.

About

App information and links:

• The Castforge wordmark, tagline, and your installed version.
• Check for updates.
• Resource links: Documentation, Community, Changelog, Send feedback.
• Legal links: Privacy policy and Terms of service (open on castforge.ai).

Project settings (per project)

Open a project and go to its settings to find these sections. Everything here affects only the open project. The sidebar has five sections, in order:

1. General
2. Behavior
3. Team & roles
4. Extensions
5. Data & danger

The redesign consolidated the former project tabs into these five. The old Plan source and Collaborators tabs are now stacked inside General; the fake per-project Permissions grid was replaced by the real Behavior section; the old Data and Activity tabs are stacked inside Data & danger; per-project MCP servers and Plugins now live together under Extensions; and the old Agents & roles tab is now Team & roles. Old bookmarks to the retired tab addresses redirect to the right section.

(In the current beta build the Collaborators part of General is hidden. Collaboration is coming soon: inviting teammates to a project arrives in a later release.)

Project settings save automatically. There is no Save button on most surfaces; changes are written as you make them, with an auto-save hint in the header.

General

The General section stacks the project's core settings: metadata and plan source (plus collaborators, which is beta-hidden).

About this project. Project metadata. Click Edit on a field to change it, Esc to cancel.

Plan source. Choose the planner that drives this project's Course (the board of phases). Options: Manual, Roadmap auto-detect, Markdown, Linear, GitHub, Notion. Manual and Roadmap auto-detect are live and selectable. Markdown, Linear, GitHub, and Notion are shown but not selectable (they are marked "Stub" and arrive in a later release), so you cannot strand a project on a planner that does nothing yet. If you switch between the live sources while a Course already has phases, Castforge asks whether to keep, merge, or replace them.

There is no longer a per-project Permissions grid in General. The controls that actually govern what the project may do live on the Behavior section below.

Behavior

The Behavior section owns the enforced controls for how the project's agents act. It replaces the old per-project Permissions grid (a set of switches that were written but never read). Behavior ships three controls plus a plain-language consent note.

Permission level (Careful, Balanced, Autonomous): how often agents pause to ask you.

• Careful asks before commands and risky actions. Shell commands, network access, and anything reaching outside your project folder stop and ask. File edits inside your project folder are applied as the agent works, at every level and on every agent, and every one is recorded so you can roll it back with /undo.
• Balanced asks only for product decisions, and for anything on the sensitive list.
• Autonomous shows no permission prompts at all.

What Autonomous grants, stated plainly. Since 2026-08-05, a project on Autonomous asks you nothing. An agent working in it can read any file your user account can read, including your SSH keys, your saved cloud credentials, and your AI CLIs' own sign-in folders, and it can send what it reads out over the network. It can deploy to production, migrate a database, publish a package, and buy a domain, with no confirmation at any point. It can also start new milestones on your board without showing you the proposed structure first.

Castforge still evaluates every one of those checks and still writes an audit line for each, so an unattended run can be reconstructed afterwards. It simply does not stop. That trade was made deliberately: an explicitly autonomous run was stopping several times an hour for things nobody wanted to be asked about, and a stream of prompts you dismiss without reading is not a safeguard.

Autonomous means "run this project unattended, including the parts I would normally want to approve." If you want the second half of that sentence back, use Balanced: it auto-approves routine file edits and shell commands and still stops for everything on the sensitive list. Balanced is the right setting for most long runs.

Careful and Balanced are unchanged by all of the above, and were measured to be unchanged rather than assumed. On Careful you are asked before every command, reads included. On Balanced, reading is not an interruption: web search, fetching a page, reading a file inside your project, and searching your project's files run without a prompt, while anything reaching a sensitive location still asks.

A few things can still hold an Autonomous run, and none of them is a permission decision: a genuine design question from the role that plans your work, a boundary you set by hand ("do not plan yet"), a scheduling conflict with another running project, the one-time switch to Autonomous itself, and the rollback buttons you press yourself on the board. See "Working in a project" for the full list.

On Careful and Balanced, this boundary holds whether or not the project is open on screen. Previously, opening a project could answer a waiting prompt for you: the app decided in one place that an action needed your approval, then the project view approved it anyway. If you saw a run appear stuck on Mission Control and then "unstick" the moment you opened the project, that was this bug. The gate was real, and opening the view was pressing the button. It no longer does that, so a run held on one of these actions waits for a real answer from you. On Autonomous the prompt is answered for you immediately and deliberately, which is the setting working as intended rather than that bug returning.

Escalating to Autonomous confirms once, then applies to this project going forward. The deploy target below is a separate gate and Autonomous does not unlock it: a project set to Local still refuses cloud actions at every permission level.

A project's own level always wins, and applies only once it has loaded. Your account-wide "Default permission level" decides what a NEW project starts on. It is not a fallback for a project whose own setting Castforge has not read yet: in that brief window, and in the rarer case where the setting fails to load at all, the project is treated as Careful and you are asked. So an Autonomous project can ask you about something in the first moments after you open it. See "An Autonomous project is asking me for approvals" in Recovery and troubleshooting.

Deploy target (Local only, Web): where this project is allowed to ship.

• Local keeps everything on your machine with no cloud accounts and blocks cloud actions (Vercel, Supabase, domains, publish).
• Web lets the team deploy to your own Vercel and Supabase.

Changing the deploy target updates the capability gate and the Lead's charter; it does not rewrite existing code.

Parallel execution (On, Off): whether independent board cards run at the same time.

• On (the default) lets independent ready cards run concurrently, each in its own isolated workspace, up to a small per-project limit. Review and merge stay in order, so nothing lands unreviewed.
• Off runs the classic one card at a time through the queue.

Maximum lanes (1, 2, or 3): how many independent cards may run at once when parallel execution is On. The default is 2 and the most is 3. Set it to 1 to keep parallel review order but run one card at a time; raise it to 3 to fan out wider. Higher lane counts use more of your provider limit at the same time. This control has no effect when parallel execution is Off, and Castforge never runs more than 3 agents at once no matter what you pick.

The change takes effect on the next task the dispatcher starts. See "The board" for the full explanation of how parallel runs stay safe.

Continue past milestone boundaries (On, Off): whether a run may roll straight from one milestone into the next on its own. The default is Off, which pauses the run for your review when it finishes a milestone and the next one is ready, a natural checkpoint before the team moves on to a new workload. Turn it On to let auto-advance cross the boundary without stopping. This only affects the jump between milestones; moving from one phase to the next inside a milestone is automatic either way. The engine re-reads this at every continuation, so a change applies at the next boundary the run reaches. See "The board" for how milestones and boundary pauses work.

Model preferences (per agent, per tier): the same "Customize models per agent" block as the account default, scoped to this project. It overrides your account default here, and adds a "Overrides your account default for this project" note. Each set tier gets a Reset to account default, and a whole agent can be reset back to the account default in one click. A tier left unset at the project level falls through to your account default; if that is unset too, a Claude tier uses its built-in alias default (the Claude CLI runs the newest version of that model) and any other agent runs on its CLI's own default model. Setting a Top preference takes effect even under the default Max strategy. Leaving everything unset changes nothing. See "Your AI dev team" for tiers and the full precedence order.

Team & roles

Configure the team that works on this project (this section was formerly labeled "Agents & roles"):

• Team preset: pick Solo, Pair, Trio, or Custom to seed roles and handoff rules. Seats are seeded onto an agent you have actually connected, so the team is runnable right away. Editing any seat flips the preset to Custom.
• The team: the role pipeline. Add, remove, or reconfigure roles and their agents and plugins. Each seat has its own agent and an optional model picker (leave it on Default and Castforge sends no model, so the agent's CLI uses its own account default; or pick a specific model from that agent's catalog).
• Role charters: each role's base identity. Edits apply at the next spawn; leave blank to use the built-in default.
• Handoff rules: how work passes from one role to the next. This includes the off-by-default Roles can request follow-up work through the Lead rule; when on, any role can flag extra work mid-run and the Lead accepts or rejects it. See "Your AI dev team" for how that adjudication works.
• How they work together: a diagram of the flow.

Plugins are equipped here too, as toggleable chips on each seat. A badge on this section shows how many roles the project has. See "Your AI dev team" for the full walkthrough.

Extensions

The per-project Extensions section stacks the project's MCP servers and its plugin assignment.

MCP servers. Register custom MCP servers scoped to this project so its agents can call extra tools. Global MCP servers (from App Settings) are active here as well. The add and edit form is the same one described under "Custom MCP servers" in App Settings: pick a transport (Stdio or HTTP), name the server, choose which agents may use it, and optionally add environment variables (values are always masked).

Plugins. Assign plugins to this project's roles. This is where plugins are actually equipped; the global Extensions section only points you here.

Model and quality controls

Castforge scales how much model firepower and how many review gates a project uses. These controls are per project and are set in the places noted below (they are not a separate settings tab):

• Quality tier (Draft, Standard, Max): chosen when you create a project (on the wizard's Setup step) and stored on the project. It decides which review gates run (Draft is fastest and skips the heavier gates; Standard adds plan-check and verification; Max runs the full stack including research) and sets the expected cost band. A pre-run notice in the workspace shows the band for the active tier. See "Quality and review gates" for detail.
• Model strategy (Max, Smart, Economy, and the two + Alloy variants): a per-project control in the workspace side rail. Smart is the default and matches cheaper models to simpler tasks while keeping a quality floor on the Coder, Reviewer, and Designer, so new projects save tokens out of the box; Economy tiers more aggressively without that floor; Max always uses the top model (pick it when you want maximum quality regardless of cost); the Alloy variants also rotate providers across cards when two or more agents are connected (and fall back to the base strategy when only one is). Smart maps tiers to Claude's opus, sonnet, and haiku aliases and the Claude CLI runs the newest version of each; every other agent runs on its CLI's own default model unless you set a model preference for that tier, so you are never forced onto a model your account does not support. Projects created before this change keep whatever strategy they already had. If a selected or tiered model turns out to be unavailable on the connected account, Castforge shows a notice on the failed step, retries it automatically with the account's default model, and skips that model for the rest of the app session; reconnecting that agent clears the skip and allows one fresh attempt.
• Per-seat model: set on the Team & roles section, as above, so each role can run a different model.
• Per-task model tier: on the Course board, an individual card can carry a model tier (for example Top, Mid, or Cheap), set when you add the card or later from the card's right-click Set model tier menu. The card shows a small tier badge.

Data & danger

The Data & danger section stacks the destructive project actions, the project's data management, and its activity history.

Danger actions. Each is behind a type-to-confirm step:

Data. Storage and data management for the project:

• Storage: a breakdown of disk space the project uses, with a Refresh button.
• Cloud sync: Enable cloud sync (marked Coming soon). Your files stay on disk for now.

Castforge trims its own history in the background, about once an hour, so its database cannot grow without limit. Old chat messages age out, and the internal activity record is bounded two ways: routine entries age out on the same schedule, and any single kind of entry keeps only its most recent entries per project. That second bound matters when something goes wrong in a loop and records the same diagnostic thousands of times a minute: the record of what happened is kept, the endless repeats are not. Decisions, phase and milestone changes, and run history are never trimmed. Trimming pauses while agents are running, so it never competes with your work.

Activity. A record of actions taken on this project. (This was formerly the standalone Activity tab; it now lives here alongside Data and the Danger actions.)

The project's default branch is set under General (in the About this project fields), so editors, terminals, and agents all use the same branch.

Global vs per-project at a glance

Global (App Settings), seven sections:

Per project, five sections:

Quality tier and model strategy are also per project, but they are set on the project wizard and the workspace side rail rather than a settings section (see "Model and quality controls" above).

Where settings are stored

Most look-and-feel preferences (theme, accent, density, sidebar), the new-project defaults (default permission level and default deploy mode), and your account-level model preferences are stored locally on your machine and survive restarts. A project's own model preferences (its per-agent tier overrides) are stored with the project. Conversation style and notification preferences are saved to your local Castforge data. Project settings, including each project's permission level, its deploy target, its quality tier, and its model strategy, are stored with the project. There is no longer a per-project fine-grained permissions record; the enforced values are the permission level and the deploy target on the Behavior section. The project's default branch is written into the project's own git configuration. Custom MCP server definitions are stored per scope (global entries app-wide, project entries with the project); MCP environment values are stored but never displayed back. Today these settings live on your device; cloud sync of project data is a planned future feature, marked Coming soon under the Data & danger section's Data controls.