Workspaces

Workspaces are the core organizational unit in Shellarium. Each workspace represents a single task assigned to an AI agent, running in a completely isolated environment.

Git Worktrees

Every workspace creates a git worktree — a separate working directory linked to the same repository. This means:

• No conflicts — multiple agents can modify the same files simultaneously without interfering with each other
• Clean state — each agent starts with a clean copy of your branch
• Easy cleanup — deleting a workspace removes the worktree automatically

Worktrees are stored in the .shellarium/worktrees/ directory inside your repository.

Workspace Lifecycle

1. Created — workspace is set up with a name, description, and base branch
2. Running — an AI agent is actively working on the task
3. Completed — the agent has finished; changes are ready for review
4. Merged — changes have been merged into the target branch

Creating Workspaces

You can create a workspace in several ways:

• From scratch — click + and describe the task
• From a GitHub issue — import an issue directly as a workspace
• From a pull request — create a workspace linked to an existing PR

Workspace Settings

Each workspace supports:

• Base branch — the branch to create the worktree from
• Permission mode — normal, auto, or brave
• Agent model — which AI model to use (Claude Sonnet, Opus, etc.)