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

# Launch your first AI coding agent

> A step-by-step walkthrough for opening a project in Agentastic, configuring an AI agent, launching it in an isolated worktree, and reviewing its changes.

Agentastic makes it straightforward to hand off a coding task to an AI agent and keep working while it runs. This guide walks you through opening a project, configuring an agent, and reviewing its output — from start to finish.

## Prerequisites

Before starting, make sure you have the following:

* **Agentastic installed** — See the [installation guide](/installation) if you haven't set it up yet
* **A git repository** — Any project with git initialized works
* **An AI agent installed** — For example:
  * Claude Code: `npm install -g @anthropic-ai/claude-code`
  * Hermes Agent: `curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash`

## Walkthrough

<Steps>
  <Step title="Open your project">
    Launch Agentastic, then press `Cmd+O` or drag your project folder onto the app window. Select your git repository.

    You'll see the Navigator panel on the left showing your project files.
  </Step>

  <Step title="Open Agent Home">
    Agent Home is your control center for launching AI agents. Open it by:

    * Clicking the **Home** icon in the Navigator sidebar, or
    * Using the keyboard shortcut listed in the Command Palette

    You'll see a prompt card where you can describe your task.
  </Step>

  <Step title="Configure your agent">
    Fill in the configuration fields in Agent Home:

    1. **Select your repository** — If you have multiple repos open, pick the right one
    2. **Choose a base branch** — Usually `main` or `master`
    3. **Select an agent** — Pick from the auto-discovered agents (Claude, Codex, Hermes Agent, etc.)
    4. **Enter a branch name** — A random city name is suggested, or type your own
  </Step>

  <Step title="Write your prompt">
    In the prompt card, describe the task you want the agent to complete. Be specific about what you need, the technologies involved, and any patterns to follow.

    ```
    Add a user authentication system with:
    - Login/logout endpoints
    - JWT token handling
    - Password hashing with bcrypt
    - Basic rate limiting
    ```

    You can also:

    * **Mention files** — Type `@` to reference specific files for context
    * **Attach images** — Drag screenshots or click the photo icon
  </Step>

  <Step title="Launch the agent">
    Click the **Send** button or press `Enter`.

    Agentastic will:

    1. Create a new git worktree for your branch
    2. Run your setup script (if configured)
    3. Launch the AI agent in a terminal
    4. Pass your prompt to the agent

    The agent now works in its isolated environment. You can keep coding in your main workspace without any interference.
  </Step>

  <Step title="Monitor progress">
    While the agent runs, you have a few options:

    * **Watch the terminal** — See the agent's output in real time
    * **Switch worktrees** — Press `Cmd+Option+Down` to view the agent's workspace
    * **Keep working** — The agent runs in isolation and won't affect your current work
  </Step>

  <Step title="Review the changes">
    When the agent finishes, inspect what it produced:

    1. Open the **Diff Viewer** to see exactly what changed
    2. Optionally run **Code Review** for AI-powered feedback
    3. If you're satisfied, push the branch and open a pull request:

    ```bash theme={null}
    git push -u origin your-branch-name
    gh pr create --title "Add authentication system"
    ```
  </Step>

  <Step title="Clean up">
    After merging or discarding the branch, remove the worktree to keep your workspace tidy.

    **From the UI:**

    1. Go to **Settings > Agents**
    2. Right-click the agent's worktree
    3. Select **Remove Agent**

    **From the terminal:**

    ```bash theme={null}
    git worktree remove ../your-project-worktrees/branch-name
    ```
  </Step>
</Steps>

## Tips for success

<AccordionGroup>
  <Accordion title="Write clear prompts">
    * Be specific about what you want the agent to build or fix
    * Mention the technologies and patterns you want it to use
    * Reference existing files with `@` mentions to give the agent relevant context
  </Accordion>

  <Accordion title="Start with focused tasks">
    * Begin with single-purpose tasks that have a clear scope
    * Break larger tasks into smaller pieces before handing them to an agent
    * Focused tasks are easier to review and less likely to produce unexpected changes
  </Accordion>

  <Accordion title="Use multiple agents in parallel">
    * Run Claude for architecture and design decisions
    * Run Codex for boilerplate and repetitive code
    * Each agent works in its own isolated worktree, so there are no conflicts between them
  </Accordion>

  <Accordion title="Always review before merging">
    * Check the diff carefully before merging any agent branch
    * Use the built-in AI code review for a second opinion
    * Test the changes in the agent's worktree before merging into your main branch
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent not found">
    Agentastic auto-discovers agents that are installed and available in your `PATH`. If your agent doesn't appear, verify that the CLI is installed and accessible:

    ```bash theme={null}
    which claude  # Should show the path to the binary
    ```

    If the command returns nothing, reinstall the agent and ensure your shell's `PATH` is configured correctly.
  </Accordion>

  <Accordion title="Worktree creation failed">
    Check the following:

    * The branch name you entered doesn't already exist in your repository
    * You have write permissions in the project directory
    * Git is properly configured (`git config --list` to review)
  </Accordion>

  <Accordion title="Agent exits immediately">
    If the agent launches but exits right away, check the terminal output for error messages, then verify:

    * API keys for the agent are set as environment variables
    * The agent supports non-interactive (headless) mode
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={3}>
  <Card title="Setup and teardown scripts" icon="scroll" href="/guides/setup-teardown-scripts">
    Automatically install dependencies and configure each agent's environment when a worktree is created.
  </Card>

  <Card title="Run multiple agents" icon="users" href="/guides/multi-agent">
    Learn how to launch and manage several agents in parallel for faster development.
  </Card>

  <Card title="Customize your workflow" icon="sliders" href="/guides/customization">
    Tailor Agentastic's behavior to match how you and your team work.
  </Card>
</CardGroup>