AI Agents

Shellarium runs AI coding agents as headless subprocesses. Each agent receives your task description and works autonomously to implement it.

Supported Providers

Claude Code — Anthropic’s coding agent (default, native integration)
ACP-compatible agents — any agent implementing the Agent Communication Protocol, including Codex CLI (OpenAI), Aider, and others from the ACP registry

How Agents Work

When you start an agent, Shellarium:

Creates an isolated git worktree for the workspace
Spawns the agent process with your task as the prompt
Streams the agent’s output to the UI in real time
Handles permission requests from the agent

The agent has full access to the worktree and can read files, write code, run commands, and use tools — subject to your permission settings.

Installing ACP Agents

Shellarium includes a built-in ACP agent registry. To install an ACP agent:

Open Settings (gear icon in the sidebar)
Go to the Agents tab
Browse the available agents from the ACP registry
Click Install next to the agent you want to use

Installed agents will appear as provider options when creating a new workspace. You can uninstall agents at any time from the same settings page.

Requirements for ACP agents

Some ACP agents require additional tools to be installed:

npx-based agents — require Node.js to be installed
uvx-based agents — require Python and uv to be installed
Binary agents — are downloaded and installed automatically

API keys for ACP agents

Some ACP agents require their own API keys (e.g., Codex CLI requires an OpenAI API key). Configure API keys in Settings → Providers.

Agent Output

The output panel shows:

Thinking — the agent’s reasoning process
Tool calls — files read, code written, commands executed
Permission requests — actions requiring your approval
Cost tracking — token usage and estimated cost

Tool-call handling includes parity for Cron-style and ScheduleWakeup flows, so scheduled follow-up actions are processed consistently.

MCP Authorization Flow

When an MCP server requires OAuth, Shellarium supports an in-app authorization flow from chat. You can authorize without leaving the app, and Shellarium validates the new auth state immediately.

For managed OAuth credentials, expired MCP tokens are refreshed automatically before agent start when a refresh token is available.

For the full provider-agnostic architecture (single MCP setup and shared auth across all agents), see MCP Integration.

Session Resumption

If an agent is interrupted or you want to send follow-up instructions, Shellarium supports session resumption. The agent picks up where it left off with full context preserved.

Replay Session

Completed agent sessions can be replayed as a demo. Click the Replay button to watch the full session output play back step by step — useful for demonstrations, reviews, or understanding how the agent solved a problem.

Chat Experience

Auto-collapse — completed turns collapse automatically to keep the conversation readable
Shared input history — your command history is shared across all chats and persists between sessions
Stderr output — agent stderr is captured and shown as a collapsible section in the output
Selection context actions — highlight text in chat and use Copy or nested Execute as task for fast follow-up runs
File mentions — file references in chat include richer context and open in dedicated closable tabs

Model Selection

You can choose which model to use for each workspace:

Claude Sonnet — fast and capable, good for most tasks
Claude Opus — most capable, best for complex tasks
Claude Haiku — fastest, good for simple tasks