Start here6 min readUpdated for Syntheo v0.4 Series

Getting started

© 2026 Quadropic Pvt Ltd. Proprietary Information. Use restrictions.

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 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.