Agent Home

Launch and manage AI coding agents from a single interface

Overview

Agent Home is your command center for launching AI coding agents. From a single interface, you can:

  • Write prompts for AI agents
  • Select which agents to run
  • Configure worktrees or containers
  • Launch multiple agents in parallel

Opening Agent Home

Open Agent Home by:

  • Clicking the Home icon in the Navigator sidebar
  • Using the Command Palette (Cmd+Shift+P) and typing "Agent Home"

The Prompt Card

The central prompt card is where you describe your task.

Writing Prompts

Type your instructions in the text area:

Add a REST API for user management:
- GET /users - list all users
- POST /users - create user
- GET /users/:id - get user by ID
- PUT /users/:id - update user
- DELETE /users/:id - delete user

Use Express.js and follow our existing patterns in src/api/

Tips for effective prompts:

  • Be specific about what you want
  • Mention technologies and patterns
  • Reference existing code for context
  • Break complex tasks into steps

File Mentions

Reference specific files by typing @:

  1. Type @ in the prompt
  2. Start typing a filename
  3. Select from the autocomplete list
  4. The file path is inserted as a mention

Mentioned files give the agent context about your codebase.

Image Attachments

Attach images (screenshots, diagrams, mockups) to your prompt:

  • Drag and drop images onto the prompt card
  • Click the photo icon to browse for images
  • Paste images from clipboard (Cmd+V)

Images are saved to the agent's prompt file for vision-capable agents.

Selecting Agents

Auto-Discovered Agents

Agentastic automatically detects installed AI agents:

  • Claude Code - If claude is in your PATH
  • Codex - If codex is in your PATH
  • Aider - If aider is in your PATH

Configured Agents

Add custom agents in Settings > Terminal > Startup Command.

Multiple Agents

Run multiple agents simultaneously:

  1. Click the agent selector
  2. Check multiple agents
  3. Adjust instance counts (1x, 2x, 3x)
  4. Each gets its own worktree

For example: Run 2 Claude agents and 1 Codex agent on different aspects of your task.

Configuration Options

Repository Selection

If multiple repositories are open, select which one the agent should work in.

Base Branch

Choose the branch to create the new worktree from:

  • Usually main or master
  • Can be any existing branch

Branch Name

Enter a name for the new branch:

  • A random city name is suggested (e.g., tokyo-847)
  • Or type your own descriptive name

Mode: Worktree vs Container

Choose the agent's environment:

Worktree Mode (default)

  • Agent runs directly on your machine
  • Faster to start
  • Full access to your tools

Container Mode

  • Agent runs in Docker
  • Maximum isolation
  • Reproducible environment

Container Image

When using Container mode, select a Docker image:

  • agentastic/soup - Pre-installed AI tools
  • node:22-bookworm - Node.js environment
  • Custom images you've added

Launching

Click Send (or press Enter) to launch.

Agentastic will:

  1. Create a git worktree for your branch
  2. Run setup scripts (if configured)
  3. Start the container (if using container mode)
  4. Open a terminal in the new environment
  5. Launch the AI agent with your prompt

After Launch

Monitoring Progress

  • The terminal shows the agent's output
  • Switch to the agent's worktree to see file changes
  • Use Cmd+Option+Down/Up to navigate worktrees

Multiple Tasks

Agent Home supports queuing multiple tasks:

  • Each launch creates a new worktree
  • Agents work in parallel
  • Track progress in the Agents navigator tab

Validation Warnings

Agent Home shows warnings if:

  • The branch name already exists
  • The base branch is not up to date
  • Docker is not running (for container mode)

Persistence

Agent Home remembers your selections:

  • Last used repository
  • Base branch preference
  • Selected agents
  • Mode (worktree/container)

Settings persist across sessions.

Keyboard Shortcuts

ActionShortcut
Submit promptEnter
New line in promptShift+Enter
Open Agent HomeCheck Command Palette

Tips

Start with One Agent

Get familiar with the workflow using a single agent before running multiple.

Use Descriptive Branch Names

Makes it easier to identify what each agent is working on.

Attach Context

Use @ mentions and image attachments to give agents the context they need.

Check Validation Warnings

Address any warnings before launching to avoid issues.

Troubleshooting

Agent Not Showing

Ensure the agent CLI is:

  1. Installed globally
  2. In your PATH
  3. Executable

Check with which agent-name.

Container Mode Unavailable

  1. Install Docker Desktop
  2. Start Docker
  3. Refresh Agent Home

Worktree Creation Failed

  • Branch name might already exist
  • Check git status for conflicts
  • Ensure write permissions