> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentastic.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Agents: git worktrees and Docker containers
> Agentastic runs each AI agent in its own isolated environment — a git worktree or a Docker container — so agents never interfere with your main workspace.
Every AI agent in Agentastic works inside its own isolated environment. Isolation means that multiple agents can edit code simultaneously without stepping on each other, and you can discard an agent's work without affecting anything else. Agentastic supports two isolation modes: **git worktrees** and **Docker containers**.
## Git worktrees
### What is a worktree?
A git worktree is a linked working copy of your repository. Unlike switching branches (which changes files inside a single directory), a worktree gives each branch its own complete directory on disk. Your main workspace stays untouched while an agent works in its own copy.
```text theme={null}
~/projects/
├── my-app/ # Your main workspace
└── my-app-worktrees/
├── feature-auth/ # Agent 1's worktree
├── feature-api/ # Agent 2's worktree
└── bugfix-login/ # Agent 3's worktree
```
Worktrees give you:
* **No file conflicts** — each agent edits its own copy of your files.
* **True parallel work** — multiple agents run simultaneously without waiting for each other.
* **Easy comparison** — diff the agent's branch against yours at any time.
* **Safe experimentation** — delete a worktree if you don't like the result, with no impact on main.
### Worktree storage locations
Configure where Agentastic creates worktrees 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 from repo root |
| Global | `~/worktrees/repo/branch-name` | Centralized management across repos |
### Creating a worktree
Click the **Home** icon in the Navigator sidebar.
Enter your task and choose a branch name. A random suggestion is provided.
Agentastic creates the worktree automatically before launching the agent.
Use `Cmd+,` to open Settings, then go to the Agents section.
Choose a branch name and any additional options.
Run the standard git command directly:
```bash theme={null}
git worktree add ../my-project-worktrees/feature-x -b feature-x
```
### Switching between worktrees
| Action | Shortcut |
| ------------------------- | ----------------- |
| Next agent / worktree | `Cmd+Option+Down` |
| Previous agent / worktree | `Cmd+Option+Up` |
You can also click directly on any worktree in the **Agents** tab of the Navigator (`Cmd+4`).
### Removing a worktree
* **From Settings** — open **Settings > Agents**, right-click the worktree, and select **Remove**.
* **From the terminal** — run `git worktree remove path/to/worktree`.
* **Clean up stale references** — run `git worktree prune` after manual deletion.
## Docker containers
For maximum isolation, you can run agents inside Docker containers. Each container has its own filesystem, network stack, and pre-installed tooling, with your worktree mounted at `/workspace`.
### Enabling containers
Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop/). Start it and wait for it to finish initializing.
Click the **Home** icon in the Navigator sidebar.
Toggle **Mode** from "Worktree" to "Container".
Choose a pre-defined image or enter a custom one.
Click **Send**. Agentastic pulls the image if needed and starts the container.
### Available images
| Image | Description |
| -------------------------------------- | --------------------------------------------------- |
| `agentastic/soup` | All-in-one: Claude Code, Codex, Aider pre-installed |
| `docker/sandbox-templates:claude-code` | Official Claude Code sandbox |
| `paulgauthier/aider-full` | Aider AI assistant |
| `node:22-bookworm` | Node.js 22 environment |
| `python:3.12-bookworm` | Python 3.12 environment |
### Container mounts
Agentastic automatically mounts the following paths into every container:
| Host path | Container path | Purpose |
| ------------------ | ------------------ | -------------------------------------- |
| Your worktree | `/workspace` | The code the agent edits |
| Container home dir | `/root` | Tool state persistence across runs |
| `~/.gitconfig` | `/root/.gitconfig` | Git identity (optional) |
| `~/.ssh/` | `/root/.ssh/` | SSH keys for git operations (optional) |
### Network modes
| Mode | Description |
| ---------------- | ------------------------------------- |
| Bridge (default) | Full network access |
| Restricted | Limited to specific allowed endpoints |
| None | No network access |
Change the network mode in **Settings > Agents > Network Mode**.
## All built-in agents
Agentastic ships with 33 built-in agent definitions and auto-discovers them when their CLI is installed and available in your `PATH`.
| Agent | CLI command | Install |
| -------------- | ------------------ | -------------------------------------------------------------------------------------------------------- |
| Agentastic | `agentastic exec` | Built-in |
| Claude Code | `claude` | `npm install -g @anthropic-ai/claude-code` |
| Codex | `codex` | `npm install -g @openai/codex` |
| Command Code | `cmd` | `npm i -g command-code` |
| Cursor | `agent` | `curl https://cursor.com/install -fsSL \| bash` |
| Gemini | `gemini` | `npm install -g @google/gemini-cli` |
| 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 @sourcegraph/amp@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 | `kilocode` | `npm install -g @kilocode/cli` |
| Kiro | `kiro-cli` | `curl -fsSL https://cli.kiro.dev/install \| bash` |
| Rovo Dev | `acli rovodev run` | Atlassian CLI |
| Cline | `cline` | `npm install -g cline` |
| Continue | `cn` | `npm install -g @continuedev/cli` |
| Codebuff | `codebuff` | `npm install -g codebuff` |
| Mistral Vibe | `vibe` | `curl -LsSf https://mistral.ai/vibe/install.sh \| bash` |
| Pi | `pi` | `npm install -g @mariozechner/pi-coding-agent` |
| Aider | `aider` | `pip install aider-chat` |
| Autohand Code | `autohand` | `curl -fsSL https://autohand.ai/install.sh \| bash` |
| Letta Code | `letta` | `npm install -g @letta-ai/letta-code` |
| OpenHands | `openhands` | `pip install openhands-ai` |
| 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` | `pip install mini-swe-agent` |
| OB-1 | `ob1` | `curl -fsSL https://dashboard.openblocklabs.com/install \| bash` |
### Custom agents
Add any terminal-based AI agent in **Settings > Connections**. The command must accept a prompt (either as an argument or interactively).
## Agent lifecycle
From launch to cleanup, every agent follows this lifecycle:
```text theme={null}
1. Create
└── Worktree created (or container started)
└── Setup script runs
└── Agent CLI launched
2. Work
└── Agent receives your prompt
└── Agent makes file changes
└── You monitor progress in the terminal
3. Review
└── View diff of changes
└── Run AI code review (optional)
└── Test in the agent's environment
4. Complete
└── Push branch and create a PR, or
└── Merge directly, or
└── Discard the changes
5. Cleanup
└── Remove the worktree
└── Delete the branch (optional)
└── Container is removed (if used)
```
## Best practices
### Use descriptive branch names
Names like `feature-user-auth`, `fix-login-bug`, and `refactor-api-client` make it clear what each agent is working on when you have several running in parallel.
### One task per agent
Keep each agent's scope focused. Rather than asking one agent to "build the whole feature," split it into:
* "Add the database schema for users"
* "Create the API endpoints"
* "Build the frontend components"
### Always review before merging
Before merging any agent's work:
1. Open the Diff Viewer to inspect changes.
2. Run AI code review for automated feedback.
3. Test the changes in the agent's environment.
4. Confirm there are no regressions.
### Clean up regularly
Remove old worktrees to free disk space, keep the agent list manageable, and avoid branch name conflicts. Use **Settings > Agents** or run `git worktree prune` in the terminal.
## Troubleshooting
A branch can only exist in one worktree at a time. Either remove the existing worktree that has the branch checked out, or choose a different branch name for the new agent.
1. Verify Docker Desktop is running.
2. Check that the image exists locally: `docker images`.
3. Review container logs in **Settings > Agents**.
Agentastic discovers agents by scanning your `PATH`. Ensure the agent CLI is:
1. Installed globally (not just locally in a project).
2. Accessible in your `PATH` — confirm with `which `.
3. Executable (`chmod +x` if needed).