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.

Project type. A convenience row that changes the type (Web app or Unreal Engine) of the project you currently have open. It acts on the foreground project; if no project is open the row tells you to open one. Changing it re-routes the preview surface right away, with no reload and no confirm. A Web app opens to the live web Preview; an Unreal Engine project opens to the Unreal panel. (The full, enforced deploy target and permission level for a single project live on that project's Behavior section, described below.)

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 alpha 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 alpha-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 exactly two controls plus a plain-language consent note.

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

• Careful asks before every action.
• Balanced asks only for product decisions.
• Autonomous runs without asking.

Escalating to Autonomous confirms once, then applies to this project going forward.

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.

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. 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 to use the agent's default model, 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.
• 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. Max always uses the top model (the default); Smart and Economy match cheaper models to simpler tasks; 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).
• 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.

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) and the new-project defaults (default permission level and default deploy mode) are stored locally on your machine and survive restarts. 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.