Skip to content

[Feature]: Allow multiple named entries (aliases) per agent harness #9136

Open

Description

@s546126

Problem or use case

Each CLI harness can only appear once in Settings → Agents. I use one harness (e.g. Codex) against several different models — OpenAI's hosted models, third-party providers, and locally-deployed open-source models. The CLI invocation is identical; only the model / base URL / API key differs. Today the only per-agent customization is agentCmdOverrides, agentDefaultArgs, and agentDefaultEnv, all keyed by a single TuiAgent id, so I can configure exactly one Codex profile and have to hand-edit settings whenever I switch models.

Locally I already distinguish these combinations with shell aliases — one alias per model × reasoning-effort pair, all wrapping the same CLI. Orca can't see them: a shell alias isn't on PATH as a binary, and detectCmdAliases in TUI_AGENT_CONFIG works the other way around — it collapses several command names into a single catalog entry rather than surfacing them as separate ones. So the distinction I maintain in my shell is flattened away the moment I'm in Orca.

Proposed solution

Let one harness back multiple named catalog entries. Each entry would have its own label, args, and env, and would show up as a separate row in Settings → Agents and in the agent picker — so Codex (gpt-5), Codex (local qwen), Codex (vendor X) can be enabled, disabled, and set-as-default independently.

claude-agent-teams is already exactly this shape by hand: a distinct id whose expectedProcess is claude and which requires claude on PATH. Generalizing that into user-definable entries with a baseAgent: TuiAgent field would cover it.

Concretely, an entry should be able to override the launch command itself, not just args and env — that's what lets codex-high and codex-local-qwen be two rows backed by one harness, mirroring the aliases I already have.

Alternatives or additional context

  • Workaround today is editing agentDefaultEnv per switch, or shell wrappers on PATH that Orca can't detect as agents.
  • Main blockers: TuiAgent is a closed union (src/shared/types.ts:2397) and every table is Record<TuiAgent, …>; isTuiAgent validates by membership in TUI_AGENT_CONFIG; normalizeDisabledTuiAgents (src/main/persistence.ts:5274) silently drops unknown ids. A parallel customAgents list with baseAgent would avoid widening the union.
  • The commit-message flow already has a scoped CUSTOM_AGENT_ID escape hatch (src/shared/commit-message-agent-spec.ts:673), but it never reaches the launchable catalog.

Activity

  1. AmethystLiang commented on Jul 17, 2026

    @AmethystLiang
    Contributor

    it's coming :-D

    Image Image
  2. s546126 commented on Jul 17, 2026

    @s546126
    ContributorAuthor

    @AmethystLiang Can't wait to try out this new feature!

  3. Dhi13man commented on Sep 4, 2026

    @Dhi13man

    #17668 runs multiple named Codex profiles on my fork. Is that what you had in mind?

  4. wrightbuilt commented on Sep 9, 2026

    @wrightbuilt

    Adding my upvote. I want multiple named Codex entries in Orca—such as a default model, a high-effort reviewer, and an alternate-provider model—each with its own model, CLI arguments, and optional environment.

    In Orca 1.4.198, worktree create --agent codex selects Codex but does not allow choosing a model or effort per launch. worker-start supports model/effort overrides, but there is still no reusable named profile in the normal launcher. Editing global Codex defaults or manually creating terminal commands is awkward when running several variants in parallel.

    PR #17668 looks like exactly the right direction. I’d appreciate seeing this prioritized or merged.

  5. harisonw commented on Sep 25, 2026

    @harisonw

    I would use this to create multiple named entries backed by GitHub Copilot, for example Copilot Luna launching copilot --yolo --model=gpt-5.6-luna. This would provide a quick, lower-cost model window alongside the normal Copilot configuration, without manually editing settings between launches.

  6. iHusk commented on Oct 2, 2026

    @iHusk

    This still in the pipeline? I/my team manage multiple separate billing profiles for different clients and being able to dispatch these as custom agents would be a huge boon.

  7. nwparker commented on Oct 18, 2026

    @nwparker
    Contributor

    Consolidating #25661’s matching Claude use case here: named entries such as claude-code, claude-docs and claude-review can wrap the same Claude harness while loading different plugins and choosing different entry agents. Each should remain a separately selectable launch option with its own command and a Claude base type, rather than requiring a raw terminal or repeatedly changing one global Claude command. This fits the command override plus baseAgent model proposed here. The original request remains at #25661.

  8. danchamorro commented on Nov 3, 2026

    @danchamorro

    I would also find this useful, particularly in Chat UI.

    I use separate Pi profiles for personal work and different businesses. Each profile has its own models, extensions, settings, and account configuration. I also use separate personal and work Claude Code subscriptions.

    I would like to add named instances such as Pi Personal, Pi Work 1, Pi Work 2, Claude Personal, and Claude Work, then choose the right instance when starting a chat or terminal session without changing a shared agent configuration.

    Each instance should have its own executable path, launch arguments, and environment variables. For Pi, that includes a separate PI_CODING_AGENT_DIR. Existing sessions should remain associated with the instance they started with, and credentials and configuration should remain separate between instances.

    T3 Code's provider settings illustrate the experience I mean. The screenshot below shows multiple named instances of the same agent, with separate runtime configuration. Connection names are anonymized and the account identity is redacted.

    T3 Code provider settings showing Claude Personal, Claude Work, and multiple Pi profiles alongside per-instance runtime settings

    This would help avoid accidentally using the wrong account or Pi profile when switching between personal and work projects. Account switching alone does not cover profiles with different extensions and settings.

  9. eltria commented on Nov 7, 2026

    @eltria

    A concrete case for named entries backed by the Claude harness, and what a plugin can and can't cover today (Orca 1.4.251, macOS).

    I run Claude Code through several wrappers. Each is a small script that exports ANTHROPIC_BASE_URL, a token and the model mapping for one API gateway, then does exec claude --dangerously-skip-permissions "$@". One more entry is a managed launcher with its own subcommand (<launcher> launch claude). I'd like to pick one of these by name when starting an agent, like a terminal-profile list (name + command).

    What this needs beyond today's single Claude command override:

    1. A command with arguments, with Orca's args appended. <launcher> launch claude is three words; Orca's own args (--prefill, permission flags, the prompt) go after it. The launcher already forwards unknown flags to claude.
    2. The Claude identity, even though the executable differs. Every entry ends up running the claude process, so prompt injection, status hooks, trust preflight and resume should work exactly as for Claude. A rule like "changing the executable drops the provider identity" (feat: add custom agent launch profiles #17668) would turn all of them into plain terminals.
    3. Resume through the same entry. Otherwise a conversation started on one gateway silently continues on another provider and model.

    Meanwhile I use a local plugin: an agent.launch.before hook swaps the program at the head of Claude's command for the wrapper picked in four status bar items. It covers new launches from every launcher, but:

    • the entries can't appear in the agent picker or Settings → Agents (contributes.agentHarnesses is still reserved),
    • restores and resumes skip the hook, so they fall back to the global Claude command (point 3),
    • agent.launch / terminal.create from a plugin always open in the background, so a "start this profile now" command can't bring the new tab forward.

    Happy to test #8337 or a follow-up with this setup on macOS.

  10. cfqlilei commented on Nov 8, 2026

    @cfqlilei

    Adding a concrete Claude-only case from the terminal new-agent path (Orca 1.4.251, macOS 15.5, Apple Silicon).

    Setup. One Claude CLI, several model aliases. The only difference between them is the model flag: claude --model opus versus claude --model sonnet. I want each variant to be a named entry I pick when I open an agent tab.

    What 1.4.251 gives me today

    • Settings -> Agents keeps exactly one Arguments string per agent, so switching models means editing that field before each launch, every time.
    • The new-tab agent picker does expose an Arguments field for terminal launches, but it is a per-launch draft: not saved, not named, and not selectable next time.
    • orca agent launch --model and orca worktree create --agent --model choose a model for one launch, but there is no reusable named entry, and neither takes arbitrary extra arguments.

    Proposed

    Named entries under an existing harness, each with a label, command, arguments and environment, selectable everywhere an agent starts (new-tab terminal picker, Create worktree, worktree create --agent), persisted across restarts, and still treated as the base harness so prompt injection, status hooks and resume keep working.

    Related: #36236 (the Claude-only preset request filed earlier).

  11. Stardust0831 commented on Nov 13, 2026

    @Stardust0831

    I'd like to add a concrete Codex use case: run multiple configurations concurrently, each selectable by a custom alias in Orca's native agent picker.

    Each configuration should support:

    • Its own provider/base URL and credentials, including different API keys for the same endpoint.
    • Its own CODEX_HOME, including an existing user-managed directory.
    • A custom alias, such as Codex Personal, Codex Work, or Codex Local.

    For example, I use separate API keys for different purposes and would like to launch both configurations side by side without changing a global Codex setting. Separate homes would also let me keep their configuration and history apart.

    This should work for native chat and terminal sessions. Follow-up messages and resumed sessions, including after restarting Orca, should keep the configuration they started with.

    Could this be covered by the named-entry support proposed here? Related: #10366 for importing an existing CODEX_HOME.

  12. Stardust0831 commented on Nov 13, 2026

    @Stardust0831

    I've implemented and locally validated a Codex-focused prototype for this: implementation, based on c75b43bc8666.

    The configuration is a named entry with { id, label, homePath, modelProvider, model? }. Multiple entries can use the same home with different providers, or different homes with the same provider ID. For example, Codex Work and Codex Personal can select two providers in one config.toml, including different API keys for the same endpoint; another entry can select a separate home.

    The main implementation choices are:

    • Keep the canonical harness identity codex, with a separate stable entry ID. Settings → Agents manages the entries, and the picker exposes their aliases for native chat and terminal launches.
    • Resolve the entry on the execution host. Select CODEX_HOME and pass -c model_provider="…" per process. Credentials remain in Codex configuration or the host environment. Named launches use their own model/configuration instead of inheriting global Codex model/argument defaults.
    • Persist the resolved descriptor in native conversation records, and the effective arguments/environment in existing terminal restore recipes. Changing defaults, repointing an alias, or deleting its definition does not redirect a saved conversation. Missing homes/configuration produce an error. This pins the selection, not the contents of user-editable config/auth files.
    • Scope running-chat model discovery by home/provider/entry. Prepare terminal status hooks in custom homes using the existing in-place reconciliation path, without mirroring global Codex configuration into them.

    Validation used real Codex 0.167.2, isolated homes and a localhost Responses SSE server with three dummy keys at the same endpoint:

    Scenario Result
    Native chat: first turn, follow-up, close/resume, then changed aliases/global defaults and Orca server restart 12/12 requests routed to the expected key: A/B in one home, C in another
    Codex terminals: initial replies, sleep, removed alias definitions, Orca server restart, saved restore and follow-up 12/12 requests routed correctly
    Web UI, headless Chromium/CDP, 1280×900 Alias selection and execution-host settings add/reload/edit/remove passed; existing entries preserved; light/dark views checked
    Focused tests and builds 31 tests across 8 files passed; Node/Web/CLI typechecks and Web/mobile-Web/orcad builds passed

    pnpm check:changed --maxWorkers=2 --timeout=3 passed 36 of 37 checks; its broad affected-unit-test selection timed out at 180 seconds, so I am not claiming a full-suite pass. The UI also reported Unknown method: linear.onLinkedIssueUpdated from an unchanged web bridge path; feature assertions passed with that error recorded separately.

    This is a prototype with explicit remaining scope: native macOS/Windows, SSH, Electron and mobile interaction still need validation; Windows-host → WSL launches are refused pending proper host routing. Profile-specific model discovery before launch is not implemented yet (an entry can specify a model or use its home's default). Per-alias default/disable controls and other harnesses are also still outside this Codex slice.

    For attribution, I adapted the normalization/deduplication and draft ID/upsert excerpts from @brennanb2025's #5728, commits fa4631b435566 and f0b92dfc9ef9. The implementation commit records the source paths and retains the original co-author credits. #5754's separate profile identity / canonical harness approach also informed the design; no code was copied from #5754, #8573 or #17668.

    Would the separate entry identity plus a persisted launch descriptor be a useful foundation to integrate into the existing named-entry work, particularly for native chat and restore behavior?

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 request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions