Skip to content

[Feature]: user-defined agent entries — bring your own CLI, and presets for the ones you have #18249

Description

@akolmayer

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:

  1. Running a CLI Orca doesn't ship — a vendor tool, a self-hosted gateway, or a wrapper
    script of your own.
  2. 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:

  1. Picked two entries nobody has installed (crush, openclaw).
  2. Planted symlinks named after them on PATH so detectCmd finds "them", plus a second
    symlink of the same name behind my wrapper so the running process still matches
    expectedProcess.
  3. Overwrote agentDefaultArgs.crush / agentDefaultArgs.openclaw — which also means
    deleting those entries' real defaults (e.g. --yolo), since the borrowed CLI rejects them.
  4. 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:

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:

    Orca launcher showing the hijacked catalog slots

    OpenRouter is really the crush slot and Qwen 3.6 ∞ is the openclaw slot, 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.5 is 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

  1. Dhi13man commented on Sep 4, 2026

    @Dhi13man

    #17668 handles local profiles and unsupported terminal CLIs on my fork. Could it cover the non-plugin part here?

  2. akolmayer commented on Sep 4, 2026

    @akolmayer
    Author

    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:

    1. expectedProcess for wrapper scripts. I see it threaded through
      custom-agent-automation-startup.ts. For a profile created from a raw command rather than
      duplicated 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 the
      running 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.

    2. A missing binary. If the command isn't on PATH for a given host, does the profile show
      as 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.

  3. added theissue type on Sep 19, 2026
  4. harisonw commented on Sep 25, 2026

    @harisonw

    A concrete use case is a user-defined GitHub Copilot entry such as Copilot Luna, launching copilot --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.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions