# Getting started

>  © 2026 Quadropic Pvt Ltd. Proprietary Information. [Use restrictions](NOTICE.md).

This walkthrough takes you from a fresh installation to a reviewed first change.

## 1. Connect an AI provider

Open **Settings → AI Provider**.

Syntheo exposes model assignments instead of one global model:

- **Standard** for everyday work.
- **Hunter** for hard reasoning, planning, and debugging.
- **Design** for product and UI work.
- **Light** for low-latency questions and small tasks. This is an internal routing lane, not a composer preset.
- **Browser** for web-aware work.

For each lane:

1. Choose a provider.
2. Choose a model from that provider.
3. If the model supports reasoning controls, choose a thinking level.
4. Authenticate the provider with an API key or OAuth when supported.

Authentication is shown once for the first lane using a provider. Other lanes that use the same provider share that credential.

### Use an existing subscription

You do not necessarily need a separately billed API key:

- Choose **Anthropic → OAuth** for eligible Claude Pro/Max subscription access, including supported Claude/Claude Code use.
- Choose **OpenAI Codex → OAuth** for eligible ChatGPT Plus/Pro Codex access. The regular **OpenAI** provider uses an API key instead.
- Choose **GitHub Copilot → OAuth** for an eligible Copilot subscription.

Complete the provider-controlled sign-in flow, then reuse that provider connection across any model lanes that should use the subscription. See [Use existing AI subscriptions](subscriptions-provider-access.md) for the complete setup and billing distinctions.

### A practical first configuration

Use a fast, affordable model for Standard and Light. Use your strongest code-capable reasoning model for Hunter. You can initially let Design and Browser inherit or share a provider, then specialize them when you see a recurring need.

If the composer redirects you to AI Provider when you try to send, the selected preset does not yet resolve to an available provider and model.

### Local and compatible endpoints

Use **Add provider** when you have a local model server or an OpenAI-compatible proxy.

You must provide:

- stable provider and model IDs;
- a display label;
- the compatible API shape: OpenAI-compatible, OpenAI Responses, or Anthropic Messages;
- the base URL;
- an optional environment-variable name for the key;
- accurate context-window and maximum-output values;
- whether the model supports reasoning and vision.

Incorrect capability or context values can cause missing controls, invalid requests, or a misleading context meter.

## 2. Add a workspace

Use **Add Workspace** in the sidebar or press:

- macOS: `⌘O`
- Windows/Linux: `Ctrl+O`

Choose the project directory, not a parent folder that contains many unrelated projects. The selected directory becomes the default boundary for new tasks and integrated tools.

You can:

- pin frequently used workspaces;
- filter the sidebar by directory and activity range;
- right-click a workspace for its actions;
- open **Settings → Workspace** to configure the selected workspace.

Before asking for edits, inspect the repository’s current Git state in the Terminal or Git menu. Syntheo preserves existing changes, but neither the agent nor `git add -A` can infer which uncommitted files are disposable.

## 3. Index the workspace

Open **Settings → Workspace → Code Intelligence** and select **Index codebase**.

Indexing is worth doing when:

- the repository is unfamiliar or large;
- you ask architectural or cross-cutting questions;
- symbol names are more useful than exact strings;
- Architect or Hunter will need to trace call paths.

You can continue using normal file and text search without an index. For a tiny repository or a one-file task, indexing may not repay its setup cost.

Use **Sync index** after a substantial checkout, merge, rename, or refactor. Turning Code Atlas off keeps the existing index. **Clear index** removes only a Syntheo-managed index and does not change source files.

## 4. Check permissions

Open **Settings → Permissions**.

The default posture is **Ask**. A tool on Ask pauses before execution and shows its arguments in the thread.

For a first session:

- leave shell, file writes, Git-affecting tools, and network tools on Ask;
- allow read/search tools only if you are comfortable with their scope;
- leave unfamiliar MCP tools on Ask until you have inspected their server and arguments.

When prompted:

- **Allow Once** authorizes only that call;
- **This Turn** authorizes the tool for the active run;
- **Deny** rejects the call and lets the agent adapt or explain the blocker.

Use **This Turn** only after the first invocation shows the expected command, path, or URL.

## 5. Ask a read-only orientation question

Select the workspace, create a new thread (`⌘N` or `Ctrl+N`), cycle the secondary action to **Ask**, and send:

```text
Explain how this project starts in development.
Identify the main entry point, the command I should run, and the three files
I should understand first. Do not modify files.
```

This confirms:

- the provider works;
- the workspace is accessible;
- search/read tools work;
- permission prompts reach you;
- the response cites real repository evidence.

Use `@` in the composer to mention a specific file or directory if the answer is too broad.

## 6. Make a small isolated change

Create another new thread. Select the workspace and enable **Virtual Edit** beside the workspace selector. On macOS use `⌘⇧E`; on Windows/Linux use `Ctrl+Shift+E`.

Send a small Submit request:

```text
Update the empty-state copy in @path/to/component so it tells the user what
action to take next. Match the existing tone and styling. Run the narrowest
relevant check and summarize the exact file changed.
```

Why start with a Virtual Edit:

- the agent works in a separate Git worktree;
- the original working tree stays untouched;
- you can inspect the diff before integration;
- abandoning the experiment does not require manually undoing edits.

## 7. Review and integrate

Open **File Diff** (`⌘⇧D` / `Ctrl+Shift+D`) and inspect every changed file.

Then:

1. Read the agent’s final summary and validation result.
2. Open the integrated Terminal (`Ctrl+\``) and rerun the important check if needed.
3. Open **Git → Apply Layer** to merge the Virtual Edit into the real codebase.
4. Review the real working tree.
5. Stage only the intended changes. The menu’s **Add Current Changes** stages all current changes, so use the terminal for selective staging when necessary.
6. Commit after the staged set is correct.

## 8. Tune the experience

After a few tasks:

- assign stronger or cheaper models per preset in **AI Provider**;
- set a stable tone and response length in **Behaviour**;
- put project-wide preferences in repository instructions when they should travel with the codebase;
- install narrowly useful Skills or MCP servers through **Marketplace**;
- configure auto archive in **Workspace** so old threads do not crowd the sidebar;
- enable completion, permission, and error sounds in **Audio** if you run work in the background.

## First-session checklist

- [ ] Standard, Hunter, Light, and any used specialized lanes resolve to a model.
- [ ] Provider authentication succeeds.
- [ ] The correct project directory is added as a workspace.
- [ ] Code Atlas is indexed if the repository benefits from it.
- [ ] Tool permissions match your trust level.
- [ ] A read-only Ask task completes.
- [ ] A small Virtual Edit is reviewed and applied.
- [ ] The validation command succeeds in the real working tree.