Project Settings

Every project has its own per-project settings modal, accessible from the ⋯ menu next to the project name in the sidebar. Unlike the global Settings panel, these overrides only apply to a single project.

The modal lives at apps/desktop/src/renderer/components/ProjectSettingsModal.tsx.

Fields

Editable

Read-only

Moving a repo folder

If you move the repo on disk, open Project Settings -> General -> Change folder… and point ShipCode at the new location. That updates projects.path without creating a duplicate project row.

Setup and runtime QA

The Setup tab edits the repo setup contract at .shipcode/setup.json. ShipCode reads that file in fresh worktrees before execution and verification.

{
  "version": 1,
  "setupCommands": ["<repo-specific install command>"],
  "verifyCommands": [
    "<repo-specific scoped verify command>"
  ],
  "runtimeQa": {
    "server": {
      "command": "<repo-specific dev server command using $PORT>",
      "readinessUrl": "http://127.0.0.1:$PORT",
      "startupTimeoutMs": 60000,
      "portEnvVar": "PORT"
    },
    "testCommands": ["<repo-specific runtime test command>"],
    "discoverAgentTests": true
  },
  "envFiles": [{ "source": ".env.local", "required": true }],
  "setupBeforeVerify": false,
  "testingContext": "Explain the repo's test runner, scope rules, and expensive commands to avoid."
}

Project detection can prefill setup and verify commands from common repo profiles, including Node package managers, Turborepo, Xcode, SwiftPM, Rust, Go, Python, Ruby, Java, .NET, and PHP. Runtime QA starts the configured dev server inside the feature worktree, runs browser/E2E commands, and also supports generated visual QA when a PRD includes a ## QA State contract.

GitHub readiness

The GitHub tab checks and repairs ShipCode-owned labels, validates GitHub issue types and Projects fields, and maps ShipCode columns to your GitHub Projects v2 Status field. Label sync is automatic for missing ShipCode labels; domain metadata such as priority, complexity, blast radius, and product taxonomy stays in GitHub issue types and Projects fields.

Memory and context

The Context tab shows repo memory files and the generator CLI used to keep them current. This is separate from runtime skills: repo memory guides agents building or modifying the project, while runtime skills drive pipeline prompts.

Override Hierarchy

Project Settings sits between the global Settings panel and the issue-level overrides.

• Planner / Reviewer / Verifier: global settings -> project override
• Executor: global settings -> project override -> issue override
• Human approval: app default -> project override -> issue override
• Revisions: app default -> project override -> issue override
• Speed profile and PRD quality gate: app/project defaults -> project override

Inherit means the project stores null for that field and falls back to the app default.

Effort options are provider-specific:

• Claude CLI: none, medium, high
• Codex: low, medium, high, xhigh
• OpenRouter: none, minimal, low, medium, high, xhigh

If an older stored effort is not exact for the chosen provider, the UI surfaces the fallback mapping explicitly.

Issue Detail can still override human approval, revisions, and phase models for a single issue when one task needs a different workflow than the rest of the repo.

Why the GitHub Projects v2 URL exists

GitHub Projects v2 boards live under a user or org, but GitHub exposes the boards associated with each repository. When you add a folder or refresh its board, ShipCode reads that association and stores the only open board automatically. If several open boards are associated, ShipCode selects the unique board whose title matches the repository name.

If no board is associated or several candidates remain ambiguous, paste the intended board URL into this field. A configured URL lets ShipCode sync cached issues to the board, detect the Status field, map columns, run readiness checks, and show the Kanban board button. A manual URL remains authoritative until you clear it; clearing allows auto-detection to run again on the next refresh.

Accepted URL formats

The field accepts all three canonical Projects v2 URL shapes:

• https://github.com/orgs/<org>/projects/<number> — org-scoped
• https://github.com/users/<user>/projects/<number> — user-scoped
• https://github.com/<owner>/<repo>/projects/<number> — repo-scoped classic

Validation is inline on blur — a bad URL shows a red border with a hint. Whitespace and empty strings are a valid clear — they hide the board button again.

The validator lives in packages/shared/src/github-url.ts.

Keyboard

• ⌘↩ / Ctrl+Enter — save and close
• Esc — close without saving
• Changes auto-focus back on the Kanban when the modal closes

Related

• Kanban Board — the board quick-link that this modal controls
• Settings — global settings not covered here