# Syntheo User guide

>  © 2026 Quadropic Pvt Ltd. Proprietary and confidential. Do not copy, redistribute, scrape, adapt, or use this material to develop or train a competing product. [Full use restrictions](NOTICE.md).

Syntheo is a development harness: it gives an AI model a workspace, durable task history, code-search tools, a terminal, a browser, Git workflows, permissions, and optional multi-agent coordination. The model matters, but most of the leverage comes from choosing the right execution mode and giving the harness a crisp target.

This guide documents the behavior currently available in the desktop app.

## Start here

If this is your first session, follow [Getting started](getting-started.md). For day-to-day work, keep [Tasks, prompts, and context](tasks-prompts-context.md) nearby.

| What you want | Best starting point | Why |
|---|---|---|
| A small, well-defined code change | Standard + Submit | Lowest coordination overhead |
| An explanation with no intended edits | Ask | Optimized for a concise answer |
| A plan you want to review before implementation | Architect | Inspects the code and writes a durable plan without changing implementation files |
| A hard bug with unclear cause | Debug | Prioritizes reproduction and diagnosis before a focused fix |
| A broad or ambiguous problem | Hunter + Submit | Gives the run more reasoning capacity |
| Web research or interaction with a site | Browser preset or Browser panel | Routes to web-aware behavior and provides a persistent page surface |
| UI/product design work | Design preset | Uses the model assignment configured for design work |
| Risky or experimental changes | Virtual Edit | Isolates the thread in a temporary Git worktree |
| Several independent workstreams | A named room + Conductor | Gives workers a shared objective and coordination scope |
| Recurring work while Syntheo is open | Scheduled Tasks | Runs a prompt on a daily, weekly, weekday, or cron schedule |
| Start work from a shell or script | `syntheo` CLI | Creates a desktop task without leaving the terminal |

## The leverage loop

The highest-signal Syntheo workflow is:

1. **Choose the workspace.** A task can only inspect and edit the directory it is launched in (or its associated worktree).
2. **Choose the action.** Submit, Architect, Ask, and Debug carry different instructions. Do not use a large prompt to compensate for the wrong action.
3. **State an observable outcome.** Name the behavior that should exist when the task is done.
4. **Attach focused evidence.** Mention files, paste an error, add an image, or identify a reproduction path.
5. **Define constraints and validation.** Say what must not change and what command or behavior proves success.
6. **Let the agent inspect.** Avoid prescribing an implementation before the agent has seen the code unless the implementation itself is a requirement.
7. **Steer with deltas.** While a run is active, send only new information or a changed priority.
8. **Review the evidence.** Read the final summary, inspect File Diff, and run the relevant tests.
9. **Integrate intentionally.** Apply a Virtual Edit, stage/commit through Git, or keep the result isolated.

A strong request usually fits this shape:

```text
Outcome:
When a signed-in user refreshes /billing, their selected plan is preserved.

Evidence:
The failure starts after commit abc123. Reproduction: ...

Constraints:
Do not change the public API or add a dependency. Preserve the guest flow.

Done when:
- the reproduction no longer fails
- the existing billing tests pass
- a regression test covers refresh after selection
```

## Guide map

- [Getting started](getting-started.md) — connect a model, add a workspace, index it, and complete a safe first task.
- [Use existing AI subscriptions](subscriptions-provider-access.md) — connect eligible Claude/Claude Code, ChatGPT Plus/Pro, and GitHub Copilot subscriptions through OAuth.
- [Tasks, prompts, and context](tasks-prompts-context.md) — action modes, prompt construction, `@` mentions, images, steering, approvals, and context compression.
- [Workspaces and code intelligence](workspaces-code-intelligence.md) — workspace boundaries, Code Atlas, panels, thread housekeeping, and context hygiene.
- [Git, diffs, and Virtual Edits](git-diffs-virtual-edits.md) — isolation, review, applying a layer, staging, committing, pulling, pushing, and syncing.
- [Autonomy, rooms, and Conductor](autonomy-rooms-conductor.md) — when multi-agent work pays off, room worktrees, Kanban lifecycle, and orchestration.
- [Models, permissions, skills, and MCP](models-permissions-extensions.md) — model lanes, thinking levels, custom endpoints, global behavior, tool trust, and Marketplace extensions.
- [Schedules, CLI, Mobile Companion, and privacy](automation-cli-mobile.md) — unattended runs, terminal launch, phone pairing, remote relay, external apps, and Privacy Veil.
- [High-leverage recipes](recipes.md) — copyable workflows for common engineering jobs.
- [Troubleshooting and shortcuts](troubleshooting-shortcuts.md) — common failure modes, recovery steps, and keyboard reference.

## Core terms

**Workspace:** A project directory registered with Syntheo. Tasks and tools are scoped to a workspace or a worktree derived from it.

**Thread:** A durable conversation and execution history for one task. A thread keeps its model choice, messages, tool activity, approvals, and artifacts.

**Action:** The intent attached to a prompt: Submit, Architect, Ask, or Debug.

**Preset:** A user-selectable model lane such as Standard, Hunter, Design, or Browser. Each lane maps to a provider, model, and optional thinking level in Settings.

**Virtual Edit / layer:** A temporary Git worktree and branch associated with a thread. It isolates changes until you apply the layer.

**Autonomy:** The board for staging, running, reviewing, and organizing agents.

**Room:** A coordination boundary with a shared objective. A named room may also have a shared worktree inherited by its agents.

**Conductor:** An orchestration agent that can create rooms, decompose work, create worker tasks, start them, steer them, and stop them.

**Code Atlas:** A local semantic index used for code-aware search and navigation. It complements exact text search; it does not replace normal file inspection.

**Skill:** Reusable instructions that teach an agent a specialized workflow.

**MCP server:** A local or remote tool server whose discovered tools can be exposed to agents.

## Safety defaults

- Keep write-capable and network-capable tools on **Ask** until you understand their scope.
- Inspect the arguments in every approval prompt. **Allow Once** is the safest temporary choice.
- Use a Virtual Edit for broad refactors, migrations, generated changes, or any task where rollback matters.
- Treat **Add Current Changes** as `git add -A`: it can stage unrelated working-tree changes.
- **Commit** only commits files that are already staged.
- **Pull** is fast-forward only. **Sync** fast-forward pulls and then pushes the current branch.
- A room worktree is shared by its room’s agents. Assign non-overlapping ownership before running several writers.
- Scheduled tasks only run while Syntheo is open.
- Privacy Veil hides the app from supported screen capture; it is not a substitute for removing secrets from prompts or logs.