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
  • Pressing Cmd+Shift+K
  • 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 press Cmd+K or choose View > Show Quick Agent
  • 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.

Agent Chat Panels#

Run agents as chats — not just terminals — in dedicated panels that live alongside the editor. Open the Agent Chat panel in the navigator with Cmd+5, or use the matching chat surface in the Utility Area at the bottom of the window. Each panel keeps its own independent tabs, so you can run several agent sessions in parallel in the active worktree.

Agentastic's Chat transcript — tool calls collapsed to one line each, an edited-files card with line counts, Undo, and Review, and clickable file links in the response

  • Pick your setup per chat — choose the provider, model, thinking level, and any run mode that every selected provider can enforce. Unsupported auto-approve and plan choices are hidden.
  • Terminal or transcript — flip any chat between the raw Terminal and a clean Chat transcript at any time without interrupting the agent.
  • Answer without leaving Chat — permission requests arrive as approval cards with the agent's own options, and questions an agent asks arrive as selectable choices. Anything the agent leaves open to freeform text you can just type.
  • Steer or queue follow-ups — while an agent is working, sending normally adds the message to the regular queue. For Codex and ACP agents that advertise steering, hold Option and the composer changes to Steer the current turn; send while it is held to deliver the message into the live turn. If that turn finishes first, the message falls back to the visible queue. Queued messages can be edited, reordered, sent next, or deleted before the agent sees them.
  • Promote to the editor — drag a running chat from either panel into the editor — the center, a split zone, or an exact tab position — to give it a full editor tab. The live session, model choice, and terminal move with it; nothing restarts.
  • Counted like any other agent — a chat session registers with its worktree the same way a terminal agent does: it appears in the Inspector's Agents card and the sidebar's agent deck, and it can serve as the worktree's primary agent.
  • Restored where you left off — panel chats, their selected tabs, display mode, and layout are saved across restarts and crash recovery.

Launch Interface#

Every agent has a Launch Interface preference under Settings > Agents that decides which surface a new launch opens in:

PreferenceBehavior
Terminal (default)The agent runs in a real terminal; convert it to Chat at any time
ChatThe agent opens directly as a structured Chat transcript from the first prompt, in the surface you launched from — a sidebar or utility-panel launch stays in that panel

Chat is available for agents Agentastic can drive over a structured protocol — 24 of the 52 catalog definitions today:

TransportAgents
NativeClaude Code, Codex
Agent Client Protocol (ACP)Prime Agent, Poolside, Cursor, Grok Build, Qwen Code, Droid, OpenCode, GitHub Copilot, Auggie, Goose, Kimi, Kilocode, Devin, Kiro, Cline, Mistral Vibe, Hermes Agent, Junie, MiMo Code, Qoder CLI, Oh My Pi, CodeBuddy Code

Custom connections that resolve to one of these commands get Chat too. Agents launched with a command override, and agents started by a scheduled task, always open in Terminal.

ACP chats start the provider's own ACP server over stdio, so the transcript carries thinking, nested tool calls, plans, session metadata, and permission requests as structured events rather than scraped terminal output. Optional features — image attachments, session resume, mid-turn steering, slash commands, usage reporting, dynamic configuration — are negotiated with the provider when the session starts, so a chat only offers what that agent actually implements. The Export menu on an ACP chat writes either a parsed transcript or a redacted protocol log for troubleshooting.

Native Codex chats use App Server's turn/steer request for the same mid-turn experience. Agentastic includes the active thread and expected turn identifiers, so a message cannot accidentally land in a newer turn when completion races with delivery.

A direct Chat launch owns no hidden shell. Choosing Terminal on such a chat resumes that exact provider conversation in a real PTY and replaces the tab — so nothing is lost, but the switch waits for the current turn to finish.

You can also start or continue these chats from the command line with dev agent task (and its dev agent submit alias), so scripts and automations can queue work into the right worktree's chat. See the System-wide dev CLI for details.

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's public catalog includes 52 built-in agent definitions and automatically detects the installed CLIs, including:

  • Prime Agent - If prime-agent is in your PATH
  • Claude Code - If claude is in your PATH
  • Codex - If codex is in your PATH
  • Poolside - If pool is in your PATH
  • Command Code - If command-code, commandcode, or cmdc 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
  • MiMo Code - If mimo is in your PATH
  • Qoder CLI - If qodercli is in your PATH
  • OpenClaude - If openclaude is in your PATH
  • Ante - If ante is in your PATH
  • Oh My Pi - If omp is in your PATH
  • OpenClaw - If openclaw is in your PATH
  • Warp Agent CLI - If warp is in your PATH
  • CodeBuddy Code - If codebuddy or cbc is in your PATH
  • Zero - If zero is in your PATH
  • And 30+ 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 with the provisional name shown in Agent Home
  2. Run setup scripts and start the container when configured
  3. Start the Worktree Display Name action inside that new worktree
  4. Open the new environment and launch the AI agent without waiting for naming
  5. Apply the display name when the background action finishes; the original branch and worktree path remain unchanged

The naming action runs in its own task session, rooted in the newly created worktree; it does not ask the main coding agent to name itself. Its default Headless target preserves the selected agent's preferred interface while keeping the session hidden, then closes that terminal or Chat after a valid result. Failed sessions remain available for inspection. You can choose Utility Chat to explicitly use, reveal, and retain Chat instead. For a local terminal-first Codex or Claude agent, Agentastic captures the structured response from a provider-native semantic record or durable transcript. Worktree creation and agent launch do not wait for that response. The task only updates presentation metadata: it never renames the Git branch or worktree directory. Customize its target, model, and prompt in Settings > Tasks. Its built-in prompt uses {userPrompt}, and the full shared placeholder dictionary is available. See Actions.

Activity Indicators#

Waiting has a shape in Agentastic. Instead of a generic spinner, an animated orb tells you which kind of work is in flight:

OrbWhereMeans
Large, above the composerAgent Home, Quick AgentConnecting to the agent
Small, beside the status textChatThinking, streaming a response, or running a tool group
Small, slowAgent Home status rowsCreating a worktree, or provisioning and syncing a cloud container

The orbs are drawn natively for both light and dark appearance. With Reduce Motion enabled in System Settings > Accessibility > Display, they render as a still image instead of animating.

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