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

# Frequently asked questions

> Answers to common questions about Agentastic, including agents, worktrees, containers, terminal configuration, code review, performance, and troubleshooting.

Find answers to the most common questions about Agentastic below. If you do not find what you are looking for, check the [documentation](https://www.agentastic.dev/docs) or [open a GitHub issue](https://github.com/agentastic/agentastic/issues).

## General

<AccordionGroup>
  <Accordion title="What is Agentastic?">
    Agentastic is a native macOS code editor designed for AI agentic coding workflows. It uses git worktrees to let you run multiple AI coding agents in parallel without conflicts.
  </Accordion>

  <Accordion title="What makes Agentastic different from other editors?">
    Several things distinguish Agentastic from general-purpose editors:

    * **Native macOS** — built with Swift and SwiftUI for optimal performance
    * **Agent isolation** — each AI agent works in its own git worktree
    * **Parallel execution** — run multiple agents simultaneously without conflicts
    * **Ghostty terminal** — GPU-accelerated terminal with smooth rendering
    * **Code review integration** — AI-powered review with Claude, Codex, and more
  </Accordion>

  <Accordion title="Is Agentastic free?">
    Yes, Agentastic is free to use.
  </Accordion>

  <Accordion title="Does Agentastic train on my code?">
    No. Agentastic does not collect any data for training or any other purpose.
  </Accordion>

  <Accordion title="What macOS versions are supported?">
    Agentastic requires macOS 14.0 (Sonoma) or later. Both Apple Silicon and Intel Macs are supported.
  </Accordion>
</AccordionGroup>

## Agents

<AccordionGroup>
  <Accordion title="How do agents work?">
    Each agent runs in an isolated git worktree — a separate checkout of your repository. This means:

    * Agents cannot overwrite each other's work
    * You can continue working while agents run
    * Each agent's changes are on a separate branch

    When an agent finishes, you review its diff and merge or discard the changes.
  </Accordion>

  <Accordion title="Which AI agents are supported?">
    Agentastic ships with 33 built-in agent definitions and auto-discovers them when installed:

    * **Claude Code** (Anthropic)
    * **Codex** (OpenAI)
    * **Gemini** (Google)
    * **Cursor** (Anysphere)
    * **GitHub Copilot** (GitHub)
    * **Junie** (JetBrains)
    * **OpenHands** (All Hands AI)
    * **Letta Code** (Letta)
    * **Cortex Code** (Snowflake)
    * **OB-1** (OpenBlock Labs)
    * **Aider**, **Goose**, **Amp**, **Droid**, **Cline**, **OpenCode**, and many more
    * **Custom agents** via configuration

    See the full list in [Supported AI agents and providers](/reference/providers).
  </Accordion>

  <Accordion title="Do I need API keys?">
    Yes, AI agents require their respective API keys. For example:

    * Claude: `ANTHROPIC_API_KEY`
    * Codex: `OPENAI_API_KEY`

    Set these in your shell environment or configure them in the agent's own settings.
  </Accordion>

  <Accordion title="Is my code sent to external servers?">
    Agentastic itself does not send your code anywhere. When you use AI agents, code is sent to the agent's API (Anthropic, OpenAI, and so on). Review each agent's privacy policy for details.
  </Accordion>
</AccordionGroup>

## Worktrees

<AccordionGroup>
  <Accordion title="What is a git worktree?">
    A git worktree is a linked working copy of your repository. Unlike branches (which share one working directory), worktrees give each branch its own complete directory. This lets multiple agents work simultaneously on different branches without interfering with each other.
  </Accordion>

  <Accordion title="Where are worktrees stored?">
    By default, adjacent to your repository:

    ```
    my-project/               # Your main repo
    my-project-worktrees/     # Agent worktrees
      ├── feature-auth/
      └── feature-api/
    ```

    You can configure the location in **Settings > Agents**.
  </Accordion>

  <Accordion title="How do I clean up worktrees?">
    To remove a worktree from within Agentastic:

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

    Or from the terminal:

    ```bash theme={null}
    git worktree remove path/to/worktree
    git worktree prune  # Clean up stale references
    ```
  </Accordion>
</AccordionGroup>

## Containers

<AccordionGroup>
  <Accordion title="Why use containers?">
    Containers provide maximum isolation for agents:

    * Sandboxed filesystem and network
    * Reproducible environments
    * Pre-installed tools
    * Resource limits

    Use container mode when you need to ensure the agent cannot affect your host system or when you need a specific environment with particular dependencies pre-installed.
  </Accordion>

  <Accordion title="Do I need Docker?">
    Yes. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) to use container mode in Agentastic.
  </Accordion>

  <Accordion title="What images are available?">
    The following images are built-in:

    * `agentastic/soup` — all-in-one image with Claude, Codex, and Aider
    * `docker/sandbox-templates:claude-code` — official Claude sandbox
    * `node:22-bookworm` — Node.js environment
    * `python:3.12-bookworm` — Python environment

    You can add custom images in **Settings > Agents**.
  </Accordion>
</AccordionGroup>

## Terminal

<AccordionGroup>
  <Accordion title="What's the difference between Ghostty and SwiftTerm?">
    Agentastic supports two terminal backends:

    * **Ghostty** — GPU-accelerated via Metal, smooth performance. Recommended for most users.
    * **SwiftTerm** — Pure Swift implementation, reliable fallback.

    You can switch between them in **Settings > Terminal**.
  </Accordion>

  <Accordion title="Can I use my custom shell?">
    Yes. In **Settings > Terminal**, select **Custom** and enter the path to your shell, for example:

    ```
    /opt/homebrew/bin/fish
    ```
  </Accordion>

  <Accordion title="How do I get Powerline fonts to work?">
    Install a Nerd Font and select it in **Settings > Terminal > Font**.
  </Accordion>
</AccordionGroup>

## Code review

<AccordionGroup>
  <Accordion title="How does AI code review work?">
    To run a code review:

    1. Click the **Code Review** button
    2. Select which agents to use
    3. Agents analyze your diff
    4. Review the feedback in the terminal
  </Accordion>

  <Accordion title="Can I use multiple review agents?">
    Yes. Enable multiple agents in **Settings > Code Review** to get diverse perspectives on your code changes.
  </Accordion>

  <Accordion title="Can I add custom review agents?">
    Yes. In **Settings > Code Review > Custom Agents**, add any command-line tool. For example:

    ```bash theme={null}
    ollama run codellama "$(cat 'prompt_file')"
    ```
  </Accordion>
</AccordionGroup>

## Performance

<AccordionGroup>
  <Accordion title="How can I improve performance with large projects?">
    Try the following steps to improve performance on large codebases:

    1. Add build folders to search ignore patterns in **Settings > Search**
    2. Close unused tabs and worktrees
    3. Disable unused language servers
    4. Use the Ghostty terminal backend
  </Accordion>

  <Accordion title="Why is my CPU usage high?">
    High CPU usage is usually caused by language servers indexing your project on first open. Wait for the initial indexing to complete. If high CPU persists, try disabling LSP temporarily in Settings.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Where are settings stored?">
    Agentastic stores settings at:

    ```
    ~/Library/Application Support/Agentastic/
    ```
  </Accordion>

  <Accordion title="How do I reset to defaults?">
    <Steps>
      <Step title="Quit Agentastic">
        Close the application completely.
      </Step>

      <Step title="Remove the settings folder">
        ```bash theme={null}
        rm -rf ~/Library/Application\ Support/Agentastic
        ```
      </Step>

      <Step title="Relaunch Agentastic">
        Open Agentastic. It will start with default settings.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Agent not found">
    Ensure the agent CLI is installed and available in your `PATH`:

    ```bash theme={null}
    which claude
    which codex
    ```

    If the binary is found but Agentastic does not detect it, go to **Settings > Connections** and click **Refresh** to re-scan your `PATH`.
  </Accordion>

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

    * The branch name does not already exist in the repository
    * You have write permissions in the parent directory
    * Run `git status` to check for uncommitted conflicts
  </Accordion>

  <Accordion title="Container won't start">
    Check the following:

    1. Verify Docker Desktop is running
    2. Check that the image exists: `docker images`
    3. Review logs in **Settings > Agents**
  </Accordion>
</AccordionGroup>

## Getting help

<AccordionGroup>
  <Accordion title="Where can I get support?">
    * [Documentation](https://www.agentastic.dev/docs) — browse guides, references, and how-tos
    * [GitHub Issues](https://github.com/agentastic/agentastic/issues) — report bugs and request features
  </Accordion>

  <Accordion title="How do I report a bug?">
    Open a [GitHub issue](https://github.com/agentastic/agentastic/issues) and include:

    * Your macOS version
    * Your Agentastic version
    * Steps to reproduce the issue
    * What you expected to happen versus what actually happened
  </Accordion>
</AccordionGroup>