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 six sections, in order:

1. General (look and feel, new-project defaults, the keyboard-shortcuts pointer, and the Notifications status)
2. Account
3. Connections (connect your AI CLIs)
4. Extensions (the MCP server library and plugins)
5. Privacy & data
6. About

General

The General section (formerly called Preferences) holds the look-and-feel controls, the defaults new projects start on, a pointer to the keyboard-shortcuts reference, and a single line on where Notifications stands. Notifications no longer has its own section: it used to say the same "coming soon" thing three times over on a standalone tab, so it folds into one statement here instead.

Look and feel.

Themes and accents, and what the colors mean. Castforge ships two themes, Dark and Light, and three accents: Violet, Amber and Mint. The theme decides the canvas the app sits on. The accent decides the highlight Castforge uses for itself: the focus ring, the text you select, active controls and the brand mark.

Everything else on screen carries meaning, and each meaning has exactly one color:

Roles keep one hue each wherever they appear, so a Coder dot on a card, a Coder chip in the header and a Coder lane on the rail are all the same color: violet for Lead, lime for Coder, green for Reviewer, blue for Researcher, teal for Tester and pink for Designer.

The accent never wears a role's color or a status's color, on either theme. That is enforced at build time rather than left to care: a gate resolves every one of these tokens across both themes and all three accents and fails the build if two of them come out the same. It is why the Mint accent is a green you will not find on any card, and why picking Mint moves the focus ring to indigo instead of leaving it mint.

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.

For one agent (today, Codex), Castforge can check a picker's list against what that agent's own installed command-line tool actually reports. For every other agent it cannot make that comparison, and rather than showing a plain list with no caveat, the picker states in its own words why not, for example that an agent's whole configuration directory was checked and carries no separate model-catalog file at all. That matters because a model a provider has quietly retired can still be sitting in a list Castforge shipped and has not caught up to yet. Separately, wherever a curated model is one the installed tool no longer reports, the picker marks that row "No longer reported" before you pick it. The marking is a warning, not a lock: the row stays clickable, and choosing it is still yours to make.

See "Your AI dev team" for the full explanation of tiers and precedence.

Keyboard shortcuts. General shows a "Keyboard shortcuts" row with a "View all" link that opens the full reference, grouped by area (Global, Workspace, Composer, Palette, Navigation), on its own page. Custom rebinding is not available in this build.

Notifications. A single row states that notifications are coming soon, and that choosing what Castforge tells you about, and where, arrives in a later release. There is nothing to configure yet.

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 sidebar Connections page (in the app's main navigation, not inside Settings) is the one source for connecting your AI CLIs, API keys, and dev infrastructure. Each agent (Claude, Codex, Gemini, and the rest) shows a card there with its connection status and a connect or sign-in action that launches that CLI's own login. Settings, Connections (this section was formerly labeled "Agents") is a thin pointer to that same page, an Open Connections button, rather than a second copy of the same grid, so status lives in exactly one place. 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. Your MCP server library: the servers you have saved once so you can reuse them, plus the switch that decides which of them new projects get automatically. This part owns what a server is. It does not connect servers to projects; each project picks the ones it wants in its own Extensions section. See "The MCP server library" below.

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.

The MCP server library

An MCP server extends what your agents can do by exposing extra tools over the Model Context Protocol. The library is where a server is saved, once, and it is the only place a server is created or edited.

It has two doors onto the same surface: MCP servers in the app sidebar, in the Extend group between Connections and the plugin marketplace, and Settings, Extensions. Use whichever you reach first.

Each entry is a card showing its name, a transport badge (HTTP or Stdio), the command or URL, the agents allowed to use it, whether it connects to new projects by default, and any environment variable key names (values are always masked and never shown).

• Add MCP Server opens a form. If another MCP host gave you a block of JSON, paste it into Paste server config and click Fill from JSON; it accepts a bare server object or a wrapper keyed by server name, one server at a time. Otherwise fill it in yourself: 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; the value box is masked as you type and stays masked when you reopen the form).
• Connect to new projects by default is a switch on each server. On, and every project you create from then on arrives with that server already connected, through the new-project wizard, a template, or first-project onboarding alike. It applies going forward only, so turning it on never changes a project that already exists.
• Edit reopens the same form for an existing server. An edit here changes the server everywhere it is connected, which is the reason to keep definitions in one place.
• Remove asks for an inline confirm before deleting the server. Deleting it removes it from every project that had it connected.

What an agent can do here. Your agents can read this library and connect or disconnect one of its servers for the project they are working in, asking you to confirm first unless the project is on Autonomous. An agent cannot save a new server definition. That limit is deliberate, not an unfinished feature: a definition carries a command, its arguments and its environment, so anything that could write one could introduce a new subprocess into every project that later connects it. If an agent reports that the server you want is not in the library, save it here yourself and ask again.

Privacy & data

Your telemetry and data-consent controls, plus links to data and legal information. The Telemetry part holds three switches.

Crash reports and Product analytics are the first two. Both are off until you turn them on, and nothing is sent to either while they are off.

First run step counter is the third, and it is the one thing on this screen that is on by default. It records how far you got in setup, as a number, so we can see where new installs get stuck and fix the step that loses people.

It sends three things and nothing else:

• a step number, which is how far through setup you reached
• a version number for the setup steps, so that changing the steps later does not make the earlier numbers unreadable
• a random install id, created on your machine the first time you run Castforge

The install id is not your email, not your account, and nothing about your hardware. It is a random value whose only job is to tell one install apart from another.

If you are signed in when it sends, your account is recorded with it. Signed out, there is nothing to link it to, which is the common case while you are still setting up.

To turn it off, open Settings, then Privacy & data, and switch off First run step counter in the Telemetry section. It is separate from the two switches above it: turning it off leaves crash reports and product analytics exactly as they were, and turning either of those on does not change the counter.

About

App information and links:

• The Castforge wordmark, tagline, and your installed version.
• Version, Commit and Built: the full build identity, shown on every build. Commit is the short identifier of the exact build and Built is when it was compiled. Quote all three when you report a problem.
• 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. What a level can gate also depends on which agent is in the seat, because some agents decide for themselves what to raise: see "Permission modes" in "Working in a project".
• 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. Whatever roles they belong to, two ready cards that do not depend on each other run at the same time: a coder card and a designer card, or two coder cards. 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): the most independent cards that may run at once when parallel execution is On. The default is 2 and the most is 3. This is a ceiling rather than a target: what fills it is how many independent ready cards the board actually has, so a board with only one card ready runs one however high you set this. 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. Choose which of your saved MCP servers this project uses. It is a checklist over your MCP server library: tick a server to connect it to this project, untick it to disconnect it here and nowhere else. The server itself stays in the library, and other projects that have it connected are untouched. There is deliberately no add or edit form in this section, so a server has one owner rather than two; if the list is empty, save a server in the library first (MCP servers in the sidebar, or Settings, Extensions).

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. The workspace right rail shows the band for the active tier under Quality tier, just below the Model strategy control. 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. That notice and that automatic retry still apply to a model your command-line tool reported to Castforge: a tool listing a model is not the same thing as your account being able to run it. Where the tool itself marks a model as not supported in its own API, the picker shows a small "Not supported in API" marker on that row before you ever dispatch it. Read that marker as exactly what it says: it is the tool's API support flag, not a statement about what your subscription can run, and the model stays selectable.
• Per-seat model: set on the Team & roles section, as above, so each role can run a different model.
• Models reported by the installed CLI: the model picker shows Castforge's own curated list first, and then, beneath a heading that reads "Reported by the installed CLI", any additional models the agent's own command-line tool currently advertises on your machine. Those extra rows come from the tool itself, so a model your CLI has just started offering shows up without waiting for a Castforge update. Nothing in that section is ever selected for you: it is offered, and it only takes effect if you click it and save. If the tool has no way to list its models, the picker says so in a short line rather than showing an empty space, and today only the Codex CLI publishes a list Castforge can read. If the tool does publish a list and Castforge could not read it, the picker says so in that same short line and names what to do about it: run the tool once, then reopen the picker.
• Your agents can read the model list too: the same list you see in the picker is readable by the agents working on your project, so when you ask one why a model is missing or cannot be picked, it can look instead of guessing. The tool is read-only and never asks you to confirm: it reports the curated list, whatever the installed command-line tool currently advertises, where that list came from, when it was fetched, and which ids were dropped and why. For an agent whose models cannot be determined at all, it gets the written reason rather than an empty list. It selects nothing. It cannot pin a seat, set a tier preference, or change the model your project runs on, so the choice stays yours.
• 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, shown as a proportional bar plus a legend (SQLite, Thumbnails, Worktrees, and Other, each its own color) 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), six 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. MCP server definitions are stored once, app-wide, in your MCP server library, and each project stores only which of them it connects; MCP environment values are masked wherever they are shown. 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.