FAQ

Frequently asked questions about Agentastic

General

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.

What makes Agentastic different from other editors?

  • Native macOS - Built with Swift/SwiftUI for optimal performance
  • Agent isolation - Each AI agent works in its own git worktree
  • Parallel execution - Run multiple agents simultaneously
  • Ghostty terminal - GPU-accelerated terminal with smooth rendering
  • Code review integration - AI-powered review with Claude, Codex, and more

Is Agentastic free?

Yes, Agentastic is free to use.

Do you train on my code?

No. Agentastic does not collect any data for training or otherwise.

What macOS versions are supported?

Agentastic requires macOS 14.0 (Sonoma) or later. Both Apple Silicon and Intel Macs are supported.

Agents

How do agents work?

Each agent runs in an isolated git worktree - a separate checkout of your repository. This means:

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

Which AI agents are supported?

Agentastic auto-discovers and supports:

  • Claude Code (Anthropic)
  • Codex (OpenAI)
  • Aider
  • Custom agents via configuration

Do I need API keys?

Yes, AI agents require their respective API keys:

  • Claude: ANTHROPIC_API_KEY
  • Codex: OPENAI_API_KEY

Set these in your shell environment or configure them in the agent's settings.

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, etc.). Review each agent's privacy policy for details.

Worktrees

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.

Where are worktrees stored?

By default, adjacent to your repository:

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

Configure the location in Settings > Agents.

How do I clean up worktrees?

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

Or from terminal:

git worktree remove path/to/worktree
git worktree prune  # Clean up stale references

Containers

Why use containers?

Containers provide maximum isolation:

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

Do I need Docker?

Yes. Install Docker Desktop to use container mode.

What images are available?

Built-in images:

  • agentastic/soup - All-in-one with Claude, Codex, Aider
  • docker/sandbox-templates:claude-code - Official Claude sandbox
  • node:22-bookworm - Node.js environment
  • python:3.12-bookworm - Python environment

Add custom images in Settings > Agents.

Terminal

What's the difference between Ghostty and SwiftTerm?

  • Ghostty: GPU-accelerated via Metal, smooth performance
  • SwiftTerm: Pure Swift, reliable fallback

Ghostty is recommended for most users.

Can I use my custom shell?

Yes. In Settings > Terminal, select Custom and enter the path:

/opt/homebrew/bin/fish

How do I get Powerline fonts to work?

Install a Nerd Font and select it in Settings > Terminal > Font.

Code Review

How does AI code review work?

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

Can I use multiple review agents?

Yes. Enable multiple agents in Settings > Code Review to get diverse perspectives on your code.

Can I add custom review agents?

Yes. In Settings > Code Review > Custom Agents, add any command-line tool:

ollama run codellama "$(cat 'prompt_file')"

Performance

How can I improve performance with large projects?

  1. Add build folders to search ignore patterns
  2. Close unused tabs and worktrees
  3. Disable unused language servers
  4. Use Ghostty terminal backend

Why is my CPU usage high?

Usually caused by language servers indexing. Wait for initial indexing to complete. If it persists, try disabling LSP temporarily in Settings.

Troubleshooting

Where are settings stored?

~/Library/Application Support/Agentastic/

How do I reset to defaults?

  1. Quit Agentastic
  2. Remove the settings folder: 
    rm -rf ~/Library/Application\ Support/Agentastic
  3. Relaunch Agentastic

Agent not found

Ensure the agent CLI is installed and in your PATH:

which claude
which codex

Worktree creation failed

  • Check the branch name doesn't already exist
  • Verify you have write permissions
  • Run git status to check for conflicts

Container won't start

  1. Verify Docker Desktop is running
  2. Check the image exists: docker images
  3. Review logs in Settings > Agents

Getting Help

Where can I get support?

How do I report a bug?

Open a GitHub issue with:

  • macOS version
  • Agentastic version
  • Steps to reproduce
  • Expected vs actual behavior