DocsGet Started

How Agentastic Works

The repository, worktree, agent, and review model behind Agentastic

Agentastic is a native macOS development environment for delegating software tasks to many coding agents without losing control of the code around them.

The mental model#

Every delegated task moves through the same loop:

text

repository → isolated worktree → agent terminal → diff → review → pull request

The agent remains the provider's real CLI. Agentastic supplies the workspace around it: isolation, terminals, editor, browser, source control, review, and automation.

Core objects#

Object	What it represents
Repository	A git project opened in Agentastic
Worktree	A separate checkout and branch for one task
Agent	A provider CLI such as Prime Agent, Claude Code, Codex, Gemini, or Cursor
Terminal	The live native CLI session where the agent works
Diff	The changes made in the selected worktree
Review	Human review plus optional Claude, Codex, CodeRabbit, or Greptile feedback

One repository can have many worktrees. Each worktree can run its own agent, development server, browser preview, and terminal processes without editing another agent's files.

Isolation modes#

Choose the smallest boundary that fits the task.

Mode	Use it when
Worktree	You want a separate branch and checkout for normal parallel feature work
Local	You intentionally want the agent to work in the repository you already opened
Container	You need a stronger filesystem or dependency boundary through Docker or Apple Container
Remote SSH	The code and long-running session should live on another development machine
Cloud	You want an on-demand Modal, Fly.io, or Vercel Sandbox environment

Worktrees are the default because they are fast, ordinary git, and easy to inspect or delete.

Product surfaces#

Agent Home#

Describe a task, pick one or more providers, select an isolation mode, and launch. Agent Home creates the environment and delivers the prompt to each provider in the way its CLI expects.

Agents navigator#

See active and completed worktrees across repositories. Waiting indicators, diff totals, pull-request state, labels, pins, and recent-activity groups make it clear which task needs attention.

Native terminal and editor#

Agents run in GPU-accelerated Ghostty terminals. The surrounding IDE includes syntax highlighting, LSP, search, source control, and file editing, so you can investigate or adjust a task without switching applications.

Browser and review#

Run the worktree's development server, preview it in the built-in browser, drive the page through the dev browser CLI, inspect the diff, and run a second agent as a reviewer before opening a pull request.

Provider model#

Agentastic's public catalog includes 52 built-in definitions, and the app accepts custom terminal connections. A definition describes how to find a CLI, deliver its initial prompt, enter plan or unattended mode when the provider supports it, continue the latest session, and invoke code review when available.

Your provider remains responsible for the model, account, billing, and network requests. Agentastic does not extract provider tokens or proxy model calls.

Programmatic control#

Two CLIs use the command name dev:

The internal dev CLI is injected into Agentastic terminals and knows the current worktree, terminal, and browser.
The system-wide dev CLI discovers running Agentastic instances from any local shell and can launch agents, list worktrees, tail output, send follow-ups, or focus a workspace.

Both talk to the same local JSON-RPC control plane.

bash

dev agent create \
  --repo ~/src/my-app \
  --agent codex \
  --name fix-checkout \
  --prompt "Fix the checkout regression and run the focused tests."

Start with Programmatic Control or open the system-wide dev CLI reference.

Recommended first workflow#

Install Agentastic and one provider.
Launch one focused task in a new worktree.
Watch the terminal and test the worktree in the browser.
Review the diff and run optional code review.
Open a pull request, merge, then remove or archive the worktree.