Agents

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:

1. Open Agent Home
2. Enter your prompt and branch name
3. Click Send - the worktree is created automatically

From Settings:

1. Open Settings > Agents
2. Click Create Agent
3. 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

1. Settings > Agents - Right-click, select Remove
2. Terminal: git worktree remove path/to/worktree
3. Cleanup stale refs: git worktree prune

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

1. Install Docker Desktop
2. Open Agent Home
3. Toggle Mode from "Worktree" to "Container"
4. Select a container image
5. Launch your agent

Available Images

Image	Description
agentastic/soup	All-in-one: Claude Code, Codex, Aider
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 33 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

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
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.

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)

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:

1. Check the diff
2. Run AI code review
3. Test the changes
4. 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

1. Verify Docker Desktop is running
2. Check image exists: docker images
3. Review container logs in Settings > Agents

Agent not discovered

Ensure the agent CLI is:

1. Installed globally
2. In your PATH
3. Executable (which agent-name)