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.

Find answers to the most common questions about Agentastic below. If you do not find what you are looking for, check the documentation or open a GitHub issue.

​
General

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.
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
Yes, Agentastic is free to use.
No. Agentastic does not collect any data for training or any other purpose.
Agentastic requires macOS 14.0 (Sonoma) or later. Both Apple Silicon and Intel Macs are supported.

​
Agents

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

​
Worktrees

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.
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.
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:
git worktree remove path/to/worktree
git worktree prune  # Clean up stale references

​
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.
Yes. Install Docker Desktop to use container mode in Agentastic.
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.

​
Terminal

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.
Yes. In Settings > Terminal, select Custom and enter the path to your shell, for example:
/opt/homebrew/bin/fish
Install a Nerd Font and select it in Settings > Terminal > Font.

​
Code review

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
Yes. Enable multiple agents in Settings > Code Review to get diverse perspectives on your code changes.
Yes. In Settings > Code Review > Custom Agents, add any command-line tool. For example:
ollama run codellama "$(cat 'prompt_file')"

​
Performance

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

​
Troubleshooting

Agentastic stores settings at:
~/Library/Application Support/Agentastic/
1

Quit Agentastic

Close the application completely.
2

Remove the settings folder

rm -rf ~/Library/Application\ Support/Agentastic
3

Relaunch Agentastic

Open Agentastic. It will start with default settings.
Ensure the agent CLI is installed and available in your PATH:
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.
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
Check the following:
  1. Verify Docker Desktop is running
  2. Check that the image exists: docker images
  3. Review logs in Settings > Agents

​
Getting help

Open a GitHub issue and include:
  • Your macOS version
  • Your Agentastic version
  • Steps to reproduce the issue
  • What you expected to happen versus what actually happened