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.

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

Claude Code (Anthropic)#

bash

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

Codex (OpenAI)#

bash

npm install -g @openai/codex

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

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

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`
Open Interpreter	`interpreter`	`curl -fsSL https://www.openinterpreter.com/install \| sh`
Command Code	`cmd`	`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`
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`	`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`
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.

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

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)