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.

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

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

Switching Between Worktrees

Action	Shortcut
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 Chronologically	A flat, time-bucketed list across all repositories

Chronological View

Sort Chronologically keeps your most recent work on top by bucketing worktrees into time ranges, so you don't have to hunt for what you touched today:

Pinned — worktrees you've pinned, always first
Today — active in the last day
Last 7 Days
Last 30 Days
Backlog — worktrees with no recent activity
Archived — worktrees you've archived

A worktree moves up to a more recent bucket whenever its agent runs or you work in its terminal. Pin an agent (right-click → Pin) to keep it at the top regardless of recency, and Archive finished work to tuck it into the Archived section without deleting it.

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 ships with 36 built-in agent definitions and auto-discovers them when installed. Here are some of the most popular:

Claude Code (Anthropic)

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

Codex (OpenAI)

npm install -g @openai/codex

Command Code (Langbase)

npm i -g command-code

Gemini (Google)

npm install -g @google/gemini-cli

Grok Build (xAI)

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

Devin (Cognition)

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

Hermes Agent (Nous Research)

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

Official docs • GitHub

Cursor

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

npm install -g @github/copilot

Junie (JetBrains)

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

OpenHands

pip install openhands-ai

Letta Code

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

Cortex Code (Snowflake)

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

Aider

pip install aider-chat

All Built-in Agents

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`
Grok Build	`grok`	`curl -fsSL https://x.ai/cli/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 @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 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.

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 --agents claude,codex

Outside the app, install the system-wide dev CLI from Agentastic -> Install Shell 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-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)