> ## 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: launch and manage AI agents
> Agent Home is your central interface for writing prompts, selecting agents, and launching parallel AI coding sessions from a single place.
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:
```text theme={null}
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:
Place your cursor anywhere in the prompt and type `@`.
Begin typing any part of the filename. An autocomplete list appears.
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](/features/agents#all-built-in-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
Click the agent selector dropdown on the prompt card.
Select as many agents as you want to run.
For each agent, set how many parallel instances to run: 1x, 2x, or 3x.
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
The agent runs inside a Docker container, with your worktree mounted at `/workspace`.
* Maximum isolation from your local environment
* Reproducible setup across machines
* Requires Docker Desktop to be running
### Container image
When using Container mode, select a Docker image from the list:
| Image | Contents |
| -------------------------------------- | ------------------------------------------------- |
| `agentastic/soup` | Pre-installed AI tools: Claude Code, Codex, Aider |
| `docker/sandbox-templates:claude-code` | Official Claude Code sandbox |
| `node:22-bookworm` | Node.js 22 environment |
| `python:3.12-bookworm` | Python 3.12 environment |
You can also add custom images you have locally.
## Launching
Click **Send** or press `Enter` to launch. Agentastic then:
A new branch is created from your base branch, and a separate working directory is set up on disk.
Any setup scripts configured for the repository run automatically.
Docker pulls the image if needed and starts the container with your worktree mounted.
A terminal tab opens in the new environment.
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
| Action | Shortcut |
| ------------------ | ------------------------------------- |
| Submit prompt | `Enter` |
| New line in prompt | `Shift+Enter` |
| Open Agent Home | `Cmd+Shift+P`, then type "Agent Home" |
| Next worktree | `Cmd+Option+Down` |
| Previous worktree | `Cmd+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 ` 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](https://www.docker.com/products/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**.