Projects: set a default agent per project #9393

Activity

1. github-actions commented on Nov 5, 2026

   

   github-actionsBot

   on Nov 5, 2026 – with GitHub Actions

   Contributor

   More actions

   I've finished looking through the code and am writing up the triage comment.

   Summary

   This is a feature request, not a bug. The reporter wants each project to have its own default agent, so new workspaces, chats and automations in that project start with it. Today they pick the agent by hand each time. The use case is keeping personal projects on a custom agent (for example a second Claude account via CLAUDE_CONFIG_DIR) and work projects on the native Claude agent. The proposal is a "Default agent" dropdown in project settings ("Use global default" or any configured agent) and an optional --default-agent flag on superset projects. I checked the code: there is no per-project agent setting today. The "global default" is not stored as a setting at all. It is the last agent picked, saved in renderer localStorage, and each launch surface saves it under its own key.

   How the agent is chosen today

   • apps/desktop/src/renderer/hooks/useAgentLaunchPreferences/useAgentLaunchPreferences.ts:37-71: the agent is the value stored under agentStorageKey in localStorage. If nothing is stored, it falls back to defaultAgent. If that agent is not available on the host, it uses fallbackAgent. Each pick is written back to the same key (:83-91). The hook can remember a selected project (projectStorageKey), but nothing links an agent to a project.
   • apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/NewWorkspaceScreen/NewWorkspaceScreen.tsx:601-608: the new-workspace screen passes selectableAgentIds[0] as the default. The key is lastSelectedV2WorkspaceCreateAgent (.../DashboardNewWorkspaceForm/PromptGroup/types.ts:5).
   • Other surfaces have their own separate keys: lastSelectedAgent (RunInWorkspacePopover.tsx:111), lastSelectedV2TaskBatchAgent (RunInWorkspacePopoverV2.tsx:41), lastSelectedV2IssueBatchAgent (RunIssuesInWorkspacePopover.tsx:34), lastSelectedDiffCommentNewAgentConfigId (AgentSessionPicker/hooks/useAgentSessionTarget/useAgentSessionTarget.ts:24).
   • Automations save an explicit agent per automation (packages/db/src/schema/schema.ts:1708), so a project default would only fill in the create form.

   Where a per-project setting would fit

   The host-service projects table already holds per-project overrides where null means "use the host-wide default". branchPrefixMode/branchPrefixCustom and namingInstructions are examples (packages/host-service/src/db/schema.ts:97-113). Each has a setter and is returned by the project getter (packages/host-service/src/trpc/router/project/project.ts:232-249, setNamingInstructions at :353-381, setBranchPrefix at :419+). The settings UI for these is apps/desktop/src/renderer/routes/_authenticated/settings/v2-project/$projectId/components/V2ProjectSettings/components/V2ProjectSettingsBody/V2ProjectSettingsBody.tsx. The CLI project commands are in packages/cli/src/commands/projects/{create,setup,list}/command.ts, and none of them take an agent option.

   Suggested direction

   1. Add a nullable default_agent column to the host-service projects table, using the same pattern as branchPrefixMode. Return it from the project getter and add a setDefaultAgent procedure. Follow packages/trpc/AGENTS.md: this is an additive field and procedure, so released clients keep working. Store the agent's id (the id in useV2AgentChoices), so custom agents work as well as built-in presets.
   2. In useAgentLaunchPreferences, accept an optional projectDefaultAgent. When the selected project has one, use it before the localStorage value. The open design question is whether a manual pick should still be remembered across projects, or only within the current launch. Either way, the project default should apply again when the user changes project. Pass it in from NewWorkspaceScreen, the task/issue run popovers, the new-chat entry points and the automation create form.
   3. If the agent is not available on the target host, keep the current fallbackAgent behaviour. Showing a hint would help.
   4. Add a "Default agent" select to V2ProjectSettingsBody, with Lingui strings and translations through bun run check:i18n. Add a --default-agent option to projects create/setup, or a new projects update command.
   5. Since this is a host-side SQLite column, store it there rather than in a new localStorage key. That fits the persisted-state policy in apps/desktop/AGENTS.md.

   Test sketch: a bun:test for useAgentLaunchPreferences, next to the existing useAgentLaunchPreferences.test.ts. With a stored global pick of claude and projectDefaultAgent: "custom-1", selectedAgent should be "custom-1". With projectDefaultAgent set to null, it should be "claude". If "custom-1" is not in validAgents, it should be fallbackAgent.

   Related: #8104 / PR #8005 pin the account per project. A default agent would also cover custom and non-Claude agents, so the two settings could sit side by side in project settings.