# Getting Started

## Choose An Install Path

Most users should install a direct application:

- Mac: [Direct Mac application](../platforms/direct-mac-application.md)
- Android: [Direct Android application](../platforms/android-application.md)

Use the CLI path only when you prefer npm, need a scriptable command, or are contributing from a checked-out repository.

## Prerequisites

- Direct Mac app: a Git project to manage and either a supported CLI agent (Claude Code, Codex, Gemini, OpenCode, Droid, Kiro) or a configured Cline provider.
- Direct Android app: the ZoneGaze Matrix APK. The owned Zone Terminal runtime ships with the app and is set up from the Runtime tab.
- CLI or contributor path: Node.js 22 or newer, and a git repository to run inside.

## Start The Application

Direct Mac app:

1. Open `ZoneGaze Matrix.app`. It starts or attaches to the local runtime and opens the Matrix dashboard directly.
2. If the runtime is offline, use the recovery screen's **Restart runtime** action or the menu-bar tray icon's **Start Server** / **Restart Server** action.
3. Add or select a project from the dashboard.

Direct Android app:

1. Open `ZoneGaze Matrix`. It opens on the **Dashboard** tab.
2. Check the **Runtime** tab until the owned Zone Terminal setup is complete.
3. On **Dashboard** or **Ports**, tap **Start** for the Matrix runtime, then tap **Open** once it is running.

CLI package path — run from the root of any git repository:

```bash
npx zonegaze-flow
```

ZoneGaze Flow detects your installed CLI agent and opens the board in your browser. Add `--no-open` to skip the browser launch and open the printed URL yourself.

For local verification from this repository, contributors use:

```bash
npm run dev -- --port 4217 --host 127.0.0.1
```

Then open `http://127.0.0.1:4217/demo-website`.

Screenshot: [open board overview](../assets/screenshots/board-overview.png)

![Board overview after opening ZoneGaze Flow](../assets/screenshots/board-overview.png)

## Add A Project

1. Open the **Projects** sidebar (left rail).
2. Choose **Add Project**.
3. Select a local path, browse the filesystem, enter a path manually, or clone from a git URL.
4. If the selected folder is not a git repository, confirm whether to initialize git.

## Create Your First Task

1. In the Backlog column, click **Create task**, or press <kbd>c</kbd>.
2. Enter a title and prompt. Use `@file` to reference files and drag-and-drop or paste (<kbd>Cmd</kbd>+<kbd>V</kbd>) to attach images.
3. Choose the work-item type, base ref, agent/model overrides, plan mode, and auto-commit / auto-PR as needed.
4. Click **Save** to add it to the board, or **Start** to begin immediately.

Screenshot: [open create task dialog](../assets/screenshots/create-task-dialog.png)

![Create task dialog for the first task](../assets/screenshots/create-task-dialog.png)

## Review The Result

1. Click the card to open the task detail view.
2. Inspect the chat or terminal transcript.
3. Review all changes or last-turn changes, in unified or split diff.
4. Click a line or drag a range to add a comment, then send comments back to the agent.
5. When the work looks good, click **Commit** or **Open PR**. To set the card aside, use the card's overflow (⋯) menu — Archive, Delete, or Remove — which tells you which view each sends the card to.

## Next Reading

- [Software manual](../manual/software-manual.md)
- [Platform application guides](../platforms/README.md)
- [How-to guide](how-to.md)
- [Cline integration](../features/cline-integration.md)
- [Operations runbook](../operations/runbook.md)
