dsh-agent-hub

Run any agent loop engine on dsh — the built-in in-process loop, Claude Code, Codex, or Pi — chosen per session, all sharing dsh's own session store, message format, model routing, and tracing.

Pick an engine the way you pick a model: in the composer, when you start a session. The session you are in keeps running on the engine it was created with. No restart, no global switch, no interrupted work.

Why a hub

dsh admits exactly one AgentFactory for the whole process. That single slot is what forced every earlier approach to be a global choice: to run Claude Code you had to disable the base loop, and every session in the profile moved with you.

This plugin takes that slot and turns it into a router. It holds one factory per engine — including dsh's own in-process loop, mounted as a first-class engine rather than replaced — and dispatches each createAgent / resume call to the engine that session belongs to.

dsh harness  (session · llm · tracing · model routing)
      │
      │  the one AgentFactory slot
      ▼
 LoopEngineRouter
      ├── in-process   → @deepseek-ai/dsh-agent-loop  (hosted, not replaced)
      ├── claude-code  → Claude Agent SDK
      ├── codex        → codex app-server
      └── pi           → pi --mode rpc

Everything above the router stays dsh's. Each engine's native output is translated into dsh's Message / ContentBlock / StreamChunk types, so sessions from different engines are stored, streamed, resumed, and traced identically.

Engine affinity is durable

A session's engine is recorded when it is created and travels with it. Resuming a session restores it to the engine that produced its history — not to whatever is currently selected. This matters because engine session logs carry different provenance (a Codex-driven session records provider = 'codex'), and replaying that history under another engine would hand the model a transcript it cannot act on.

Forked sessions and subagents inherit the parent's engine.

Install

dsh plugin --profile web add @vidge/dsh-agent-hub

Restart dsh web once after installing. After that, engine selection is runtime state — switching never requires a restart again.

Installing writes a small managed block into the profile's cordis.patch.yml, disabling the bundle's own agent-loop row so the router can take the factory slot and re-mount that loop itself. Everything else in that file is preserved byte for byte.

Engine dependencies

Each engine's SDK is an optional peer — installing this plugin pulls in the router only. Add the engines you actually want, into the same profile:

# Claude Code
dsh plugin --profile web add @anthropic-ai/claude-agent-sdk@0.3.220
# Codex
dsh plugin --profile web add @openai/codex@0.149.1
# Pi
dsh plugin --profile web add @earendil-works/pi-coding-agent@0.84.3

Two details matter, and getting either wrong looks like a plugin bug:

• Install through dsh plugin ... add, not a bare pnpm add. The SDK has to land in the profile that runs dsh (~/.dsh/profiles/<name>). A pnpm add in some other directory installs a package the host will never resolve.
• Pin the version this release declares. The versions above are the exact peerDependencies entries of this package; the SDK message vocabularies are not stable across minors, and a drifting version is not a supported configuration.

Because profiles set autoInstallPeers: false, an optional peer is only ever present if some package explicitly depends on it. Installing it as a direct profile dependency (which the command above does) records it in the profile's lockfile, so later installs and upgrades keep it. An SDK that is merely present in node_modules without being depended on is an orphan, and the next pnpm install in that profile will prune it — after which the engine reports the package as missing.

The in-process engine needs nothing beyond dsh itself, so a profile that installs no SDK at all still works.

Selecting an engine whose SDK is missing fails that turn with a message naming the package to install; it never affects other sessions or engines.

Authentication

Only for the engines you use:

• Claude Code — credentials are derived from dsh's own LLM provider configuration (see below); a CLI login is a fallback, not a requirement.
• Codex — authenticated via codex login, or a CODEX_API_KEY entry.
• Pi — authenticated the way pi expects: its own ~/.pi/agent/auth.json, or the provider's API-key environment variable.

Usage

Choose an engine in the composer when starting a session. To change engines, start a new session — the current one keeps its engine, and anything still running on it is undisturbed.

Settings → Loop engine sets the default for new sessions and controls whether the composer picker is shown.

To remove the plugin:

dsh plugin --profile web remove @vidge/dsh-agent-hub

Then restart dsh web.

Model and credential routing

For the Claude Code engine, the child process's provider environment is derived from dsh's own LLM configuration rather than inherited from the shell that launched the host. The selected model names a provider route; the plugin reads that route's endpoint from llm-pi-ai settings, resolves its key through dsh's credentials service, and states the result as the environment variables the Agent SDK understands — Bedrock (including behind a corporate gateway) and native Anthropic endpoints.

This is why a dsh started from a desktop launcher works: it inherits no provider variables, but it does not need to. dsh already knows the answer.

When a route cannot be derived — an OpenAI-protocol provider with no Claude Code equivalent, an unset credential — the plugin falls back to inherited environment and reports what the child was actually pointed at.

Engine notes

• Claude Code runs one SDK query per dsh step. Its slash commands are bridged into the web menu (built-ins plus user-level ~/.claude/commands/) and forwarded to the engine, which expands them natively. Project-level .claude/commands/ files stay engine-side and work when typed directly.
• Codex runs codex app-server and has no interactive tool approval — permissions come from the session's sandboxMode + approvalPolicy. Its AGENTS.md files are surfaced through the dsh skill-injection seam across every directory from the session cwd up to the git root, plus ~/.codex/AGENTS.md.
• Pi runs pi --mode rpc. Pi has no permission system, so the whole child is sandboxed through the dsh subprocess service (default read-only). Its context files (AGENTS.md / CLAUDE.md, with AGENTS.override.md preferred, plus the user-level file under the pi config dir) and its skills/ catalogs are surfaced through the same seam.

License

MIT