Run your first task

1 · Create or open a project

On the web you can create a scratch project or attach a GitHub repository reference for cloud context. In the Mac app you can also Open Folder and bind the real working tree. A web-created project keeps the same project id, history, membership, and Assets when you later connect it to a Mac workspace.

2 · Connect machine capabilities

On first run, the app shows one switch per optional machine feature: window captures (Screen Recording), text in captures (Accessibility), voice dictation (Microphone), and local task alerts (Notifications). Turning a switch on asks your computer for that permission; when the OS requires its own settings app, Iterel opens the exact pane and detects the change when you return. Turn on only what you intend to use, or choose Finish later or Continue without granting anything. Live status and the same switches stay available under App settings → Machine access. Project-folder access is requested only when you choose a folder; Iterel does not need Full Disk Access.

Use first-run setup or App settings → Engines to configure Claude Code, Codex, Cursor, or another supported Build engine once for the machine. Product integrations belong somewhere else: bind the exact account and remote resource under Project settings → Integrations.

Iterel detects installed CLI executables from the Mac login-shell PATH. Having Claude, ChatGPT, or Cursor open does not connect it. If an engine is missing, choose Install in Iterel: Electron resolves the allowlisted official command, runs it in a visible machine-setup terminal, and checks again automatically. Verified vendor sign-in commands use the same flow; copy and the official guide remain fallbacks. Iterel does not copy or proxy the resulting login.

Optional model providers are a separate choice, not software to install. Add a provider key for Qwen, MiniMax, z.ai, DeepSeek, Kimi, or OpenRouter during first-run setup or later in App settings; Iterel encrypts it on the Mac and uses it only with the compatible local engine.

If the project was created on the web, Iterel creates a tracked setup task named Connect the Mac app for local execution. Setup work stays in the task system rather than disappearing into a tooltip.

3 · Create the task

Use the Build-home General composer to describe the outcome. Add files, project context, acceptance criteria, or a source link before running. Iterel creates an Up next task and records the selected engine and environment.

4 · Run a round

Open the task dashboard and choose Run. Iterel creates a per-task git worktree, assembles project context and task history, then streams the engine's plan, prose, tool calls, browser verification, and errors into the task. You can Stop the run; supported engines can also receive a steer while they work.

5 · Review and land

A changed run moves to Needs review. Read the file and frame changes, gate results, browser-verification evidence, and receipt. Accept merges the isolated worktree into the base branch; Discard removes it. A no-change run says so and does not manufacture review work.

6 · Continue with a round

Use the task composer to Run another round or Ask a cited question without changing status. A same-objective follow-up stays on the task; broader work becomes a new task in the same mission.