Skip to content

feat(agents): custom CLI agent profiles (#1473) - #1479

Closed
nwparker wants to merge 1 commit into
mainfrom
nwparker/https-github.com-stablyai-orca-issues-1473
Closed

nwparker wants to merge 1 commit into
mainfrom
nwparker/https-github.com-stablyai-orca-issues-1473

Conversation

@nwparker

@nwparker nwparker commented May 6, 2026 •

Copy link
Copy Markdown
Contributor

Closes #1473.

What

Adds user-defined CLI agent profiles — named variants of a built-in TuiAgent with their own launch command and optional env vars. The motivating ask in #1473 was "two Claudes pointed at different provider URLs"; this lands a general mechanism for that and similar workflows (custom Codex with separate OPENAI_API_BASE, Claude with --dangerously-skip-permissions baked in, etc.).

Where it surfaces

  • Settings → Agents — new Custom Agents section with add/edit/delete, base-agent picker, command field, and env key/value pairs. Each profile gets a "Set as default" affordance.
  • Default Agent picker in Settings → Agents and in the workspace composer — custom profiles render as additional pills/items with the base agent's icon plus a wrench overlay.
  • New Workspace composer (full + quick) — the agent combobox lists custom profiles inline; selecting one routes the launch through the profile's command + env.
  • Tab-bar Quick Launch — custom profiles whose baseAgent is detected on PATH appear in the launch dropdown.

How it's wired

  • New CustomAgentProfile = { id, label, baseAgent: TuiAgent, command, env? } in src/shared/types.ts.
  • GlobalSettings.customAgents: CustomAgentProfile[] (default []).
  • GlobalSettings.defaultTuiAgent widens to accept { kind: 'custom', id }. Stale custom defaults fall back to auto, matching how uninstalled built-ins fall back.
  • buildAgentStartupPlan / buildAgentDraftLaunchPlan accept an optional customProfile; when present, the launch base command comes from the profile (with env rendered as a POSIX shell prefix KEY='value' …) instead of cmdOverrides[agent] ?? config.launchCmd. The base agent still drives prompt-injection mode, telemetry kind, and paste-draft logic, so custom agents ride the existing flow with zero downstream changes.
  • Env shell prefix piggybacks on the existing startup-command path (local-pty-shell-ready.ts writes startup commands to the user's interactive shell) — no PTY-spawn changes needed.
  • New helpers: src/shared/custom-agent-profile.ts (env quoting + base command), src/renderer/src/lib/custom-agent-resolve.ts (lookup + default-pref resolver).

Selection model

Composer state stays minimal: tuiAgent: TuiAgent + customAgentId: string | null (parallel slots). When the user selects a custom profile, the picker sets tuiAgent to its baseAgent and records the profile id, so existing call sites that only know about TuiAgent (telemetry, paste-draft, trust preflight) continue to work unchanged.

Tests

  • src/shared/custom-agent-profile.test.ts (new) — POSIX/Windows env quoting, single-quote escaping, command resolution.
  • src/renderer/src/lib/tui-agent-startup.test.ts — added cases for both buildAgentStartupPlan and buildAgentDraftLaunchPlan with a custom profile (incl. that profile command + env override the per-agent cmdOverrides).

npm run typecheck clean. npm run lint clean (0 errors; 7 pre-existing warnings untouched). Vitest passes for everything except the pre-existing better-sqlite3 native-module mismatch in orchestration/runtime tests (failing identically on master).

Notes / out of scope

  • Env shell-prefix uses POSIX quoting; on Windows the settings hint advises wrapping with cmd /c … if env vars matter. A first-class Windows path can come later.
  • Migration: customAgents defaults to []; existing users keep working unchanged until they explicitly pick a custom profile.

Made with Orca 🐋

Risk: high
Historic risk metadata backfill based on the existing risk:high label.

Adds user-defined CLI agent profiles \u2014 named variants of a built-in
TuiAgent with their own launch command and optional env vars. Surfaced
in the agent picker (new-workspace composer + tab-bar quick launch)
alongside built-ins, and in Settings \u2192 Agents with add/edit/delete.

A profile inherits its baseAgent's prompt-injection mode, icon, trust
preflight, and telemetry kind, so the existing launch flow handles
custom agents without a parallel code path. Env vars render as a POSIX
shell prefix (`KEY='value' \u2026`) on the launch command, leveraging the
existing shell-evaluated startup-command path \u2014 no PTY-spawn changes.

defaultTuiAgent widens to also accept { kind: 'custom', id }; a stale
custom default falls back to auto-pick (matches uninstalled-builtin
behavior). Quick-launch dropdown only surfaces custom profiles whose
baseAgent is detected on PATH so the menu can't recommend a stalled
launch.

Co-authored-by: Orca <help@stably.ai>
@nwparker nwparker added the risk:high High risk change label May 30, 2026
@nwparker

Copy link
Copy Markdown
Contributor Author

PR closer pass: leaving this open and unmerged.\n\nCurrent evidence:\n- GitHub reports this PR as dirty, and git merge-tree --write-tree origin/main refs/tmp/pr-1479 conflicts across the agent settings/composer/quick-launch path, including AgentsPane.tsx, AgentCombobox.tsx, both new-workspace composer surfaces, QuickLaunchButton.tsx, useComposerState.ts, launch helpers, tui-agent-startup.ts, settings/store slices, constants.ts, and types.ts.\n- The only current check rollup item is track-community-pr; there is no current verify success on this head.\n- The feature is still high risk: it introduces custom CLI agent profiles, command/env handling, default-agent expansion, and multiple UI launch surfaces.\n\nNot stale because custom agent profiles are not present on current main, but it needs a fresh design/rebase pass, current type/lint/unit validation, and interactive UI proof before risk-lowering or merge.

@BorjaLL

BorjaLL commented Jun 10, 2026

Copy link
Copy Markdown
Contributor

Hey @nwparker, I really liked this feature so I rebased it onto current main (it was ~3k commits behind), fixed up the spots that had drifted in the integration, and also wired custom agents into Automations. It's on my fork at BorjaLL:BorjaLL/custom-agent. Happy to either open a fresh PR that supersedes this one, or push my commits onto your branch, whichever you prefer. Thanks for the original work!

@AmethystLiang

Copy link
Copy Markdown
Contributor

Thanks for this work — we took inspiration from it and will land the custom-agent implementation in #8337. Closing this PR in favor of that work.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:high High risk change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: Can't add custom cli agent

3 participants