First run: from a model to the first dispatch
Five steps take you from “connect a model” to “attach a folder, create a session, send a request, and inspect the changes”. Each step names the actual control in the window.
1. Connect a provider
Section titled “1. Connect a provider”Press Ctrl+, (⌘+, on macOS), open Settings, and choose Model providers. Click Add provider, pick a preset or a custom OpenAI-compatible endpoint, fill in the base URL and API key, fetch or type model ids, turn on Reasoning for models that should offer thinking levels, and save.
Back in the main window, the model pill at the bottom-left of the composer confirms the provider is available. See Providers for every field.
2. Attach a workspace
Section titled “2. Attach a workspace”Click + next to “Workspaces” in the left sidebar, or choose “Attach folder” in the empty state, then pick a Git repository (a plain folder works too). The workspace row shows its name and path; click the selected workspace again to expand its session list. To dispatch into separate Git worktrees, the repository must already have commits.
Plain folders can also run sessions and dispatch workers, but they show “No git”; the worker edits the folder in place, no worktree is created, and only one task runs there at a time. Use a Git repository when you need parallel dispatch.
3. Create a session and pick a role
Section titled “3. Create a session and pick a role”Expand the workspace and click + next to the “Sessions” heading, or use “New session” in the center. The dialog selects Orchestrator (marked with a crown) by default; choose Worker or a custom role if you want to work directly. Pick a model and an available thinking level, then click Create.
The open session shows its status, role, and current branch in the header. The composer at the bottom is ready for your request.
4. Send the first request
Section titled “4. Send the first request”Describe the goal in your own words and press Enter to send; use Shift+Enter for a new line. While the turn runs, the send button becomes Queue and a Stop button appears; messages and tool calls stream into the timeline.
When the orchestrator dispatches, it reads code and splits the work, and the Tasks tab on the right gains a task count; open it to see task cards and progress. A direct conversation with a Worker or custom role has no dispatch step.
5. Inspect what happened
Section titled “5. Inspect what happened”In the right panel’s Tasks tab, click a task card. Details show the brief, dependencies, attempts, messages, and worker output. When the task is In review or Completed and uses Git, click View changes to switch to the Changes tab with that dispatch’s diff.
When it dispatches, the orchestrator reports review and merge results in the conversation. If the request is unclear, worker questions come back through the orchestrator; answer them in the composer.
Three examples
Section titled “Three examples”Example 1: dispatch several different tasks
Section titled “Example 1: dispatch several different tasks”In a workspace attached to a Git repository, create a session and keep the default Orchestrator role, then send the text below.
The repo has two unrelated tasks. Dispatch each to a separate worker and run them in parallel:
1. Tighten the home page layout — consistent spacing and type sizes, no copy changes.
2. Rework the user docs and fill in the missing steps.
Review and merge both when they finish; ask me first if anything is unclear.The orchestrator reads code, splits the work into two tasks, and gives each one a worker. In a Git workspace they run in parallel on separate worktrees and two cards appear in the Tasks tab; when both finish it reports the review and merge results in the conversation. The worktree requirements are in the note below.
On it. The two tasks are independent: the home page only gets consistent spacing and type sizes without copy changes, and the docs get the missing steps. I'll dispatch them in parallel, ask you first if anything is unclear, and review and merge both when they finish.
fynvra/home-spacing fynvra/docs-steps Both workers reported back without touching each other's branch: the home page only changed spacing and type sizes, and the docs gained the missing steps. I'll review both now.
+86 −54 git diff --check · node --check fynvra/home-spacing → main +128 −39 fynvra/docs-steps → main Both tasks passed review and merged. main has two --no-ff commits: the home page now has consistent spacing and type sizes without copy changes, and the docs have the missing steps.
Example 2: name a different model for each worker
Section titled “Example 2: name a different model for each worker”Still in the Orchestrator session, name the model for each task in the request itself. Replace the example names with the actual names or ids enabled under Settings → Model providers.
Dispatch two tasks:
- Home page implementation goes to one worker on DeepSeek deepseek-chat.
- Docs cleanup goes to another worker on GPT gpt-5.5.
Review and merge both when they finish. If one of those models is not configured, tell me instead of substituting another one.The orchestrator starts each worker on the model you named for that task; models are set per dispatched task.
On it. Home page implementation goes to a deepseek-chat worker, docs cleanup to a gpt-5.5 worker. Both models are configured, and the tasks are independent, so I'll dispatch them in parallel and review and merge both when they finish.
fynvra/home-impl fynvra/docs-cleanup Both workers are running in parallel worktrees: deepseek-chat on the home page implementation, gpt-5.5 on the docs cleanup.
+74 −58 +96 −31 Both workers reported back. The home page implementation is committed and the docs cleanup filled in the missing steps; I'll review both against the same request now.
+74 −58 +96 −31 fynvra/home-impl → main fynvra/docs-cleanup → main Both tasks passed review and merged. main has two --no-ff commits: the home page implementation from deepseek-chat and the docs cleanup from gpt-5.5.
Example 3: talk to a role directly
Section titled “Example 3: talk to a role directly”First, under Settings → Roles click New, create a “Code reviewer” role with the Read-only tool policy, and save it; it applies to newly started sessions. Fynvra has only two built-in roles, Orchestrator and Worker, so a reviewer has to be created. See Roles for the fields.
Add a collapsible sidebar to the settings page: when collapsed only icons remain, remember the state locally, and list the files you changed.Review the sidebar-collapse implementation you just made: keyboard operation, persisted collapse state, and layout. List only problems and suggestions; do not edit files and do not commit.Create a session with Worker first and send the first prompt. When that work is finished, create another session with Code reviewer and send the second prompt to check the result. The Worker session edits code and names the changed files; the reviewer session is read-only and returns a list of issues without touching files. A role is chosen when a session is created, so an existing session cannot switch roles in place — create another one. Direct conversations create no tasks, so there is no orchestrator dispatch, review, or merge, and no per-dispatch worktree or task cards.
Added sidebar collapse to the settings page: when collapsed only the icon rail remains, the content area resizes with it, and narrow screens still expand correctly. The collapse state is saved locally and survives reloads. Changed 3 files: src/renderer/settings/Settings.tsx (collapse button and state read/write), src/renderer/settings/SettingsSidebar.tsx (icon rail layout), and src/renderer/settings/settings.css (widths and narrow-screen styles).
Issues
- The collapse control in
SettingsSidebar.tsxis a non-focusabledivwith only a click handler, so it cannot be activated from the keyboard. Settings.tsxreads the local collapse state without a fallback; older configs get undefined.settings.csshard-codes a 56px icon rail, so content overlaps when expanded on narrow screens.
Suggestions
- Use a native
buttonor add keydown handling, and keeparia-expandedin sync. - Default the value on read and add a version to the stored state so old values can be ignored safely.
- Drive the rail width from a variable and let content wrap in the 320px expanded state.
Read-only review done: no files modified and nothing committed.
Choose a role
- Orchestrator Main agent · plan & dispatch
- Worker Build · ship the change
- Code reviewer Custom · review only