# ZoneGaze Flow Manual

ZoneGaze Flow is a first-party Matrix plugin for task orchestration, agent sessions, review, and
Git-backed work. This manual is Flow-specific. For the host shell and plugin-platform view, start
with the [ZoneGaze Matrix manual](zonegaze-matrix-manual.md).

## Installation And Launch

Most users open the Matrix host app first:

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

The CLI launch path is for package users, automation, and contributors. It requires Node.js 22 or
newer and must be run from the root of a git repository:

```bash
npx zonegaze-flow
npm i -g zonegaze-flow
zonegaze-flow
```

The direct Mac app starts or adopts the local runtime from the desktop shell. The direct Android
app starts the runtime through the app-owned Zone Terminal backend. In this project, contributor
verification uses `http://127.0.0.1:4217/demo-website`.

## First Run

1. Launch ZoneGaze Flow.
2. Select or add a project.
3. Configure an agent in Settings if no supported agent is ready.
4. Create a task card, choose the target agent, base ref, plan/act preference, work type, parent task, child prompts, and optional images.
5. Start the task. ZoneGaze Flow creates or reuses the task workspace and runs the agent.
6. Review output and diffs before committing, opening a PR, moving to Done, or archiving work.

Screenshot: [open onboarding modal](../assets/screenshots/onboarding-modal.png)

![Onboarding modal showing the first-run task creation guide](../assets/screenshots/onboarding-modal.png)

## Main Screens

- Project sidebar: switch projects, add projects, remove projects, and switch to the ZoneGaze Flow Agent.
- Board: Plan Later, Plan Review, Backlog, Next Up, In Progress, Review, Done, Archive, deleted, and removed views.
- Detail view: task chat or terminal, diffs, file tree, comments, task children, and review actions.
- Git history: refs, commits, working-copy changes, branch checkout, fetch, pull, and push.
- Settings: agents, Cline providers, MCP servers, work types, workflow flags, shortcuts, notifications, appearance, Git prompts, project context, and project settings.

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

![Board overview with project sidebar and workflow columns](../assets/screenshots/core-board-input.png)

Screenshot: [open settings process](../assets/screenshots/core-settings-process.png)

![Settings dialog with core configuration areas](../assets/screenshots/core-settings-process.png)

## Core Feature Summary

The [core feature guide](../features/zonegaze-flow-core-features.md) is the full behavior reference. The feature groups are:

- Project management: local paths, remote browsing, manual path entry, Git clone/init, switch/remove, open workspace, disconnected and blocked states.
- Work items: create, edit, tag, filter, sort, move, restore, archive, delete, remove, images, file mentions, base refs, agents, model overrides, plan mode, auto review, child prompts, work types, and parent tasks.
- Work types: Epic, Story, Task, Subtask, coordinator/executable behavior, parent rules, validation, labels, colors, icons, and hierarchy flags.
- Dependencies: linked tasks, blocked/ready state, chained work, and descendant start behavior.
- Planning: ZoneGaze Flow Agent, Plan Later, Plan Review, generated cards, publish to Backlog, parallel planning, and coordinator validation.
- Agents: native ZoneGaze Flow/Cline, Claude Code, OpenAI Codex, Factory Droid, Kiro, OpenCode, Gemini, PTY sessions, Cline SDK sessions, provider/model/auth setup, MCP, and reasoning effort.
- Terminal and shortcuts: persistent terminal, workspace shell, reconnect, resize, clear, stop, restore, expand, minimize, and shortcut execution.
- Review and shipping: chat/terminal detail view, working-copy and last-turn diffs, file tree, line/range comments, commit, PR, auto-review cancellation, and Done/archive actions.
- Git and worktrees: branch, upstream divergence, changed counts, fetch, pull, push, checkout, refs, commits, diffs, task worktrees, and discard actions.
- Settings and platform access: project context, passcode gate, PWA, update detection, notifications, Featurebase feedback, Mac app, and Android app.

## Work Item Lifecycle

The typical lifecycle is:

1. Input: user creates a task, selects work type, agent, base ref, plan mode, child prompts, and optional images.
2. Process: ZoneGaze Flow prepares or reuses a task worktree, starts the selected agent, streams status, and updates the board.
3. Output: the detail view shows chat or terminal output, tool activity, files, diffs, warnings, comments, and Git state.
4. Result: the user commits, opens a PR, moves the task to Done, archives it, restores it, or removes it.

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

![Create task dialog with work item type, base ref, plan mode, and agent controls](../assets/screenshots/core-create-task-process.png)

Screenshot: [open Git/review output](../assets/screenshots/core-git-output.png)

![Git and review output surface](../assets/screenshots/core-git-output.png)

## Agents

Native ZoneGaze Flow/Cline supports provider setup, model setup, custom providers, API key or OAuth/device auth, MCP servers, account metadata, Plan/Act behavior, slash commands, file mentions, image attachments, prompt history, persisted chat, cancellation, tool labels, token snapshots, and context recovery where supported by the SDK.

CLI agents run through PTY sessions. Session states include idle, running, awaiting review, failed, and interrupted.

Screenshot: [open terminal panel](../assets/screenshots/terminal-panel.png)

![Terminal panel attached below the board](../assets/screenshots/terminal-panel.png)

## Worktrees And Review

Task execution normally happens inside an isolated Git worktree. The runtime tracks task metadata, branch state, changed files, additions/deletions, turn checkpoints, and patches for trashed tasks.

Review features include working-copy and last-turn diffs, unified and split views, file tree navigation, line/range comments, sending comments back to the agent, commit prompts, PR prompts, and auto-review modes.

Screenshot: [open Git history](../assets/screenshots/git-history.png)

![Git history view with refs, commits, and diff](../assets/screenshots/git-history.png)

## Direct Mac And Android Apps

The direct Mac app is the normal desktop install path. It starts or adopts a local runtime, provides dashboard/tray/menu controls, opens multiple windows, handles deep links, enriches PATH, and recovers from runtime or renderer failures.

The direct Android app is the normal Android install path. It provides a native Matrix dashboard and uses the owned Zone Terminal backend for automatic local runtime setup. It guides setup progress, plugin install state, runtime start/stop, WebView opening, Git setup, storage setup, and ZoneGaze Code start/stop.

Current Mac install screenshot: [open current Mac installed app board](../assets/screenshots/mac-install-launch-current.png)

![Current installed Mac app showing the ZoneGaze Flow board](../assets/screenshots/mac-install-launch-current.png)

Current Mac install video: [open current Mac install/launch video](../assets/videos/zonegaze-flow-mac-install-launch-current.webm)

![Current ZoneGaze Flow Mac install and launch video](../assets/videos/zonegaze-flow-mac-install-launch-current.webm)

Current Android install screenshot: [open current Android install/launch screenshot](../assets/screenshots/android-install-launch-current.png)

![Current Android emulator showing the installed ZoneGaze Flow APK dashboard](../assets/screenshots/android-install-launch-current.png)

Current Android install video: [open current Android install/launch video](../assets/videos/zonegaze-flow-android-install-launch-current.mp4)

![Current ZoneGaze Flow Android install and launch video](../assets/videos/zonegaze-flow-android-install-launch-current.mp4)

Mac video: [open Mac full workflow](../assets/videos/zonegaze-flow-mac-full-workflow.webm)

![ZoneGaze Flow Mac full workflow video](../assets/videos/zonegaze-flow-mac-full-workflow.webm)

Android dashboard setup video: [open Android dashboard setup recording](../assets/videos/zonegaze-flow-android-dashboard-setup.mp4)

![ZoneGaze Flow Android dashboard setup video](../assets/videos/zonegaze-flow-android-dashboard-setup.mp4)

The current Android recording verifies APK install and native dashboard launch on the emulator. A full owned-runtime Android workflow video still requires runtime start and WebView result capture; the remaining scope is documented in [Direct Android application](../platforms/android-application.md#recording-status).

## Input Process Output Result Evidence

Core working video: [open core working demo](../assets/videos/zonegaze-flow-core-working-demo.webm)

![ZoneGaze Flow core working demo video](../assets/videos/zonegaze-flow-core-working-demo.webm)

The durable core recording and screenshots show:

- Input: board state and create-task dialog.
- Process: settings/process and task configuration surfaces.
- Output: Git/review output.
- Result: archive view and produced website result.

Result screenshot: [open produced website result](../assets/screenshots/core-produced-website-result-page.png)

![Produced website output after a ZoneGaze Flow workflow](../assets/screenshots/core-produced-website-result-page.png)

## More Information

- [Master documentation](../MASTER.md)
- [Feature catalog](../features/feature-catalog.md)
- [Feature coverage matrix](../features/feature-coverage-matrix.md)
- [Platform application guides](../platforms/README.md)
- [How-to guide](../user/how-to.md)
- [Troubleshooting](../user/troubleshooting.md)
- [Screenshot assets](../assets/screenshots/README.md)
- [Video assets](../assets/videos/README.md)
- [Runtime API reference](../reference/runtime-api.md)
- [System design](../architecture/system-design.md)
