Repository navigation
Description
Problem or use case
Orca's agent catalog is a fixed list of ~33 entries compiled into the app. Each entry is
matched by binary name (detectCmd), launched by a fixed command (launchCmd) and tracked
by process name (expectedProcess). A user can override an existing entry's command and
arguments, but cannot add one — so two things are impossible today:
- Running a CLI Orca doesn't ship — a vendor tool, a self-hosted gateway, or a wrapper
script of your own. - Having one installed CLI appear as several entries, pinned to different providers or
models.
The second case is the common one now that coding CLIs are provider-agnostic. One binary
(opencode, codex, crush, goose) fronts many providers and dozens of models. What I
want to launch is not "OpenCode" but "OpenCode on my unlimited Qwen plan" or "OpenCode on
free OpenRouter models" — different cost, context window and rate limits, so they belong in
the launcher as different entries.
What I ended up doing instead. With no supported path, I hijacked the catalog:
- Picked two entries nobody has installed (
crush,openclaw). - Planted symlinks named after them on
PATHsodetectCmdfinds "them", plus a second
symlink of the same name behind my wrapper so the running process still matches
expectedProcess. - Overwrote
agentDefaultArgs.crush/agentDefaultArgs.openclaw— which also means
deleting those entries' real defaults (e.g.--yolo), since the borrowed CLI rejects them. - Shipped a local dev plugin whose language pack overrides
auto.lib.agent.catalog.*so the
menu reads "OpenRouter" and "Qwen 3.6 ∞" instead of "Charm" and "OpenClaw".
It works, and it is as brittle as it sounds: installing the real Crush later collides with my
symlink, the icons still belong to charm.sh and openclaw, and agent status hooks are keyed to
a borrowed id. Every user who wants this reinvents the same hack.
Proposed solution
Let users declare additional agent entries, with the trust question handled up front.
Where entries come from — two sources:
- Plugin contribution (primary). The plugin manifest already has
contributes.agents: [{ path }]. Extend it to carry agent definitions, so custom agents
inherit machinery that already exists: manifest validation, the consent fingerprint and
"Review & enable" flow, per-plugin disable, the kill list, and marketplace distribution. - Local definition (secondary). An "Add agent" flow in Agent settings for a single
machine, using the same schema and the same review screen, disabled until confirmed.
Entry schema, mirroring the internal registry rather than inventing a parallel one:
{
"id": "custom.acme.qwen-unlim", // namespaced; may never collide with a built-in id
"label": "Qwen 3.6 ∞",
"icon": "icons/qwen.png", // bundled file, or a letter avatar
"detect": { "cmd": "opencode" },
"launch": {
"cmd": "opencode",
"args": ["--model", "neuraldeep/qwen3.6-unlim"],
"expectedProcess": "opencode" // defaults to basename(launch.cmd)
},
"promptInjectionMode": "stdin-after-start",
"defaultEnv": { "SOME_FLAG": "1" },
"platforms": { "win32": { "launch": { "cmd": "opencode.cmd" } } }
}expectedProcess is explicit rather than implied by the entry id, so a wrapper script can
declare what actually ends up running and status tracking keeps working. detect is separate
from launch, so an entry can be detected by the CLI it wraps. No --dangerously-* defaults
are ever inherited from a built-in entry.
Behaviour. Custom entries appear where built-ins do (the + menu, quick launch, the agent
picker, Agent settings) and take part in defaultTuiAgent / disabledTuiAgents. Detection
runs per workspace host as it does today. Built-in ids stay reserved: a custom entry can never
shadow or silently retitle a shipped one — which also keeps this from becoming a second,
unreviewed way to change what "Claude" or "Codex" launches. Labels come from the definition,
so no language-pack workaround is needed to name things.
Security. The objection I'd expect is that an agent entry is a command Orca executes, and
"Add agent" is a soft path to arbitrary execution. Hence: plugin-contributed agents run only
after the existing consent flow; a changed definition changes the fingerprint and forces
re-review; locally added agents show the resolved command, arguments and environment before
first launch; definitions never carry credentials (CLIs keep their own auth); and nothing is
auto-imported from a workspace checkout, so a repo can't add an agent to your launcher.
Alternatives or additional context
Related work in this repo:
- feat: add custom agent launch profiles #17668 (open) adds launch profiles for installed agents — case 2 above. This request
does not re-litigate it; if it lands, custom agents should reuse its profile model rather
than add a second one. What it doesn't cover is a CLI the catalog has never heard of. - [Feature]: Allow users to add custom agent presets, not only override commands for built-in agents #2284 asks for user-added presets.
- Custom agents #8337 is a stalled draft in this area.
- [Feature]: Allow custom / user-defined agent integrations? #11469 ("Allow custom/user-defined agent integrations") was closed
not_plannedon
2026-08-23 with no recorded rationale.
The question I'd like answered first: was #11469 closed on scope or on security? The
design above assumes security, which is why the plugin consent flow is the primary path. If
the objection was different, the proposal should be reshaped before anyone writes code.
Alternatives I considered and rejected:
-
Keep hijacking unused catalog slots — what I do now; collides with real installs, wrong
icons, borrowed status hooks.Here is what that workaround looks like in the launcher today — three entries named after
the models they actually start:
OpenRouteris really thecrushslot andQwen 3.6 ∞is theopenclawslot, which is
why they wear charm.sh's and openclaw's icons: the favicon domain is baked into the
catalog, so a language pack can rename an entry but not re-brand it.
OpenCode · Mercury 2.5is the genuine OpenCode entry, relabelled the same way. -
Rename via a language-pack plugin only — cosmetic; the entry is still someone else's, and
icons can't be overridden since the favicon domain is baked into the catalog. -
A plugin panel — plugins can contribute panels, but panels are webviews and can't start a
terminal agent, so this doesn't reach the use case.
I have a longer design document with a testing plan and open questions, and I'm happy to
implement this behind the existing plugin consent flow if the shape is acceptable. Tested
against 1.4.193 on macOS (arm64).
Written with help from Claude Opus 5 (Claude Code); all claims about current behaviour
were checked against a running 1.4.193 install. X: @akolmayer
Activity
Dhi13man commentedon Sep 4, 2026
#17668 handles local profiles and unsupported terminal CLIs on my fork. Could it cover the non-plugin part here?
akolmayer commentedon Sep 4, 2026
Yes – it covers the non-plugin half, and from the updated description and the diff it goes
further than what I sketched: SSH/WSL launch paths, automations, and keeping the built-in
provider identity separate from the profile are all things I hadn't worked through.
The way I'd draw the line: yours is creating an entry on one machine, mine is distributing one
and making it reviewable – a team packaging its internal agent as a plugin so everyone gets it
through the existing consent flow, instead of each member retyping the same local profile.
That only makes sense on top of what you've built, so I'll narrow this issue to the
plugin-contributed path once yours lands.
Two things I'd like to confirm, because they're where my workaround broke:
expectedProcessfor wrapper scripts. I see it threaded throughcustom-agent-automation-startup.ts. For a profile created from a raw command rather thanduplicated from a built-in, is it derived from the executable or settable on its own? My
entry launches a small script that picks a model and then
execs the real CLI, so therunning process name differs from the launch command – in the slot hijack I had to plant a
second symlink under the borrowed name just to keep status tracking alive.
A missing binary. If the command isn't on
PATHfor a given host, does the profile showas not installed the way built-ins do, or does it only fail when the terminal opens? Mostly
an SSH question, where a profile may be valid on one host and not another.
harisonw commentedon Sep 25, 2026
A concrete use case is a user-defined GitHub Copilot entry such as
Copilot Luna, launchingcopilot --yolo --model=gpt-5.6-luna. This would let me keep separate named model and cost options in the launcher, instead of using a generic Copilot entry and changing arguments manually.