DocsAgent Workflows
View as Markdown

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"

Quick Agent#

Quick Agent is a lightweight version of Agent Home for when you already know which branch you want to work in. Instead of opening the full tab, a small floating panel appears right in the editor area with a single prompt field: "What should we do in branch-name?"

Quick Agent appears:

  • When you click the Quick Agent tile on an empty editor pane
  • Automatically after you create a new worktree, so you can hand off a task the moment the worktree is ready

It's skipped for container worktrees — a quick launch runs locally on your Mac, and silently bypassing the container's isolation would be surprising, so those worktrees open straight into a terminal instead.

Type your task and press Enter to launch, or click More options… to expand into the full Agent Home with repository, branch, and mode controls.

The Prompt Card#

The central prompt card is where you describe your task.

Writing Prompts#

Type your instructions in the text area:

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

Attachment Previews#

Everything you attach to a prompt appears as a compact chip in a single row above the agent and mode controls — mentioned files, images, skills, and linked Linear or Sentry issues. Hover any chip to preview its contents inline, without opening another picker or losing your place in the prompt:

  • Images show a thumbnail.
  • Files show a snippet of their text.
  • Skills render their SKILL.md as formatted Markdown in a scrollable reading area.
  • Linear and Sentry issues show the ticket or error details.

The preview stays open long enough to move your pointer into it and scroll, while each chip's detach (✕) button stays outside the preview target so it keeps working.

Selecting Agents#

Auto-Discovered Agents#

Agentastic ships 40 built-in agent definitions and automatically detects the installed CLIs, including:

  • Claude Code - If claude is in your PATH
  • Codex - If codex is in your PATH
  • Command Code - If cmd is in your PATH
  • Gemini - If gemini is in your PATH
  • Cursor - If cursor-agent is in your PATH
  • GitHub Copilot - If copilot is in your PATH
  • Junie - If junie is in your PATH
  • OpenHands - If openhands is in your PATH
  • Letta Code - If letta is in your PATH
  • Cortex Code - If cortex is in your PATH
  • Aider - If aider is in your PATH
  • And 20+ more (see Supported Agents)

Configured Agents#

Add custom agents in Settings > Connections.

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/cloud-base - 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