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 auto-discovers these agents if installed:

Claude Code (Anthropic)

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

Requires ANTHROPIC_API_KEY environment variable.

Codex (OpenAI)

# Install from OpenAI

Requires OPENAI_API_KEY environment variable.

Aider

pip install aider-chat

Custom Agents

Add any TUI agent in Settings > Terminal > Startup Command. 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)