Repository navigation
Description
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:
TuiAgentis a fixed union insrc/shared/types.ts.TUI_AGENT_CONFIGis a fixed record insrc/shared/tui-agent-config.ts.AGENT_CATALOGis a fixed catalog insrc/renderer/src/lib/agent-catalog.tsx.- Settings store
agentCmdOverridesas a partial record keyed byTuiAgent. - 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). agentCmdOverridesis 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-startor 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)
- Env + multi-profile support — custom agents must carry an env map and default args so multi-account Claude Code setups (
CLAUDE_CONFIG_DIR=~/.claude-workvs personal default) and env-based provider variants work as first-class agents, not PATH hacks. - Click-to-launch + automation/CLI parity — registered custom agents are selectable everywhere built-ins are: launcher UI, CLI flags, automations create/dispatch.
- Session history parity — sessions started from custom agents (and ideally agents launched via terminal commands Orca recognizes) appear in agent session history.
- 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.
- 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 idBuilt-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
nwparker commentedon May 29, 2026
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.
liuyifeng92 commentedon Jul 13, 2026
+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:
ReasonixreasonixAfter saving, the custom agent should appear alongside built-in agents in:
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.137on macOS. The documentation describes this workflow, but the “Add custom agent” button isnot 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.
nwparker commentedon Jul 13, 2026
We're working on it!
Sorry for the doc-desync. We got a bit trigger happy.
AmethystLiang commentedon Jul 22, 2026
Merged duplicate #9933 into this issue.
New requirements folded into the description:
CLAUDE_CONFIG_DIR) and similar setups--agent/--providerand automations (today the provider list is hardcoded)claude@work= provider + env map)Also linked the concrete workarounds users hit (PATH shims squatting provider slots, global
agentCmdOverridesnot covering automations cleanly).shengy3000 commentedon Aug 6, 2026
+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:
detectCmd(resolveDetectedTuiAgentIdsovergetTuiAgentDetectCommands,src/shared/tui-agent-detection-commands.ts), and process recognition stays keyed on itsexpectedProcess(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.TerminalCommandQuickCommandis 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 aTuiAgentever 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
CustomTuiAgentshape proposed here is right, and why per-agentdetectCmd+expectedProcess(alongsidecommand/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).
quessaer commentedon Aug 21, 2026
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.187and Codex CLI0.149.0:orca orchestration worker-start --agent codexaccepts per-invocation--model/--effort, but not Codex--profile,--config, or environment overrides.-p <profile>and-c mcp_servers.<name>.enabled=false.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 enabledCodex: Worker (No MCP)— same Codex identity and account, but launched with a dedicated profile/default args that disable MCPThis 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:
orca orchestration worker-start --agent ...(or an equivalent explicit launch-profile flag).--model/--effortoverrides still compose with the selected profile.launch.requested/launch.effectivereport the exact profile/preset identity, with secrets redacted.worker-show,worker-stop,worker-release, session history, and prompt delivery retain normal Codex behavior.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.
webparadoxer commentedon Sep 4, 2026
+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.
10 remaining items
megamorphg commentedon Oct 15, 2026
I'm able to add custom agent presets e.g.

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).
micro-chipset commentedon Oct 17, 2026
+1 for this feature.
nwparker commentedon Oct 18, 2026
Consolidating two duplicate requests here; this feature remains open.
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.
nwparker commentedon Oct 18, 2026
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.
domai-tb commentedon Nov 9, 2026
Hey, is there any roadmap or timeline when #8337 will be merged? Thanks for your work!
codingsf commentedon Nov 12, 2026
+1 for this feature.
roszell commentedon Nov 13, 2026
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
piand 🤞 that it's configured as our agent correctly) from the cli when launching, starting workers, etcdoublefx commentedon Nov 15, 2026
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(~/.claudeversus~/.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:
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.
Adonis0123 commentedon Nov 15, 2026
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_DIRset 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 addrunsclaude logininto 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.
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.roszell commentedon Nov 17, 2026
@AmethystLiang do you have a rough idea as to if / when y'all will pick this work back up?
azohra commentedon Nov 18, 2026
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/--effortis 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:
orca agent launch,worktree create --agent,orchestration worker-startandautomations create/edit. For example--agent claude --profile work.--modeland--effortstill apply.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.