FAQ
General
Section titled “General”What is Shellarium?
Section titled “What is Shellarium?”Shellarium is a desktop application for macOS that lets you run multiple AI coding agents in parallel. Each agent works in an isolated git worktree, and you review and merge their changes from a unified dashboard.
Is Shellarium free?
Section titled “Is Shellarium free?”Shellarium is free during the public beta. Future pricing has not been announced.
What operating systems are supported?
Section titled “What operating systems are supported?”Currently macOS 13 (Ventura) and later. Windows and Linux support are planned for the future.
AI Agents
Section titled “AI Agents”Which AI providers are supported?
Section titled “Which AI providers are supported?”Shellarium natively supports Claude Code (Anthropic). Additionally, any ACP-compatible agent can be installed from the built-in registry — including Codex CLI (OpenAI), Aider, and others. Go to Settings → Agents to browse and install available agents. Note that ACP support is in early stages and not all providers have been thoroughly tested.
Do I need my own API key?
Section titled “Do I need my own API key?”Yes. You need an API key or subscription for the AI provider you want to use. Shellarium does not provide AI credits.
Can I run multiple agents at the same time?
Section titled “Can I run multiple agents at the same time?”Yes — that’s the core feature. Each agent runs in its own git worktree, so there are no conflicts. You can run as many agents as your system resources allow.
Git & GitHub
Section titled “Git & GitHub”Does Shellarium modify my repository?
Section titled “Does Shellarium modify my repository?”Shellarium creates worktrees inside .shellarium/worktrees/ in your repository root. This directory is automatically added to .gitignore. Your main working tree is never modified by agents.
Where is workspace data stored?
Section titled “Where is workspace data stored?”Workspace state, agent output, and event queue are stored in a local SQLite database inside the .shellarium/ directory. This is more reliable than the previous file-based storage and survives app restarts cleanly.
Do I need GitHub?
Section titled “Do I need GitHub?”A GitHub account is required for login. GitHub CLI (gh) is needed for PR/issue integration but is optional for core functionality.
What happens if there are merge conflicts?
Section titled “What happens if there are merge conflicts?”Shellarium checks for conflicts before merging. If conflicts exist, you’ll see a warning and can resolve them manually before proceeding.