Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentastic.dev/llms.txt

Use this file to discover all available pages before exploring further.

Agent Home is the command center for every AI coding session in Agentastic. From one interface you write your task prompt, choose which agents to run, configure the branch and environment, and launch — all without touching the terminal manually.

​
Opening Agent Home

Open Agent Home in either of two ways:
  • Click the Home icon in the Navigator sidebar.
  • Open the Command Palette with Cmd+Shift+P and type Agent Home.

​
Writing your prompt

The prompt card in the center of Agent Home is where you describe what you want the agent to build, fix, or investigate. Type your instructions in the text area. Effective prompts are specific, reference the right technologies, and point the agent to relevant existing 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/
Break complex work into focused tasks. Instead of “build the whole feature,” give each agent one clear responsibility — for example, schema, API endpoints, and frontend components as separate launches.

​
Mentioning files with @

Reference specific files to give the agent context about your codebase:
1

Type @ in the prompt

Place your cursor anywhere in the prompt and type @.
2

Start typing a filename

Begin typing any part of the filename. An autocomplete list appears.
3

Select the file

Choose the file from the list. The full path is inserted as a mention.
Mentioned files are included in the agent’s context so it understands how your project is structured.

​
Attaching images

Attach screenshots, design mockups, or UI diagrams to help vision-capable agents understand what you want:
  • Drag and drop images directly onto the prompt card.
  • Click the photo icon in the card toolbar to browse your filesystem.
  • Paste an image from your clipboard with Cmd+V.
Images are saved alongside the agent’s prompt file and passed to agents that support vision input.

​
Selecting agents

​
Auto-discovered agents

Agentastic automatically detects installed AI agents by checking your PATH. Agents that are found appear in the selector without any configuration. Supported auto-discovered agents include:
  • Claude Code — detected as claude
  • Codex — detected as codex
  • Command Code — detected as cmd
  • Gemini — detected as gemini
  • Cursor — detected as agent
  • GitHub Copilot — detected as copilot
  • Junie — detected as junie
  • OpenHands — detected as openhands
  • Letta Code — detected as letta
  • Cortex Code — detected as cortex
  • Aider — detected as aider
  • And 20+ more — see Agents for the full list.

​
Custom agents

Add agents that are not built-in by going to Settings > Connections and entering the agent’s command.

​
Running multiple agents in parallel

1

Open the agent selector

Click the agent selector dropdown on the prompt card.
2

Check multiple agents

Select as many agents as you want to run.
3

Adjust instance counts

For each agent, set how many parallel instances to run: 1x, 2x, or 3x.
4

Launch

Click Send. Each instance gets its own isolated worktree.
For example, you can run two Claude instances and one Codex instance simultaneously, each working on a different aspect of your task.

​
Configuration options

​
Repository

If you have multiple repositories open, use the repository selector to choose which one the agent should work in.

​
Base branch

Choose which branch the agent’s new worktree is created from. This is typically main or master, but can be any existing branch.

​
Branch name

Enter a name for the new branch. Agentastic suggests a random city name (e.g., tokyo-847) to avoid conflicts. You can replace it with any descriptive name you prefer.
Descriptive branch names like feature-user-auth or fix-login-redirect make it easier to track what each agent is working on when you have several running in parallel.

​
Mode: worktree vs container

Choose the environment the agent runs in:
The agent runs directly on your Mac in a git worktree — a separate checkout of your repository on disk.
  • Starts immediately, no Docker required
  • Full access to your locally installed tools
  • Fastest option for most tasks

​
Container image

When using Container mode, select a Docker image from the list:
ImageContents
agentastic/soupPre-installed AI tools: Claude Code, Codex, Aider
docker/sandbox-templates:claude-codeOfficial Claude Code sandbox
node:22-bookwormNode.js 22 environment
python:3.12-bookwormPython 3.12 environment
You can also add custom images you have locally.

​
Launching

Click Send or press Enter to launch. Agentastic then:
1

Creates a git worktree

A new branch is created from your base branch, and a separate working directory is set up on disk.
2

Runs setup scripts

Any setup scripts configured for the repository run automatically.
3

Starts the container (container mode only)

Docker pulls the image if needed and starts the container with your worktree mounted.
4

Opens a terminal

A terminal tab opens in the new environment.
5

Launches the agent

The agent CLI starts with your prompt.

​
Validation warnings

Agent Home shows warnings before launch if:
  • The branch name already exists in the repository.
  • The base branch is not up to date with the remote.
  • Docker is not running when container mode is selected.
Address these warnings before sending to avoid launch failures.

​
Monitoring progress

After launch, track your agent’s work:
  • The terminal tab shows the agent’s live output.
  • Switch to the agent’s worktree to browse file changes in the editor.
  • Use Cmd+Option+Down / Cmd+Option+Up to move between active worktrees.
  • Open the Agents tab in the Navigator (Cmd+4) to see all running agents at a glance.

​
Keyboard shortcuts

ActionShortcut
Submit promptEnter
New line in promptShift+Enter
Open Agent HomeCmd+Shift+P, then type “Agent Home”
Next worktreeCmd+Option+Down
Previous worktreeCmd+Option+Up

​
Persistence

Agent Home remembers your last-used settings across sessions:
  • Selected repository
  • Base branch
  • Selected agents
  • Mode (worktree or container)
You do not need to reconfigure these each time you open Agent Home.

​
Troubleshooting

Agentastic discovers agents by checking your PATH. If an agent is missing:
  1. Verify the CLI is installed globally.
  2. Confirm it is in your PATH by running which <agent-name> in a terminal.
  3. Make sure the binary is executable.
  4. Restart Agentastic if you installed it after the app launched.
Container mode requires Docker Desktop:
  1. Download and install Docker Desktop.
  2. Start Docker Desktop and wait for it to fully launch.
  3. Refresh Agent Home — container mode will become available.
Common causes and fixes:
  • Branch already exists — Choose a different branch name.
  • Git conflicts — Check git status in the main worktree and resolve any issues.
  • Permission error — Ensure you have write access to the worktree storage location configured in Settings > Agents.