Configuration

Use Settings for application preferences and connections. Open a project’s Repository tools for verification, history and services. Use .codeflow/config.json for committed repository defaults.

Application settings

Open Settings at the bottom of the sidebar, press ⌘, / Ctrl+,, or search for a settings category in the command palette. Categories have shareable addresses such as #/settings/ssh; browser Back and Forward preserve navigation. Search settings by a feature name such as “theme”, “permissions”, “VM”, or “Tailscale”.

• General: light, dark, or system appearance; sidebar grouping; archived runs; keyboard shortcuts. Terminals follow the selected appearance.
• Agents & models: provider health and usage, model and effort defaults. Sign in through the provider CLI on the current machine.
• Run defaults: workflow, plan approval, agent permissions and run limits. These update the composer’s remembered choices and the current draft; running work is unchanged. Project defaults and per-role choices can override model preferences.
• Notifications: browser notifications and outbound notification destinations.
• SSH connections: save and open remote VMs, with optional port and identity-file overrides. See SSH projects.
• Remote access: Tailscale, Wi-Fi, pairing and device access to the local workspace.
• Team: connect this computer to a team server as a runner and map repository keys to local clones; on the team server, define each project's repository keys and the owner's display name, read the https:// address teammates connect to and revoke runners. See Team collaboration.
• Integrations: guided service setup and connection management; each project has its own Connections tab. Existing environment-based integrations remain administrator-managed under Advanced.
• Projects & access, Extensions, Data & storage: project conventions, filesystem policies, shared accounts, extensions and retention controls.
• Advanced: collect/export diagnostics and find the server configuration reference. Process-level settings and credentials remain environment configuration and require a restart.

Appearance, run defaults and sidebar preferences save in this browser, separately for each SSH workspace. SSH definitions and the team link with its repository mappings save on the local server; project, access, notification and retention settings save on the machine hosting that workspace; team board tasks, checkpoints and runner registrations save on the team server the link points to. Controls with a Save action keep their existing explicit save behavior. Numeric run limits save when you leave the field; invalid values restore the previous setting.

Project → Repository tools contains verification, code editing, dependency and context inspection, checkpoints, services, coordinated changes and filtered tasks. Inbox and Automations are sidebar destinations. Open Insights and the workspace from the application menu or command palette. Older Settings URLs redirect to the current destinations.

Per-repo config

Commit .codeflow/config.json and every run in that repo (and every teammate) gets the same defaults. Anything you set in the UI wins.

{
  "check": "npm test",
  "setup": "npm ci",
  "copy": [".env", ".env.local", "config/*.local.json"],
  "run": { "command": "npm run dev", "port": 3000 },
  "models": { "claude": { "model": "opus", "effort": "high" } },
  "limits": { "maxMinutes": 90, "maxSteps": 60, "checkTimeoutMin": 25 },
  "trust": "standard",
  "image": "node:22",
  "learn": true,
  "prove": true
}

• check and setup: the composer suggests both from the repo (see Checks), but set them here when the guess is wrong. A uv workspace whose tests live in their own member might use:

  { "setup": "uv sync --all-packages", "check": "cd tests && uv run --no-sync pytest -q" }
  

  Setup runs once per worktree outside the agents' sandboxes, so the check can run without network (--no-sync). When a run's check can't run at all (not installed, nothing collected, conftest.py can't import the project), the run says so and asks you to set these.

• copy brings files git doesn't carry (like .env) from your checkout into every new worktree. Only regular files that git ignores are copied. Symlinks are refused, since a cloned repo's .env could point at your credentials, and so are files git would commit. Patterns can't reach outside the repo, and nothing is copied through a symlink in the worktree.

  • Copied files are never committed, even when an agent un-ignores one or runs git add -f. Neither are new files named like secrets (.env, .env.* other than .env.example, .env.sample and .env.template, *.pem, id_rsa*, id_ed25519*). They stay in the worktree, and a warning names what was left out. Commit such a file yourself if it belongs in the repo.

• image is the Docker image for running checks in isolation (automations, untrusted sources). learn passes recurring review problems on to later runs. prove checks that each passing result has a test that fails without it (fail-to-pass); set it to false when the check is too slow to run twice.

• A result's worktree that was removed (archived) is set up again when you follow up on it: files copied, setup run, context restored, and the files you sent with the follow-up added. If its branch was deleted, that follow-up fails with a clear message; the run itself stays finished. A follow-up also fails, rather than delete anything, when the worktree's folder is there but holds something else: move that folder away, then send it again.

• Try it: each result has Terminal, Editor (Cursor, VS Code, Zed or Sublime, whichever is installed) and Folder buttons that open its worktree, plus ▶ Run app.

  • Run app starts your dev server in the worktree on a free port (passed as $PORT), with logs and Stop app. Servers stop when the run is archived or code-flow shuts down.

What agents may do while building

Settings → Run defaults → Agent permissions:

Full access turns every agent's sandbox off in steps that build: an agent can run anything, use the network, and change files outside its worktree with your credentials. Use it only on repos and tasks you trust completely. To keep it a choice you make:

• It's picked per run in the composer, which warns while it's on, and the run shows ⚠ full access. A repo's .codeflow/config.json can't turn it on: "trust": "full" there is ignored.
• Planning, reviewing and judging steps stay read-only, as in every mode.
• Runs nobody watches get less: automations and sweeps run with Trusted, and fixes for watched pull requests with Standard.
• A run started from someone outside the repo is locked down to Safe whatever you picked (see Untrusted text).

Whatever the mode, code-flow never merges or pushes on its own.

Models

Per provider in Settings → Agents & models, and per role right under each role's agents in the team. See Getting started.

Light or dark

code-flow follows your system’s appearance until you choose Light or Dark in Settings → General. The pick is kept in that browser, and a side panel popped out into its own window follows it.

Health

Click the agent dots at the bottom of the sidebar to see, for each CLI, whether it's installed, its version, and whether it's signed in. It uses claude auth status, codex login status, and for agy whether it can list models; credentials are never read. Claude's 5-hour and 7-day usage windows are shown from its own reports, with how to fix anything that's wrong. A run won't start with an agent that's signed out, and Auto skips an agent that turned out to be signed out for 15 minutes. If agy can't reach its servers, its sign-in shows as unknown rather than signed out.

Health also checks that each installed CLI still accepts the flags and subcommands code-flow passes (from its --help), and warns when one is missing: after a CLI update, that's the difference between "healthy" and every step failing on an unknown option. It also checks for git 2.38 or newer, which Merge needs.

Once an agent CLI reports its final result, it gets 10 seconds to exit; one that's still running then (a hook or MCP server that hangs on shutdown) is stopped and its result kept. A single output line over 16 MB is skipped, not read into memory.

Environment variables

A numeric setting that isn't a valid number (30m, say) or is out of range falls back to its default, with a warning in the terminal.

Child processes exclude the application API token, scoped team capabilities, integration/notification configuration and their registered server credential variables. They also exclude npm lifecycle variables about code-flow itself and its own dependency bin paths; your npm_config_* settings remain. A check's tools come from its repository. Explicit agent containers use a smaller environment and only their configured authentication volume; see container setup.

Files in ~/.codeflow

Dynamic teams

CODEFLOW_AUTO_TEAM_ENABLED=false disables new Auto team runs while preserving saved-run viewing and recovery. The rollout record and evaluation evidence are shown in Insights; the composer selects Auto initially only at the default stage when there is no saved workflow preference. The recorded stage is informational (and a composer default when set to default); only CODEFLOW_AUTO_TEAM_ENABLED changes whether new Auto runs can start. Existing runs without the eventDriven option retain dependency-wave replay; newly created Auto runs default it on.

The authenticated run API accepts loop.maxInvocations as an additional per-allocation ceiling on actual CLI launches, including retries. Auto already caps launches with its step budget. Follow-up requests can specify budget: { maxSteps, maxInvocations, maxMinutes }; the UI exposes this fresh allocation and retains lifetime usage.

Project memory is in memory.sqlite, with automatic verified import from memory.json, indexed keyword search and a lightweight knowledge graph. See Memory storage for migration, rollback, runtime requirements and backup behavior. Evaluation reports and the explicit rollout decision still use durable replacement files under the evaluation store in CODEFLOW_HOME. See Auto team for scope, trust, revision and deletion semantics.

Project missions

Click Enable project missions on a project page to enable the feature immediately and save the choice for this host across restarts. CODEFLOW_PROJECT_TEAMS_ENABLED=true is an optional initial default; a saved UI choice takes precedence. CODEFLOW_AUTO_TEAM_ENABLED must also permit Auto team execution. Each team is separately activated by its owner. Schedules, budgets, missions, recovery and provider limits are described in Project missions.

Documentation library · Getting started · Local app help