---
title: Quick Start
description: "Open a repository, learn the Agentastic workspace, launch a safe first agent task, follow the work, and review it — in a few minutes."
updated: "2026-09-19"
---

This tour assumes Agentastic and at least one provider CLI are already installed. If not, start with [Installation](/docs/installation).

## Open a repository

Use any of these entry points:

- Press <kbd>Cmd</kbd>+<kbd>O</kbd> in Agentastic.
- Drag a folder onto the Agentastic icon.
- Run `open -a "Agentastic.dev" /path/to/repository`.

A git repository unlocks the normal worktree-per-task workflow. Non-git folders can still use local or container mode.

## Know the workspace

| Area | What it is for |
|---|---|
| Navigator | Files, repositories, source control, and the Agents list |
| Editor | Code, diffs, browser previews, settings, and Agent Home |
| Utility area | Native terminals, task output, and logs |
| Inspector | Worktree status, changes, browser state, agents, commit, and pull-request actions |

Useful shortcuts:

| Action | Shortcut |
|---|---|
| Quick Open | <kbd>Cmd</kbd>+<kbd>P</kbd> |
| Command Palette | <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> |
| Toggle Navigator | <kbd>Cmd</kbd>+<kbd>B</kbd> |
| Toggle Utility Area | <kbd>Cmd</kbd>+<kbd>J</kbd> |
| Find in Project | <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>F</kbd> |

## Launch a focused task

1. Open **Agent Home**.
2. Choose the repository and base branch.
3. Select an installed provider.
4. Leave the isolation mode on **Worktree**.
5. Enter a task such as:

```text
Add a health-check endpoint that returns the app version.
Follow the existing route pattern and add focused tests.
Run those tests before you finish.
```

6. Send the prompt.

Agentastic creates a branch and worktree, runs any configured setup script, launches the provider's CLI, and delivers your prompt.

## Follow the work

The new task appears in the Agents navigator. From there you can:

- Watch its terminal output.
- Open changed files in the editor.
- Launch the worktree's development server.
- Preview and inspect the result in the built-in browser.
- Send a follow-up when the agent is waiting for input.

The main repository remains untouched because the task has its own checkout.

## Review and finish

When the agent stops:

1. Open the worktree's diff.
2. Run or inspect the relevant tests.
3. Optionally run code review with Claude, Codex, CodeRabbit, or Greptile.
4. Commit and open a pull request from the Inspector or source-control actions.
5. Archive or remove the worktree after the change is merged.

## Try the dev CLI

After installing the command from **Agentastic → Command Line Integration…**, launch a task from any terminal:

```bash
dev agent create \
  --repo ~/src/my-app \
  --agent codex \
  --name docs-cleanup \
  --prompt "Tighten the installation guide and check every internal link."
```

Then inspect and message it:

```bash
dev agents
dev tail <terminal_id> 80
dev send <terminal_id> "Also verify the examples on macOS 14."
```

See [Programmatic Control](/docs/guides/programmatic-control) for scripts, schedulers, dashboards, and bot integrations.

## Go deeper

- [Your First Agent](/docs/your-first-agent) — the full task lifecycle
- [Multi-Agent Programming](/docs/guides/multi-agent) — split independent work safely
- [Browser](/docs/features/browser) — preview and automate a worktree
- [Diff Viewer](/docs/features/diffs) — review before merge
