Agents
Isolate every AI agent in its own git worktree or Docker container, organize them in the navigator, and follow each one through its lifecycle.
On this page
- Overview
- Git Worktrees
- What is a Worktree?
- Why Worktrees?
- Worktree Storage Locations
- Creating a Worktree
- Switching Between Worktrees
- Removing a Worktree
- Organizing Agents in the Navigator
- Ordering the Sections
- Group By and Sort By
- Flat Views
- Filtering and Hiding Sections
- Renaming Agents
- Docker Containers
- Enabling Containers
- Available Images
- Container Mounts
- Network Modes
- Supported AI Agents
- Agentastic
- Prime Agent (Prime Intellect)
- Claude Code (Anthropic)
- Codex (OpenAI)
- Poolside
- Reason (Reason Machines)
- Open Interpreter
- Command Code (Langbase)
- Gemini (Google)
- Antigravity (Google)
- Jules (Google)
- Grok Build (xAI)
- Muse Code (Meta)
- Devin (Cognition)
- Hermes Agent (Nous Research)
- Cursor
- GitHub Copilot
- Junie (JetBrains)
- OpenHands
- Letta Code
- Cortex Code (Snowflake)
- Aider
- MiMo Code
- Qoder CLI
- OpenClaude
- Ante
- Oh My Pi
- OpenClaw
- All Built-in Agents
- Custom Agents
- Picking the right agent
- Agent Lifecycle
- CLI Control
- Best Practices
- Naming Conventions
- One Task Per Agent
- Review Before Merging
- Clean Up Regularly
- Troubleshooting
- "Branch already checked out"
- Container won't start
- Agent not discovered
Overview#
Agents in Agentastic are isolated development environments where AI coding assistants work without interfering with your main workspace. Each agent gets either a git worktree (a separate checkout of your repository) or a Docker container (a fully isolated environment).
Git Worktrees#
What is a Worktree?#
A git worktree is a linked working copy of your repository. Unlike branches (which share a single working directory), worktrees give each branch its own complete directory with all your files.
~/projects/
├── my-app/ # Main worktree (your workspace)
├── my-app-worktrees/
│ ├── feature-auth/ # Agent 1's worktree
│ ├── feature-api/ # Agent 2's worktree
│ └── bugfix-login/ # Agent 3's worktreeWhy Worktrees?#
- No conflicts - Each agent edits its own copy of files
- Parallel work - Multiple agents can work simultaneously
- Easy comparison - Diff between your work and agent's work
- Safe experimentation - Delete a worktree if you don't like the results
Worktree Storage Locations#
Configure where worktrees are created with Create workspaces in Settings > Workspaces:
| Location | Path Pattern | Best For |
|---|---|---|
| Inside Repo | repo/.worktree/branch-name | Self-contained projects |
| Adjacent (Default) | repo-worktrees/branch-name | Clean separation |
| Global | ~/worktrees/repo/branch-name | Centralized management |
Creating a Worktree#
From Agent Home:
- Open Agent Home
- Enter your prompt and branch name
- Click Send - the worktree is created automatically
From the New Workspace dialog:
- Choose File > New Workspace… (Cmd+Shift+T), or click + at the bottom of the navigator sidebar
- Choose branch and options
- Click Create
From Terminal:
git worktree add ../my-project-worktrees/feature-x -b feature-xSwitching Between Worktrees#
| Action | Shortcut |
|---|---|
| Switch Worktree | Ctrl+Tab |
| Next Agent | Cmd+Option+Down |
| Previous Agent | Cmd+Option+Up |
Or use the Navigator sidebar to click on a worktree.
Removing a Worktree#
- Navigator sidebar - Right-click the worktree, select Delete Workspace
- Terminal:
git worktree remove path/to/worktree - Cleanup stale refs:
git worktree prune
Organizing Agents in the Navigator#
Open the Agents tab in the Navigator with Cmd+4. Each row shows the agent's icon, an activity indicator when its agent is running, and a cloud badge for cloud worktrees.
Ordering the Sections#
Under Group by Repository, drag a repository header up or down to put your repositories in whatever order you work in. The Chats group — your managers and standalone chats — drags the same way, so you can pull it to the top instead of leaving it under every repository. Both orders are remembered per window. A group left at the bottom stays at the bottom as you open more repositories.
Group By and Sort By#
The ⋯ menu at the bottom of the Agents navigator has a Group By submenu and a Sort By submenu, each with a checkmark on the current choice. The two are independent, so any grouping works with any order: group by project and sort by creation date, for example. Settings > Sidebar offers the same two choices.
Group By decides which sections worktrees are filed under:
| Group By | Layout |
|---|---|
| Repository (default) | One section per repository, with its pinned worktrees, labels, and the rest. The only layout that shows labels |
| Server | One section per machine the agents run on: This Mac, each SSH server, and Cloud. A server's header shows when it is connecting or offline |
| Project | One section per project. Checkouts of the same repository on different servers share a section, matched by their folder name |
| Flat | One list across all repositories |
Sort By decides the order inside each section:
| Sort By | Order |
|---|---|
| Name | A to Z by worktree folder name |
| Creation Date (default) | Newest first. Agent activity never moves a row |
| Recent Activity | Agents waiting for your input first, then the most recent agent activity |
Pinned worktrees always lead their section, and archived ones fold into an Archived disclosure at its foot. Under Server, Project, and Flat, each row names its repository; under Project it also names its server.
Flat Views#
A Flat list sorted by Creation Date or Recent Activity is divided into time ranges, so you don't have to hunt for recent work:
- Pinned — worktrees you've pinned, always first
- Today
- Last 7 Days
- Last 30 Days
- Backlog — nothing in the last 30 days
- Archived — worktrees you've archived
Sorted by Recent Activity, your most recent work stays on top: a worktree moves up to a more recent range whenever its agent runs or you work in its terminal, and an agent waiting for your input floats to the top of its range.
Sorted by Creation Date, it is a stable timeline: worktrees are filed and ordered by creation time (newest first), and agent activity never reshuffles them.
Sorted by Name, the flat list has no dates to divide it by: pinned worktrees come first, then everything else from A to Z.
In any layout, pin an agent (right-click → Pin) to keep it at the top, and Archive finished work to tuck it into the Archived section without deleting it.
Filtering and Hiding Sections#
The same ⋯ menu has a Show submenu: All Agents (the default), Working (running, or waiting for your answer), or With Pull Requests (an open or merged pull request). While a filter is on, a chip beside the menu names it; click the chip to show every agent again.
Configure Sidebar, at the bottom of that menu, shows or hides the sidebar's Spaces, Chats, and Workspaces sections.
Renaming Agents#
Give an agent a shorter, friendlier name without touching anything technical. Right-click its row in the Agents navigator and choose Rename. The custom name shows on the first line of the row; the Git branch stays on the second line.
Renaming is display-only — it never renames the branch, the worktree directory, the terminal, or the running agent process. The Rename dialog applies immediately; renames made through the API or dev agent rename land with a brief Braille reveal animation in the sidebar (skipped if you have Reduce Motion turned on).
A rename also never moves the row. Sidebar order is keyed to the worktree itself, so an agent stays put — and stays at the same ⌥⌘↑/↓ and ⌥⌘1–9 position — when you rename it or when an automatic naming task names it for you.
Every kind of agent renames the same way. Chats support the workflow in the sidebar's Chats section. Right-click a chat and choose Rename, then enter a Display Name. The dialog shows the original Agent Name, which stays unchanged. Leave the display name blank to restore the agent name, or hold Option to see the agent name in the sidebar. Custom names persist when you reopen the app and take precedence over automatic naming.
Manager agents, at the top of the same Chats section, rename from their own right-click menu. The dialog is the same, and so is the promise: the manager's home repository and everything in it stay put. Spaces become dashes, a blank field keeps the current name, and the result matches the Name field in the manager's settings. See Manager Agents for the rest of that menu.
Docker Containers#
For maximum isolation, run agents inside Docker containers. Each container has:
- Isolated filesystem and network
- Pre-installed AI tools
- Your worktree mounted at
/workspace - Configurable resource limits
Enabling Containers#
- Install Docker Desktop
- Open Agent Home
- Toggle Mode from "Worktree" to "Container"
- Select a container image
- Launch your agent
Available Images#
| Image | Description |
|---|---|
agentastic/cloud-base | Claude Code, Codex, Amp, Gemini, OpenCode, Droid, Fx, Agentastic, and Repomix |
docker/sandbox-templates:claude-code | Official Claude Code sandbox |
paulgauthier/aider-full | Aider AI assistant |
node:22-bookworm | Node.js environment |
python:3.12-bookworm | Python environment |
Container Mounts#
Containers automatically get these mounts:
| Host | Container | Purpose |
|---|---|---|
| Your worktree | /workspace | Code editing |
| Container home dir | /root | Tool state persistence |
~/.gitconfig | /root/.gitconfig | Git identity (optional) |
~/.ssh/ | /root/.ssh/ | SSH keys (optional) |
Network Modes#
| Mode | Description |
|---|---|
| Bridge | Full network access (default) |
| Restricted | Limited to specific endpoints |
| None | No network access |
Configure in Settings > Containers > Network access, where the modes appear as Full access, API only, and None.
Supported AI Agents#
Agentastic's public catalog includes 55 built-in agent definitions and auto-discovers them when installed. Here are some of the most popular:
Every agent runs in a real terminal. 31 of them can also run as a structured Chat transcript — Agentastic, Claude Code, and Codex through native integrations, and everything that speaks Agent Client Protocol through a shared ACP transport. Pick the default per agent under Settings > Agents > Launch Interface, and flip any running session between the two at any time.
ACP Chat currently owns a local macOS process. In Container, Remote, and Cloud targets, ACP-backed agents stay in their terminal interface so their process and file operations run inside the selected target rather than on the Mac.
Agentastic#
curl -fsSL https://releases.agentastic.ai/agent/install.sh | shbrew install agentasticai/tap/agentasticOur own terminal coding agent. Supports auto-approve (--dangerously-bypass-approvals-and-sandbox), resume (resume --last), an initial prompt, model and reasoning-effort selection, and code review (agentastic review). It also has a non-interactive agentastic exec mode for scripting. See the agent page.
Prime Agent (Prime Intellect)#
curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | shPrime Intellect's open-source RLM agent. Agentastic supports positional prompts, latest-session resume with --continue, native thinking levels, ACP Chat, and project skills. See the provider reference.
Claude Code (Anthropic)#
npm install -g @anthropic-ai/claude-codeCodex (OpenAI)#
npm install -g @openai/codexPoolside#
curl -fsSL https://downloads.poolside.ai/pool/install.sh | sh
pool loginReason (Reason Machines)#
curl -fsSL https://reasonmachines.com/install.sh | bash
reason loginReason Machines' autonomous software engineer: the agent runs in Reason's cloud and its commands run in your worktree. Agentastic types your opening prompt into the interactive session and passes the model and reasoning effort you pick with --model and --reasoning-effort. Reason runs in Terminal only, since it has no ACP mode. See the provider reference.
Open Interpreter#
curl -fsSL https://www.openinterpreter.com/install | shCommand Code (Langbase)#
npm i -g command-codeLangbase's taste-aware coding agent. Agentastic supports positional prompts, resume with --continue, auto-approve with --yolo, plan mode with --plan, and ACP Chat through command-code acp (Command Code 1.74 or later). See the provider reference.
Gemini (Google)#
npm install -g @google/gemini-cliAntigravity (Google)#
curl -fsSL https://antigravity.google/cli/install.sh | bashJules (Google)#
npm install -g @google/julesGrok Build (xAI)#
curl -fsSL https://x.ai/cli/install.sh | bashMuse Code (Meta)#
curl -fsSL https://dev.meta.ai/install.sh | bash &&
npm_config_engine_strict=true npm install --global --prefix "$HOME/.local" \
--ignore-scripts --no-audit --no-fund @bex-co/muse-code-acp@0.9.1Devin (Cognition)#
curl -fsSL https://cli.devin.ai/install.sh | bashHermes Agent (Nous Research)#
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bashCursor#
curl https://cursor.com/install -fsSL | bashCursor's terminal coding agent. Supports auto-approve (--yolo), resume (--continue), initial prompt, and sandbox control (--sandbox enabled|disabled). See the official docs.
GitHub Copilot#
npm install -g @github/copilotJunie (JetBrains)#
curl -fsSL https://junie.jetbrains.com/install.sh | bashOpenHands#
uv tool install openhandsLetta Code#
npm install -g @letta-ai/letta-codeCortex Code (Snowflake)#
curl -LsS https://ai.snowflake.com/static/cc-scripts/install.sh | shAider#
curl -LsSf https://aider.chat/install.sh | shMiMo Code#
npm install --global --prefix "$HOME/.local" @mimo-ai/cli@latestQoder CLI#
npm install --global --prefix "$HOME/.local" @qoder-ai/qodercli@latestOpenClaude#
npm install --global --prefix "$HOME/.local" @gitlawb/openclaude@latestAnte#
curl -fsSL https://ante.run/install.sh | ANTE_INSTALL_DIR="$HOME/.local/bin" bashAgentastic places these npm packages and Ante in ~/.local/bin, which it checks directly. This prevents a successful install from disappearing into a version-manager-specific npm prefix that is missing from the app's shell PATH.
Oh My Pi#
curl -fsSL https://omp.sh/install | sh -s -- --binaryAgentastic selects OMP's native binary installer so an older Bun installation cannot block setup.
OpenClaw#
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix "$HOME/.local" --no-onboardThe CLI-only installer supplies a supported Node runtime and places openclaw in ~/.local/bin, which Agentastic detects directly.
All Built-in Agents#
| Agent | CLI Command | Install |
|---|---|---|
| Agentastic | agentastic | brew install agentasticai/tap/agentastic |
| Prime Agent | prime-agent | curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh |
| Claude Code | claude | npm install -g @anthropic-ai/claude-code |
| Codex | codex | npm install -g @openai/codex |
| Warp Agent CLI | warp | curl -fsSL https://app.warp.dev/download/agent-cli | bash |
| Poolside | pool | curl -fsSL https://downloads.poolside.ai/pool/install.sh | sh |
| Reason | reason | curl -fsSL https://reasonmachines.com/install.sh | bash |
| Open Interpreter | interpreter | curl -fsSL https://www.openinterpreter.com/install | sh |
| Command Code | command-code | npm i -g command-code |
| Cursor | cursor-agent | curl https://cursor.com/install -fsSL | bash |
| Gemini | gemini | npm install -g @google/gemini-cli |
| Antigravity | agy | curl -fsSL https://antigravity.google/cli/install.sh | bash |
| Jules | jules | npm install -g @google/jules |
| Grok Build | grok | curl -fsSL https://x.ai/cli/install.sh | bash |
| Muse Code | muse | Meta installer + pinned @bex-co/muse-code-acp |
| Devin | devin | curl -fsSL https://cli.devin.ai/install.sh | bash |
| Hermes Agent | hermes | curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash |
| Qwen Code | qwen | npm install -g @qwen-code/qwen-code |
| Droid | droid | curl -fsSL https://app.factory.ai/cli | sh |
| Amp | amp | npm install -g @ampcode/cli@latest |
| OpenCode | opencode | curl -fsSL https://opencode.ai/install | bash |
| GitHub Copilot | copilot | npm install -g @github/copilot |
| Charm | crush | npm install -g @charmland/crush |
| Auggie | auggie | npm install -g @augmentcode/auggie |
| Goose | goose | curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | bash |
| Kimi | kimi | uv tool install kimi-cli |
| Kilocode | kilo | npm install -g @kilocode/cli |
| Kiro | kiro-cli | curl -fsSL https://cli.kiro.dev/install | bash |
| Rovo Dev | acli rovodev run | brew install atlassian/acli/acli && acli rovodev auth login |
| Cline | cline | npm install -g cline |
| Continue | cn | npm install -g @continuedev/cli |
| Codebuff | codebuff | npm install -g codebuff |
| Freebuff | freebuff | npm install -g freebuff |
| Mistral Vibe | vibe | curl -LsSf https://mistral.ai/vibe/install.sh | bash |
| Pi | pi | npm install -g @mariozechner/pi-coding-agent |
| Aider | aider | curl -LsSf https://aider.chat/install.sh | sh |
| Autohand Code | autohand | curl -fsSL https://autohand.ai/install.sh | bash |
| Letta Code | letta | npm install -g @letta-ai/letta-code |
| OpenHands | openhands | uv tool install openhands |
| Cortex Code | cortex | curl -LsS https://ai.snowflake.com/static/cc-scripts/install.sh | sh |
| Junie | junie | curl -fsSL https://junie.jetbrains.com/install.sh | bash |
| mini-SWE-agent | mini | uv tool install mini-swe-agent |
| OB-1 | ob1 | curl -fsSL https://dashboard.openblocklabs.com/install | bash |
| MiMo Code | mimo | npm install --global --prefix "$HOME/.local" @mimo-ai/cli@latest |
| Qoder CLI | qodercli | npm install --global --prefix "$HOME/.local" @qoder-ai/qodercli@latest |
| OpenClaude | openclaude | npm install --global --prefix "$HOME/.local" @gitlawb/openclaude@latest |
| Ante | ante | curl -fsSL https://ante.run/install.sh | ANTE_INSTALL_DIR="$HOME/.local/bin" bash |
| Oh My Pi | omp | curl -fsSL https://omp.sh/install | sh -s -- --binary |
| OpenClaw | openclaw tui --local | curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix "$HOME/.local" --no-onboard |
| CodeBuddy Code | codebuddy | npm install -g @tencent-ai/codebuddy-code |
| Zero | zero | npm install -g @gitlawb/zero |
| fx | fx | curl -fsSL https://fx.sh/setup.sh | bash |
| Jcode | jcode | curl -fsSL https://jcode.sh/install | bash |
| Yolop | yolop | brew install everruns/tap/yolop |
| CodeRabbit (review) | coderabbit | curl -fsSL https://cli.coderabbit.ai/install.sh | sh |
| Greptile (review) | greptile | curl -fsSL https://greptile.com/cli/install | bash |
Custom Agents#
Add any TUI agent in Settings > Connections. The command should accept a prompt or work interactively.
Picking the right agent#
Not sure which agent fits your workflow? Compare the popular options:
- Claude Code vs Codex — Anthropic vs OpenAI's coding CLIs
- Best Claude Code alternative — when you need something other than Claude
- Best Codex alternative — Codex CLI alternatives
- Best Cursor alternative — moving off Cursor
- Browse all alternatives — every tool in the stack
Agent Lifecycle#
1. Create
└── Worktree created (or container started)
└── Setup script runs
└── Agent CLI launched
2. Work
└── Agent receives your prompt
└── Agent makes changes
└── You monitor progress
3. Review
└── View diff of changes
└── Run code review (optional)
└── Test in agent's environment
4. Complete
└── Push and create PR, or
└── Merge directly, or
└── Discard changes
5. Cleanup
└── Remove worktree
└── Delete branch (optional)
└── Container removed (if used)CLI Control#
Agentastic agents can be controlled programmatically. (To give an agent a friendlier name, see Renaming Agents above.)
Inside Agentastic terminals, the internal dev CLI is injected automatically:
dev notify --title "Need input" --body "Should I apply this migration?"
dev browser snapshot
dev repomix --editor
dev create checkout-flow mainOutside the app, install the system-wide dev CLI from Agentastic → Command Line Integration…:
dev agent create --repo ~/code/my-app --agent codex --prompt "Fix the failing checkout tests."
dev --json agents
dev tail <terminal_id> 80
dev send <terminal_id> "Run the focused tests again."See Internal dev CLI, System-wide dev CLI, and Programmatic Control.
Best Practices#
Naming Conventions#
Use descriptive branch names:
feature-user-authfix-login-bugrefactor-api-client
One Task Per Agent#
Keep tasks focused. Instead of "build the whole feature," try:
- "Add the database schema for users"
- "Create the API endpoints"
- "Build the frontend components"
Review Before Merging#
Always:
- Check the diff
- Run AI code review
- Test the changes
- Verify no regressions
Clean Up Regularly#
Remove old worktrees to:
- Free disk space
- Keep the agent list manageable
- Avoid branch name conflicts
Troubleshooting#
"Branch already checked out"#
A branch can only exist in one worktree. Either remove the existing worktree or use a different branch name.
Container won't start#
- Verify Docker Desktop is running
- Check image exists:
docker images - Review the container's logs with your runtime, for example
docker logs agentastic-<branch>
Agent not discovered#
Ensure the agent CLI is:
- Installed globally
- In your PATH
- Executable (
which agent-name)