DocsHelp
View as Markdown

FAQ

Answers on agents, git worktrees, containers, terminals, code review, performance, and privacy in Agentastic for macOS.

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

For tool-by-tool comparisons, see Agentastic vs Cursor, Agentastic vs Claude Code, Agentastic vs Conductor, or browse all comparisons.

Is Agentastic free?#

Yes, Agentastic is free to use.

Do you train on my code?#

No. Agentastic does not collect your source code, file contents, prompts, account details, email, name, or other personally identifiable information for training.

Agentastic may send anonymous diagnostic data to Sentry to help us debug crashes and app hangs. This can include an anonymous installation identifier, app version, macOS/device context, stack traces, crash or hang details, network failure metadata, and related diagnostic breadcrumbs. These diagnostics do not collect source code, file contents, prompts, account details, emails, names, or other personally identifiable information. They are used for reliability debugging only, not for training or product analytics.

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's public catalog includes 55 built-in agent definitions and auto-discovers them when installed:

  • Prime Agent (Prime Intellect)
  • Claude Code (Anthropic)
  • Codex (OpenAI)
  • Poolside (Poolside)
  • Gemini, Antigravity, and Jules (Google)
  • Muse Code (Meta)
  • Cursor (Anysphere)
  • GitHub Copilot (GitHub)
  • Junie (JetBrains)
  • OpenHands (All Hands AI)
  • Letta Code (Letta)
  • Cortex Code (Snowflake)
  • OB-1 (OpenBlock Labs)
  • MiMo Code (Xiaomi)
  • Qoder CLI (Qoder)
  • OpenClaude, Ante, Oh My Pi, and OpenClaw
  • Warp Agent CLI (Warp), CodeBuddy Code (Tencent), and Zero
  • Aider, Goose, Amp, Droid, Cline, OpenCode, and many more
  • Custom agents via configuration

See the full list in the Agents documentation.

Which tools and plugins does Agentastic work with?#

Dev works with your team's tools. First-class plugins ship for Slack, Notion, Sentry, GitHub, and Linear. Jira, GitLab, Forgejo, Asana, Monday, Trello, Plane, Plain, and Featurebase are also supported. Skills from Skillopedia install once and are delivered to whichever agent you launch — see Skills.

Attach a plugin to a run from Settings → Plugins or via the + menu in Agent Home. Connect a tool once and every agent gets it, in whatever convention that agent speaks. See Plugins & MCP, Slack, and Issue Tracking for more.

Can I use the Agentastic agent on Linux?#

Yes. The agentastic CLI runs on macOS, Linux, and WSL without the desktop app:

bash
curl -fsSL https://releases.agentastic.ai/agent/install.sh | sh

There is no Windows build. See Install the Agentastic CLI.

Can agents run as a chat instead of a terminal?#

Yes, for 30 of the 55 catalog agents. Agentastic, Claude Code, and Codex have native integrations, and every agent that speaks Agent Client Protocol — Cursor, Droid, Goose, OpenCode, GitHub Copilot, Cline, Kiro, Devin, Qwen Code, and more — runs over a shared ACP transport. A Chat renders thinking, nested tool calls, plans, and permission requests as structured events you can answer inline. Set the default per agent under Settings > Agents > Launch Interface, and flip any running session between Terminal and Chat without losing the conversation. See Chat.

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

Not to Agentastic, unless you choose one of its optional services. Anonymous crash and hang diagnostics may be sent to Sentry as described above, but those reports do not collect code or personally identifiable information.

The iPhone app, the Agentastic agent, and conversation sharing each work straight from your Mac or through an agentastic.com service:

  • iPhone app — Connects to your Mac directly on your network or tailnet. Reach this Mac from anywhere relays the connection through Agentastic, sealed end to end so the relay can't read it.
  • Agentastic agent — Talks to your own model providers with your subscriptions or API keys. Agentastic's hosted models run through Agentastic's servers.
  • Sharing — Share (via Tunnel) serves the page from your Mac through a temporary Cloudflare tunnel. Share (via Agentastic) uploads it to agentastic.com.

If you use the agentastic.com side, session traffic may pass through Agentastic's servers. The relay and Share (via Agentastic) need an Agentastic account, so not signing in under Settings > Accounts keeps them off. iPhone notifications, if you allow them, are delivered through Agentastic's push service whether or not you're signed in; they're end-to-end encrypted, so neither Agentastic nor Apple can read them.

When you use AI agents, code may be 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:

code
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:

bash
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/cloud-base - Claude, Codex, Amp, Gemini, OpenCode, Droid, Fx, Agentastic, and Repomix
  • 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:

code
/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:

bash
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?#

code
~/Library/Application Support/Agentastic/

How do I reset to defaults?#

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

Agent not found#

Ensure the agent CLI is installed and in your PATH:

bash
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?#

Use Help > Send Feedback in the app — the form collects the type and area, takes screenshots (paste with Cmd+V), and nothing is sent until you press Submit. From a terminal or an agent, dev feedback opens the same form prefilled.

You can also use the feedback form on the web. Include:

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