Skip to content

[Feature]: Allow users to add custom agent presets, not only override commands for built-in agents #2284

Description

@noname-oni

Problem or use case

The Agents settings page states: “Manage AI agents, set a default, and customize commands.” Currently, command customization only works for built-in agents. Users can override commands for agents like codex or claude, but cannot add new custom agents such as:

  • Codex Remote VM: codex-vm
  • Local wrapped Codex profile: codex --profile foo
  • Internal/company CLI agent: my-agent / third-party agents (e.g. Reasonix)
  • Multiple Claude Code (or other) accounts via env-isolated profiles (CLAUDE_CONFIG_DIR=…)
  • Any new CLI agent before Orca supports them natively

This limitation is significant because Orca’s launch model is command-based, with each agent represented by a terminal command. While the UI allows command overrides, the catalog and default agent system remain closed.

Current behavior:

  • TuiAgent is a fixed union in src/shared/types.ts.
  • TUI_AGENT_CONFIG is a fixed record in src/shared/tui-agent-config.ts.
  • AGENT_CATALOG is a fixed catalog in src/renderer/src/lib/agent-catalog.tsx.
  • Settings store agentCmdOverrides as a partial record keyed by TuiAgent.
  • The Agents pane renders only AGENT_CATALOG, so overrides apply only to known agents.
  • Provider list for automations/CLI is hardcoded (orca automations create --provider my-profile → Unknown provider).
  • agentCmdOverrides is global (no per-repo / per-automation scoping), not exposed in the CLI, and easy to misconfigure.

Thus, one can change “Codex” to run codex-vm, but cannot have both “Codex” and “Codex VM” as separate selectable agents. Multi-account users end up squatting on unused provider slots with PATH shims so the UI shows the wrong name, or launching profiles as plain terminals with no agent-session history.

Expected behavior:
Users should be able to create custom agent presets via Settings > Agents. A minimal preset should include:

  • label (e.g., Codex VM, Claude Work)
  • command (e.g., codex-vm, claude)
  • default args
  • environment variables (e.g. CLAUDE_CONFIG_DIR, provider URLs)
  • prompt injection mode (default stdin-after-start or configurable)
  • optional detect command (default first token)
  • optional icon or favicon
  • optional homepage or docs URL

Custom presets should appear alongside built-in agents in:

  • Default agent picker
  • Installed/custom agents list
  • Workspace / worktree agent picker
  • Quick launch surfaces
  • CLI (--agent / --provider)
  • Automations
  • Command override/edit UI
  • Agent session history (sessions from custom agents tracked like built-in ones)

Additional requirements (from #9933 and related reports)

  1. Env + multi-profile support — custom agents must carry an env map and default args so multi-account Claude Code setups (CLAUDE_CONFIG_DIR=~/.claude-work vs personal default) and env-based provider variants work as first-class agents, not PATH hacks.
  2. Click-to-launch + automation/CLI parity — registered custom agents are selectable everywhere built-ins are: launcher UI, CLI flags, automations create/dispatch.
  3. Session history parity — sessions started from custom agents (and ideally agents launched via terminal commands Orca recognizes) appear in agent session history.
  4. Per-repo scoping — different repos may need different accounts/profiles (client separation, billing, memory isolation). Prefer per-repo (and ideally per-automation) selection of which custom agent/profile is default.
  5. Optional: profile variants on built-ins — e.g. claude@work = the claude provider plus an env map, selectable per repo and per automation (alternative/additional to fully custom agent entries).

Why this fits Orca:
Orca already supports per-agent launch metadata via TuiAgentConfig and allows command overrides. The missing feature is persisting user-defined agents (command + args + env) and merging them with the built-in catalog, instead of requiring all agents to be compiled into TuiAgent.

Related: #9933 (merged into this issue), #1473, #7127. Docs already describe custom CLI agents; UI not yet shipped on stable.

Proposed solution

Add the following type:

type CustomTuiAgent = {
  id: string
  label: string
  command: string
  defaultArgs?: string[]
  env?: Record<string, string>
  detectCmd?: string
  expectedProcess?: string
  promptInjectionMode?: AgentPromptInjectionMode
  faviconDomain?: string
  homepageUrl?: string
}

Then store:

customTuiAgents: CustomTuiAgent[]
defaultTuiAgent: TuiAgent | CustomTuiAgentId | 'blank' | null
agentCmdOverrides: Record<string, string>
// plus per-repo / per-automation selection of agent id

Built-in and custom agents can be combined into a single runtime catalog before detection and launch planning. Custom agent ids must be accepted by automation/CLI provider resolution.

Current workaround

Override an existing built-in agent command (e.g. set Codex to codex-vm), or put a same-named shim on PATH that sets env and execs the real binary. Both replace or squat on a built-in slot instead of adding a new agent, and may leave automations on the stock command or hide runs from session history.

Alternatives or additional context

Concrete multi-account pattern users want (from #9933): point CLAUDE_CONFIG_DIR at different directories per profile so each carries its own auth, memory, and MCP credentials — then select those profiles as first-class agents in Orca.

Activity

  1. nwparker commented on May 29, 2026

    @nwparker
    Contributor

    Covered by PR #2521. I took over the PR, pushed focused fixes, and posted validation evidence here: #2521 (comment)

    Status: PR remains open with no GitHub checks reported and was not merged.

  2. added theissue type on Jul 12, 2026
  3. liuyifeng92 commented on Jul 13, 2026

    @liuyifeng92

    +1 for this feature.

    My concrete use case is Reasonix CLI, a third-party CLI coding agent that is
    not part of Orca’s built-in agent catalog.

    I would like to configure it from Settings → Agents → Add custom agent, as already described in the Orca documentation:

    https://www.onorca.dev/docs/agents/custom-cli

    A minimal configuration could include:

    • Display name, e.g. Reasonix
    • Binary path or command, e.g. reasonix
    • Default arguments
    • Environment variables
    • Optional startup hook
    • Optional detection command

    After saving, the custom agent should appear alongside built-in agents in:

    • The terminal agent combobox
    • The default agent picker
    • New workspace creation
    • Quick Launch
    • Automations, where applicable

    Currently, I can launch Reasonix manually from a blank terminal, but Orca does not treat it as a first-class agent. This
    means it has no dedicated name or entry in the agent picker, cannot be selected as the default agent, and cannot be
    configured or reused consistently across workspaces.

    I’m currently using Orca 1.4.137 on macOS. The documentation describes this workflow, but the “Add custom agent” button is
    not available in the current stable release.

    Supporting this would make Orca’s “works with any CLI agent” promise genuinely extensible, without requiring every third-
    party agent to be added to Orca’s built-in catalog.

  4. nwparker commented on Jul 13, 2026

    @nwparker
    Contributor

    We're working on it!

    Sorry for the doc-desync. We got a bit trigger happy.

  5. AmethystLiang commented on Jul 22, 2026

    @AmethystLiang
    Contributor

    Merged duplicate #9933 into this issue.

    New requirements folded into the description:

    1. Env + multi-profile — custom agents need env maps / default args for multi-account Claude Code (CLAUDE_CONFIG_DIR) and similar setups
    2. CLI + automation parity — custom agent ids accepted by --agent / --provider and automations (today the provider list is hardcoded)
    3. Session history parity — custom-agent sessions tracked like built-ins
    4. Per-repo scoping — different repos may default to different profiles/accounts
    5. Optional profile variants on built-ins (e.g. claude@work = provider + env map)

    Also linked the concrete workarounds users hit (PATH shims squatting provider slots, global agentCmdOverrides not covering automations cleanly).

  6. shengy3000 commented on Aug 6, 2026

    @shengy3000

    +1. Concretely, I just want a third-party agent CLI managed the way Codex is: sidebar entry, working/idle/done status, completion + mobile notifications, session history, and worktree auto-launch. Neither existing path gets there, and it's a mechanism gap, not a config gap:

    • Override a built-in slot only replaces the launch command. Detection stays keyed on the slot's hardcoded detectCmd (resolveDetectedTuiAgentIds over getTuiAgentDetectCommands, src/shared/tui-agent-detection-commands.ts), and process recognition stays keyed on its expectedProcess (src/shared/agent-process-recognition.ts). Neither is user-overridable, so the running agent is still detected/recognized as the built-in — wrong identity, wrong status attribution.
    • Quick Commands feeds a string into a terminal (TerminalCommandQuickCommand is just { command, appendEnter }, src/shared/types.ts). It launches the binary but creates no agent identity — none of the status/notification/history/auto-launch machinery that keys off a TuiAgent ever engages.

    So this is squarely (b) — an arbitrary third-party CLI as a first-class agent — not (a) a launch profile of a known agent. Profiles are the right model for (a), but (b) is a different agent, so it needs its own detection and process identity, not a variant of an existing one.

    That's exactly why the CustomTuiAgent shape proposed here is right, and why per-agent detectCmd + expectedProcess (alongside command/args/env) are the load-bearing fields: they're the two things that overriding a built-in slot can't give you, and the two things that make Orca detect, launch, recognize, and track a new agent end-to-end.

    +1 for keeping (b) in scope alongside (a).

  7. quessaer commented on Aug 21, 2026

    @quessaer

    A concrete launch-profile use case for this issue is a supervised Codex worker with MCP disabled, while keeping the primary/coordinator Codex session on its normal MCP-enabled configuration.

    Current local behavior checked with Orca 1.4.187 and Codex CLI 0.149.0:

    • orca orchestration worker-start --agent codex accepts per-invocation --model / --effort, but not Codex --profile, --config, or environment overrides.
    • Codex itself supports -p <profile> and -c mcp_servers.<name>.enabled=false.
    • Per-invocation MCP overrides work without mutating the normal Codex configuration.
    • The low-level workaround (terminal create --command "codex -p worker-no-mcp" followed by dispatch/attach) weakens the normal one-call launch receipt and can become unsupervised, so it is not a good default for orchestrated workers.

    The desired shape is a named launch variant of the built-in Codex identity, for example:

    • Codex — normal primary/coordinator session, MCP enabled
    • Codex: Worker (No MCP) — same Codex identity and account, but launched with a dedicated profile/default args that disable MCP

    This aligns with the built-in launch-profile direction discussed in #2521 rather than treating the variant as a fundamentally different agent.

    For the orchestration use case, the important acceptance points are:

    1. The profile/preset ID is selectable by orca orchestration worker-start --agent ... (or an equivalent explicit launch-profile flag).
    2. Existing --model / --effort overrides still compose with the selected profile.
    3. launch.requested / launch.effective report the exact profile/preset identity, with secrets redacted.
    4. The resulting terminal remains a supervised Worker, so worker-show, worker-stop, worker-release, session history, and prompt delivery retain normal Codex behavior.
    5. Selecting the Worker profile does not mutate the global/default Codex launch configuration used by a fresh coordinator session.

    The motivation is partly reliability: generic repository-only Develop/Review/Validate workers usually do not need MCP, and MCP initialization is involved in the startup race reported in #13439. Disabling MCP for that worker profile reduces startup work without removing MCP from coordinators or specialist workers.

    If draft PR #8337 is the current landing path, it would be useful to cover this as an end-to-end orchestration fixture, not only a Settings/launcher picker case.

  8. webparadoxer commented on Sep 4, 2026

    @webparadoxer

    +1 for this feature

    I’d like to use the same CLI agent multiple times with different configurations.

    My use case is OpenCode connected to multiple Ollama Cloud models. I want to have separate Orca agents like:

    OpenCode GLM → opencode --model ollama/glm-5.3:cloud
    OpenCode Kimi → opencode --model ollama/kimi-k3:cloud
    OpenCode MiniMax → opencode --model ollama/minimax-m3:cloud

    Right now Orca only exposes a single OpenCode entry, so I can configure only one default command/arguments combination.

    What I’d like is the ability to duplicate an existing agent or create custom presets based on an existing agent type, while keeping Orca’s native OpenCode integration, prompt injection, session resume, etc.

  9. 10 remaining items

  10. megamorphg commented on Oct 15, 2026

    @megamorphg

    I'm able to add custom agent presets e.g.
    Image

    I can start a new terminal chat with this fine because its a wrapper that declares a new home. But it of course doesn't work in the new chat mode. I get an error "Chat could not be started. Codex's Command in Settings → Agents must be a program path or name Orca can find, with no arguments or variables. Change it or reset it."

    Also when I try to resume a chat after I put it to Sleep, it just opens a normal terminal window.

    I guess these are all related issues being worked on with this? Since we are able to add multiple Codex profiles, it seems next step to respect the home directory (and have the chats that are indexed be indexed from both homes not just the default codex directory).

  11. micro-chipset commented on Oct 17, 2026

    @micro-chipset

    +1 for this feature.

  12. nwparker commented on Oct 18, 2026

    @nwparker
    Contributor

    Consolidating two duplicate requests here; this feature remains open.

    • [Feature] Custom Agent params #28426 asks for multiple named Claude launchers in Settings → Agents, such as Scout (Haiku, high effort) and Worker (Sonnet, high effort), each with its own model, effort, and additional CLI arguments. Automation-only options do not cover these manually selected main-agent entries.
    • [Feature]: Allow same agents with different argument as customizable command #28756 asks for named variants of the same installed agent, especially Copilot: separate refinement, development, specification, review, and QA entries, each choosing its own model and agent/role arguments without replacing the normal Copilot command.

    These fit the existing named built-in profile/default-argument requirements above. Closing the duplicate reports does not claim implementation or close any preset/profile PR.

  13. nwparker commented on Oct 18, 2026

    @nwparker
    Contributor

    Consolidating #9552 here as another named launch-preset use case: GitHub Copilot Planner and Builder entries, each with its own model and custom-agent argument (model X / CustomAgentX versus model Y / CustomAgentY). The request also allows an arbitrary named command-plus-arguments entry rather than borrowing an installed provider slot. This is already within this issue’s built-in profile and custom-agent requirements. The July “coming today” reply did not establish shipment; this issue remains open.

  14. domai-tb commented on Nov 9, 2026

    @domai-tb

    Hey, is there any roadmap or timeline when #8337 will be merged? Thanks for your work!

  15. codingsf commented on Nov 12, 2026

    @codingsf

    +1 for this feature.

  16. roszell commented on Nov 13, 2026

    @roszell

    Another +1, we have a custom, named agent for our org built on pi. We currently have to manually override pi's launch settings in orca in order to use it here. What I'd really like in addition to this is to be able to configure orca from the cli as a one time set up to add this custom agent as well. From our org cli dev setup command, we'd ensure orca is installed and configured with our custom agent. Then we can reference it by name (instead of pi and 🤞 that it's configured as our agent correctly) from the cli when launching, starting workers, etc

  17. doublefx commented on Nov 15, 2026

    @doublefx

    My concrete use case is two named Claude Code launch presets: Personal and Work, with projects and agents running in WSL over SSH from Orca on Windows.

    I currently keep the accounts/configuration separate with existing wrappers and CLAUDE_CONFIG_DIR (~/.claude versus ~/.claude-work). I would like to select those presets per workspace without replacing the normal Claude entry or borrowing another provider's slot.

    A useful initial scope for me would be:

    • A label plus a launch command/arguments/environment, so my existing wrappers keep working.
    • Two selectable entries that still identify as Claude for session tracking, history/resume and hooks.
    • A workspace-level choice that does not switch the other account's already-running sessions.

    I saw that #8337, previously described as the replacement for #2521, was closed on 12 November as a stale draft needing a fresh design. Rather than asking to merge that old branch, is there an agreed owner or proposal for a smaller implementation against current main? What acceptance tests would make the scope above useful to review?

    I am treating quota display that follows the selected session as a separate requirement; two launch entries alone would not establish that. I am currently on 1.4.258 and will keep my existing wrappers until a shipped implementation can be validated.

  18. Adonis0123 commented on Nov 15, 2026

    @Adonis0123

    Following up from #25065 (closed in favour of this issue), with the Chat pane case that an earlier comment here also ran into (a wrapper command works in a terminal pane but Chat refuses it).

    Setup. Several Claude subscriptions on one Mac, each already signed in to its own config folder (~/.claude, ~/.claude-work, ~/.claude-personal), started with a CLI account manager or plain aliases (CLAUDE_CONFIG_DIR=~/.claude-work claude).

    What works (Orca 1.4.259, macOS, checked 2026-11-15). In a terminal pane, a CLAUDE_CONFIG_DIR set in the pane wins over Orca's selection, so these aliases work there.

    What does not. A Chat pane follows only Orca's saved accounts. orca account add runs claude login into a new folder under Orca's data folder, so an account that is already signed in elsewhere has to sign in again and ends up as a second folder for the same login. With no saved account, Chat uses the default config folder. The selection (orca account select, the status-bar switcher) applies to every new launch, not to one pane.

    Ask.

    1. Let a saved Claude account point at an existing config folder instead of signing in to a new one (for example orca account add --agent claude --config-dir ~/.claude-work, or "Use an existing folder…" in Settings). Orca would use the folder as it is: no new sign-in, no moving or copying files.
    2. Let a new Chat pick its account, so two Chats can run on different accounts side by side.
  19. roszell commented on Nov 17, 2026

    @roszell

    @AmethystLiang do you have a rough idea as to if / when y'all will pick this work back up?

  20. azohra commented on Nov 18, 2026

    @azohra

    Named launch profiles under a built-in agent, selectable on every launch path

    I run Claude Code and Codex each under two configurations on one Mac: Claude with a second CLAUDE_CONFIG_DIR, and Codex with an OpenAI API key and its own profile. Each is a wrapper command. Orca's managed accounts don't fit: they are Orca-held sign-ins, they can't hold an API key, and the selection is host-wide.

    Until now I overrode a spare agent's command to get the second configuration. That loses everything keyed on the agent id: worker-start --model/--effort is refused, automation extra arguments are refused, and status recognition is wrong.

    What I'm asking for, extending the design sketched in #5728 to the CLI:

    1. A profile belongs to a built-in agent and has a name, an optional command, arguments and environment. It keeps that agent's identity: model catalog, extras allowlist, hooks, trust and resume.
    2. A profile can be selected wherever an agent is: orca agent launch, worktree create --agent, orchestration worker-start and automations create/edit. For example --agent claude --profile work. --model and --effort still apply.
    3. The pane records its profile, so a restore or resume relaunches the same one.
    4. Profiles live in host settings and can be read and written over RPC and the CLI, so they can be scripted and backed up.

    Not asking for account pinning, quota failover or credential management. This only lets one agent have more than one launch configuration. #9496, #22691, #25762 and #43190 cover Orca-managed accounts; this covers wrapper commands and API keys, which they can't.

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

Metadata

Metadata

Assignees

Labels

enhancementNew feature or requestsize/mMedium PR (≤600 added lines, ≤25 files)

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions