DocsAgent Workflows

Agents

Git worktrees and Docker containers for AI agent isolation

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.

code

~/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 worktree

Why 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 in Settings > Agents:

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 Settings:

Open Settings > Agents
Click Create Agent
Choose branch and options

From Terminal:

bash

git worktree add ../my-project-worktrees/feature-x -b feature-x

Switching 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#

Settings > Agents - Right-click, select Remove
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.

Grouping Modes#

Switch how worktrees are grouped from the ⋯ menu at the bottom of the Agents navigator (a checkmark marks the active mode):

Mode	Layout
Group by Repository (default)	Worktrees grouped under their repository, then by pinned status and label
Sort by Recent Activity	A flat, time-bucketed list across all repositories, ordered by latest agent activity
Sort by Creation Date	The same flat list, bucketed and ordered strictly by when each worktree was created

Flat Views#

Both flat modes bucket worktrees 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

Sort by Recent Activity keeps your most recent work on top: a worktree moves up to a more recent bucket whenever its agent runs or you work in its terminal, and an agent waiting for your input floats to the top of its bucket.

Sort by Creation Date is a stable timeline: worktrees are bucketed and ordered by creation time (newest first), and agent activity never reshuffles them.

In either mode, 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.

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.

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`	All-in-one: Claude Code, Codex, and common agent tools
`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 > Agents > Network Mode.

Supported AI Agents#

Agentastic's public catalog includes 52 built-in agent definitions and auto-discovers them when installed. Here are some of the most popular:

Every agent runs in a real terminal. 24 of them can also run as a structured Chat transcript — 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.

Agentastic#

bash

brew install agentasticai/tap/agentastic

Our 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)#

bash

curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh

Prime 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)#

bash

npm install -g @anthropic-ai/claude-code

Codex (OpenAI)#

bash

npm install -g @openai/codex

Poolside#

bash

curl -fsSL https://downloads.poolside.ai/pool/install.sh | sh
pool login

Open Interpreter#

bash

curl -fsSL https://www.openinterpreter.com/install | sh

Command Code (Langbase)#

bash

npm i -g command-code

Gemini (Google)#

bash

npm install -g @google/gemini-cli

Antigravity (Google)#

bash

curl -fsSL https://antigravity.google/cli/install.sh | bash

Jules (Google)#

bash

npm install -g @google/jules

Grok Build (xAI)#

bash

curl -fsSL https://x.ai/cli/install.sh | bash

Muse Code (Meta)#

bash

curl -fsSL https://dev.meta.ai/install.sh | bash

Devin (Cognition)#

bash

curl -fsSL https://cli.devin.ai/install.sh | bash

Hermes Agent (Nous Research)#

bash

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Official docs • GitHub

Cursor#

bash

curl https://cursor.com/install -fsSL | bash

Cursor's terminal coding agent. Supports auto-approve (--yolo), resume (--continue), initial prompt, and sandbox control (--sandbox enabled|disabled). See the official docs.

GitHub Copilot#

bash

npm install -g @github/copilot

Junie (JetBrains)#

bash

curl -fsSL https://junie.jetbrains.com/install.sh | bash

OpenHands#

bash

uv tool install openhands

Letta Code#

bash

npm install -g @letta-ai/letta-code

Cortex Code (Snowflake)#

bash

curl -LsS https://ai.snowflake.com/static/cc-scripts/install.sh | sh

Aider#

bash

curl -LsSf https://aider.chat/install.sh | sh

MiMo Code#

bash

npm install --global --prefix "$HOME/.local" @mimo-ai/cli@latest

Qoder CLI#

bash

npm install --global --prefix "$HOME/.local" @qoder-ai/qodercli@latest

OpenClaude#

bash

npm install --global --prefix "$HOME/.local" @gitlawb/openclaude@latest

Ante#

bash

curl -fsSL https://ante.run/install.sh | ANTE_INSTALL_DIR="$HOME/.local/bin" bash

Agentastic 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#

bash

curl -fsSL https://omp.sh/install | sh -s -- --binary

Agentastic selects OMP's native binary installer so an older Bun installation cannot block setup.

OpenClaw#

bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix "$HOME/.local" --no-onboard

The 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`
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`	`curl -fsSL https://dev.meta.ai/install.sh \| bash`
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`	`npm install -g opencode-ai`
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`
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#

code

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:

bash

dev notify --title "Need input" --body "Should I apply this migration?"
dev browser snapshot
dev repomix --editor
dev create checkout-flow main

Outside the app, install the system-wide dev CLI from Agentastic -> Install Shell Integration...:

bash

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-auth
fix-login-bug
refactor-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 container logs in Settings > Agents

Agent not discovered#

Ensure the agent CLI is:

Installed globally
In your PATH
Executable (which agent-name)