Guide

The practical guide.

Set up your command-line AI tools on Windows, connect them in Orcheri, and make your first Room. One supported tool and one small task are enough to begin. If you still need Orcheri itself, start with the Windows installation guide.

A first useful result

Once your Alpha access is approved and this PC is set up, start small. One supported tool is enough.

  1. Connect one tool. In Connections & settings, check Claude Code, Codex, Cursor, Antigravity, OpenCode or GitHub Copilot CLI. Follow its setup action for a usable installation; supported tools explains which installation and account you need. Claude may still say Installed · sign-in not checked; the first task establishes whether that connection works.
  2. Make one Room. Choose a Room without a project folder and add your connected tool as a teammate. Give the Room a name you will recognize. In Who answers, choose Only that teammate.
  3. Ask one bounded question. Try: Help me plan a small personal website. Give me three possible pages and one question I should answer before building. Do not create files or use external tools.
  4. Read what happened. Read the answer and respond if Orcheri is waiting for you. A teammate reporting success, a project check passing and your own decision to rely on a result are different things. This first discussion does not claim a repository check.

Then add a second teammate or bring a project when the work calls for it. Your provider's usage limits still apply to this first task.

1. Connect your AI tools

Orcheri does not contain an AI. It runs the AI tools you have already installed and signed in to — Claude Code, Codex, Cursor, Google Antigravity, OpenCode or GitHub Copilot CLI — so the first thing it does is look for them.

It looks in a fixed order: an installation you chose yourself, then the command on your PATH, then the exact places each tool is known to install itself. It does not crawl your disks and it never reads a credential store. So the status Not found in checked locations means precisely that — not “you do not have it” — and the row tells you which places it looked in.

One thing catches people out, so it is worth saying first: Orcheri needs each tool's command-line tool, not its desktop app. Claude Code rather than the Claude desktop or web app. The Codex CLI rather than the ChatGPT app. Cursor's Agent CLI — which Orcheri runs as agent — rather than the Cursor editor. Google's Antigravity connection tool rather than the Antigravity app. The opencode command rather than the OpenCode desktop app. GitHub Copilot CLI rather than Copilot in an editor. Having the app or editor installed does not give you the command-line tool, and Orcheri says so rather than guessing.

The next thing to do is offered as a button rather than an essay: Install, Sign in, Connect, Update, Try again or Check connection, with Choose installation and Official instructions beside it. Paths, versions and evidence sit under Connection details rather than filling the screen.

Install the command-line tool Orcheri needs

These are official Windows installation methods. The Claude Code, Codex and Cursor commands were checked against their makers' pages on ; the Antigravity, OpenCode and Copilot CLI routes match the setup recipes Orcheri itself uses, as of . Run commands yourself in a normal PowerShell window, keeping the installer's prompts and your device's protections, or use Install now in Orcheri. Install one tool first; you do not need all six. Provider installation and sign-in are separate from setting up your Orcheri PC.

Claude Code

Use Anthropic's native Windows installer, then check that the executable runs:

irm https://claude.ai/install.ps1 | iex
claude --version

Follow Anthropic's installation instructions if the command fails. The native installation updates automatically. For Orcheri's Agent SDK connection, configure your own Anthropic API key or a supported cloud connection using Anthropic's Agent SDK authentication instructions. A Claude web or desktop subscription is not the supported authentication path documented here. For the API-key route on Windows, add a user environment variable named ANTHROPIC_API_KEY with your own key as its value, using Windows’ Edit environment variables for your account dialog. Start Orcheri from an environment that includes that variable; a variable set only in one terminal does not reach an app already open. Close and reopen Orcheri after the change; if the launcher still has the old environment, sign out of Windows and back in. Keep the key in your local provider setup, never in a Room or support message. Cloud authentication has its own configuration in the linked SDK guide.

Codex CLI

One official option is npm. Install Node.js with npm first if needed, then use the Windows command wrappers:

npm.cmd install -g @openai/codex
codex.cmd --version
codex.cmd login

Complete OpenAI's own browser sign-in under your account. The .cmd wrappers let this npm installation run from PowerShell without changing script policy; a native installation uses codex directly. OpenAI's Codex CLI guide lists current installation options; its authentication guide explains supported account methods. For an npm installation, the same install command updates Codex.

Cursor Agent CLI

Install Cursor's Windows command-line agent, then verify it and use Cursor's own sign-in:

irm 'https://cursor.com/install?win32=true' | iex
agent --version
agent login

The Cursor editor alone is not this tool. Use Cursor's CLI installation instructions and authentication guide. The CLI tries to update automatically; agent update asks it to update manually. Cursor can be a teammate in Orcheri today, and a compatible installation can also lead; Orcheri shows whether yours can.

Google Antigravity

Orcheri works with Antigravity through Google's own connection tool, agy_acp_server.exe. The Antigravity app does not supply it. In Connections & settings, choose Install for Antigravity: Orcheri shows what it will do, then downloads Google's archive (version 1.4.0, as reviewed) from dl.google.com only, checks that its bytes match the reviewed SHA-256 and that both programs inside carry Google LLC's signature, and unpacks them unchanged into %LOCALAPPDATA%\OrcheriRuntimes\antigravity-acp\1.4.0. Nothing is added to PATH. Run it yourself instead shows the same official download as PowerShell commands, hash check included.

Then choose Connect. Orcheri asks the helper whether you are signed in and which models your Google plan offers, and starts Google's own sign-in in your browser if you are not; a sign-in already on this PC may be reused. Google's terms for Antigravity apply to the helper and your account's use of it, and installing it is not a statement that Google supports Orcheri. Antigravity's documentation covers the product itself.

OpenCode

Orcheri runs OpenCode's command-line tool in its official ACP mode, opencode acp. The OpenCode desktop app does not add that command. Use the OpenCode 2 you already have, or choose Install: Orcheri downloads the reviewed OpenCode 2 release (2.1.2) from opencode.ai, checks its SHA-256 and its publisher's signature, and unpacks opencode.exe into %LOCALAPPDATA%\OrcheriRuntimes\opencode\2.1.2, adding nothing to PATH. OpenCode 2 is also published on npm; with Node.js and npm installed:

npm.cmd install -g @opencode/cli
opencode.cmd auth login

Which models work without a sign-in is OpenCode's and its providers' to decide; Orcheri lists the models OpenCode reports and does not label them free or paid. auth login signs in your own model providers — for a copy Orcheri installed, run & "$env:LOCALAPPDATA\OrcheriRuntimes\opencode\2.1.2\opencode.exe" auth login — and the OpenCode desktop app signs them in too, because every OpenCode 2 on a PC shares one data folder. The older opencode-ai npm package is OpenCode 1; if that shared folder still holds OpenCode 1 data, Orcheri does not start OpenCode 2 on it, because OpenCode 2 would convert it permanently. OpenCode's own permission settings decide when it asks before using a tool, and by its default it asks before nothing. OpenCode's ACP documentation.

GitHub Copilot CLI

Orcheri runs GitHub Copilot CLI through its own ACP server. Copilot in VS Code or another editor does not supply it. Use the Copilot CLI you already have, or choose Install: Orcheri downloads GitHub's reviewed standalone release (1.0.98) from the github/copilot-cli releases, checks its SHA-256 and GitHub, Inc.'s signature, and unpacks copilot.exe into %LOCALAPPDATA%\OrcheriRuntimes\copilot\1.0.98. It needs no separate Node.js, and nothing is added to PATH. GitHub also publishes it through WinGet, which installs the PowerShell 7 its package declares it needs:

winget install --id GitHub.Copilot --exact
copilot login

Run copilot login in a new PowerShell window after installing; for a copy Orcheri installed, run & "$env:LOCALAPPDATA\OrcheriRuntimes\copilot\1.0.98\copilot.exe" login. If you have signed in to the GitHub CLI (gh), Copilot can use that account by itself; Orcheri never runs gh or reads its sign-in. Copilot works under your GitHub Copilot plan, which counts its usage, including premium requests. GitHub describes Copilot CLI's ACP support as a public preview. GitHub's Copilot CLI ACP documentation.

After installation or an update, return to Connections & settings and press Check again. For Codex, Cursor or Copilot CLI, follow Sign in if requested; for Antigravity and OpenCode, choose Connect. Claude can remain Installed · sign-in not checked: that is an honest unknown, not a failed installation. Add it and try the first small task. If a tool remains missing, follow the missing-tool checks. Orcheri does not install or update these tools automatically.

What Orcheri's setup help will and will not do

When a tool is missing, Orcheri opens a small guide: the maker's own documented PowerShell command, a Copy command button, where the tool will be installed, and an alternative under If the installer command fails where the maker offers one. Install now runs only when you choose it, after showing what it will change: for Claude Code, Codex and Cursor, the provider's own installer, fetched from the provider and recorded by its exact digest; for Antigravity, OpenCode and Copilot CLI, the provider's reviewed archive, refused unless its SHA-256 and publisher signature match. Run it yourself instead shows the same steps for PowerShell. Cancel and nothing claims it succeeded; afterwards you press Check again.

What it never does, even to be helpful: it never installs a tool silently, never changes your provider's configuration, never bundles or ships an AI tool inside the Orcheri installer, never takes a credential from you, and never elevates itself. Orcheri itself does not edit your PATH; a provider's own installer may, and the guide says so before it runs. Signing in to a provider stays your act, in that provider's own flow. The install recipes are fixed, reviewed product recipes — never something a model wrote or a server sent.

You just installed a tool and Orcheri cannot see it

Press Check again first. A Windows installer often publishes new search paths that a program already running never receives, so Orcheri deliberately re-reads Windows' current published paths and registered installation locations each time you ask it to look again. If the tool still does not appear, close Orcheri and open it again — and tell us, because that is worth knowing.

If the tool is installed somewhere unusual, Choose installation opens a Windows file picker so you can point at it directly. Once you have chosen one, Orcheri refuses rather than quietly picking something else if that path later breaks — which is the behaviour you want when the wrong program would otherwise run your work.

2. Reading what Orcheri found

Each tool gets one short status line, and Orcheri deliberately does not compress six different facts into a single green dot. A dot that just says “connected” is a lie made of six answers, and when it is wrong you have no way to tell which one failed.

  • Ready · your accountInstalled, and the tool's own status command confirmed you are signed in. This is the state you want.
  • Installed · sign-in not checkedFound and usable, but Orcheri has not established the sign-in. You can add a teammate; the provider may still want setup.
  • Sign in neededThe tool is there and told Orcheri you are not signed in. Sign in shows its own login command.
  • Update neededThe tool ran but did not report an interface Orcheri can use. There is no minimum-version rule — this is about the interface, not the number.
  • Not found in checked locationsNot in your chosen installation, not on PATH, not where that tool normally installs itself.
  • UnavailableThe check itself could not finish. Worth a Try again before anything else.

Under Connection details the same row breaks into the facts it is made of — installation, interface, sign-in, account access, connection attempt, availability, when it was checked, what the evidence was, the version, and exactly which installation was used. Several of those can read unknown, and unknown is an honest answer rather than a failure.

One case that surprises everyone: a perfectly working Claude Code reads Installed · sign-in not checked, never Ready · your account. That is not a fault. Orcheri does not inspect Claude's authentication at all, so it has nothing to confirm and will not invent a confirmation. Add the teammate and see what happens.

If Claude's readiness is unknown, that is not a reason to buy a plan. Orcheri's supported configuration is your own Anthropic API key or a supported cloud connection, and Orcheri makes no claim about subscriptions either way. A free-plan label tells nobody — including Orcheri — whether a given installation can work.

Orcheri also tells you when it is working with a version it has not been tested against, rather than refusing it: it names the version it was tested on, says it will be used anyway, and suggests that difference as the first thing to check if something behaves oddly.

3. Your first Room

A Room is a place for one project, client or idea. Give it a name that means something to you. Everything in it — teammates, conversations, memory, decisions, files and results — is stored on your PC and is there when you come back. Your AI tools still send what they work on to their own providers, under your accounts, including the Room context Orcheri gives them for that work: what goes where.

4. Project or no project: pick deliberately

When you make a Room, Orcheri asks one useful question, and the three answers are all normal.

  • Create new project. Orcheri makes a new, empty folder where you choose it — your own Documents, say — and turns it into an ordinary Git repository on a main branch with an empty first commit. Nothing more. No remote, no Git hosting account, no push, and no change to your global Git identity. It will not write into a folder that already has files in it.
  • Use existing project. Point the Room at a folder you already work in. It needs to be a Git repository that is on a branch and has at least one commit — that is how a teammate's work can be told apart from what was already there. Your history, your branch and your uncommitted changes stay yours: Orcheri never resets, stashes or discards your own work, and its own use of Git is read-only.
  • No project. The right answer for research, writing, planning or thinking, and fully usable. A Room needs no folder at all.

Choose deliberately, because a Room's project folder is fixed when the Room is made — there is no “attach a folder later”, and every conversation in a Room works in that one folder. That is on purpose: a Room whose working directory could move is a Room whose history means something different depending on when you read it. If project work grows out of a projectless Room, Orcheri makes a new project-bound Room and carries the request you choose into it as an unsent draft. Your old Room stays exactly as it was.

Orcheri shows you where the project is and offers Show in folder, because a folder you cannot find is not really yours. While a teammate is working in a folder, Orcheri keeps other work in the same Orcheri profile out of that checkout so two teammates never write at once — it cannot hold back your own editor or another program, and it does not pretend to.

If Git is not installed

Orcheri checks that Git actually runs before it creates anything, so a missing Git means a clear sentence — “one-time setup needed: install Git, the free tool Orcheri uses to keep track of project changes. No Git account is needed” — with a Set up project support button that opens Git's own official Windows page, and Check again. Not a half-made folder and a dead end. Your Room name, your chosen parent folder and your project folder name all survive the detour. Git's mechanics stay behind a details toggle; you do not have to understand them to make a project, and no hosting account or remote repository is needed.

One thing worth knowing now rather than later: a project folder outside Orcheri's own storage is not included in an Orcheri backup, and neither is a repository you linked. Orcheri lists them as not included rather than pretending to protect them. Your project's safety net is your own Git history and your own backups.

Before your team can make changes

Orcheri asks you to acknowledge a limit of Stop: tools can hand work to other apps or services Orcheri does not own and cannot reliably stop, and that work may continue after Stop or Quit. The acknowledgement covers your project folder, or this Room if it has no project, in your profile on this PC. It is not repeated at every handoff. Accepting starts nothing — you carry on when you are ready — and you can revoke it later in the Room’s details. The full boundary and when it asks again.

5. Add teammates

  • A name and a responsibility. Plain words — “reviewer”, “builds the API”, “checks my reasoning”. This is what the teammate is told it is here to do.
  • The same tool more than once is an ordinary team. Two Codex teammates with different jobs disagree usefully. Be clear-eyed about what that is, though: teammates on one tool share that tool's sign-in, plan and usage limits. They are separate teammates, not separate accounts.
  • Make one of them the lead when you want one answer instead of a chorus. The lead is an assignment, not a product tier, and you can change it tomorrow.
  • Each teammate gets its own session in every conversation. Teammates never share a session. What the Room shares — its memory, your decisions, its files and the current work — reaches every conversation on purpose.
  • A model and how hard it thinks can be chosen where the tool offers a list; for OpenCode, so can one of its own agents. Agent default means the tool picks for itself, and Orcheri records which model it actually used each time. Where a tool offers no list — GitHub Copilot CLI's ACP mode offers none, so it runs on Copilot's own automatic choice — Orcheri says so rather than showing an invented one.
  • Which tool a teammate runs on cannot change. Everything else — name, role, model, colour — can. Changing them applies to the next piece of work; work already running keeps what it started with.

6. Ask for work, and stay in charge of it

The composer has a Who answers menu with four choices, and it shows your current one on the send row so you never send into the wrong shape: {the lead}, the lead — decides who works, and answers you; Everyone, in turn — each replies once, and later ones see the earlier replies; Everyone, open discussion — everyone weighs in, and you ask for more rounds; Only {a teammate} — nobody else replies. How it works explains when each is worth choosing.

Two controls decide how much you are interrupted, and both are yours:

  • How much the team may do — Ask me first, Work, ask when it matters (the default), or Keep going. This decides whether a permission a tool asks for reaches you. Your answer continues the same turn, and a “no” is a real answer rather than an error.
  • Until done — an allowance for work that should carry on without you. It runs only within the allowance you set and only while Orcheri is open. Orcheri keeps working when you minimise it; it does not keep working after you quit, and it will not pretend otherwise.

Stop ends processes held inside Orcheri’s execution boundary, including its running project check. Work a tool handed to another application or service may keep going after Stop or Quit. Orcheri explains that limit before the team can make changes. If it cannot confirm that work it owns has ended, it blocks further work and shows what needs attention. Delegated handoffs stay under Behind this answer: who was asked, what came back, when.

7. Use the result

When the team produces something you can actually use, Orcheri shows a Usable result card. It is dated and labelled as a teammate report, with the line “not independent verification or your acceptance” written on it, and it lists what was attempted and what is still needed. Reported, verified and accepted by you are three different things — the last is your own judgment, not a button — and a product that blurs them is lying to you politely.

  • Show in folder opens the file’s location when it is still available on this computer. If you moved or removed the folder, restore it or choose the file again. Your project source stays in that folder; a private Room backup does not include it.
  • Open file opens what can be safely opened, and refuses — with a reason — what should not be: “programs, scripts and active documents are not opened as ordinary files”.
  • Run result is a fresh decision each time you make it. It runs a named project or package script with an installed interpreter — never an arbitrary command — and carries no remembered permission from last time. It tells you plainly that repository code runs on your PC rather than in a sandbox, and that nothing installs or launches by itself. Stop running result is always beside it, and restarting Orcheri never silently relaunches anything.
  • Where a teammate reports a local address, Orcheri will open it — while saying that the address is the teammate's report, not proof the page is ready or correct.

8. Decisions and Room memory

Room memory is what every teammate should know in this Room, in every conversation. You write it, you edit it, and it is short on purpose.

Decisions are the choices you settled. When you answer a question clearly, that answer can become a decision the Room keeps — recorded with the question it answered, in your own words, and given to your teammates from then on. Orcheri never composes new wording for a decision, and an assistant's summary, your silence, a permission you granted or a continuity choice never become one. Supersede a decision and the history stays.

9. Coming back tomorrow

Home opens with one line about whether anything wants you — “nothing needs you”, “the team is working”, or a count of the things that do — and then what is running, what finished while you were away, and your Rooms. Every one of those lines names a person or a teammate rather than a status code: “waiting on your answer”, “needs your decision”, “could not continue where it left off”, “paused at a limit you set”. If Orcheri crashed mid-work, the work is resumable and comes with a sentence naming what the team was doing — not a shrug.

When a tool no longer has the session it was using, Orcheri starts a fresh one through the same official interface and hands the teammate its own work back from Orcheri's record. It never calls that a resume, and where the evidence is ambiguous it keeps the session and asks you instead of guessing.

Closing the window when work is protected does not silently kill it: Orcheri offers to keep working and minimise, to stay open, or to quit. There is no tray icon, no background service and nothing that starts itself with Windows.

Orcheri also never replaces itself silently. When a newer Alpha version is available to your account, an announcement appears at a calm moment after you open Orcheri — not while a question waits for you, work is running or a dialog is open — with the version, what's new, Update now and Skip for now, which lasts until you quit. Settings → Updates always shows this version and any available one. Update now opens your secure download page in your browser, where you download the installer and run it yourself after quitting Orcheri. How updating works.

10. Protect your work

Three different things, and none of them substitutes for another.

  • Backup my workPrivate local recovery material, written to a folder you choose. It holds Orcheri's own record and the files Orcheri owns; it never uploads, never syncs and is never a support attachment. It is not encrypted — Orcheri makes no encryption claim and tells you to keep it somewhere private. Anything outside Orcheri's own storage, including a linked repository, is listed as not included rather than quietly missed.
  • Restore from a backupRestoring never deletes anything. Orcheri checks the whole backup before it uses any of it, and says so: “nothing on this PC has changed yet”. Then you choose — Restore as separate Rooms, which leaves today's Rooms exactly as they are and lets you go back to them, or Replace the Rooms on this PC, which backs the current ones up first and sets aside what it replaced rather than deleting it. Work that was under way comes back waiting for you: none of it continues on its own.
  • Export a handoffA single plain-text document about one piece of work, for someone who does not use Orcheri — what it set out to do, what you decided, what was checked, what is still open. It gives nobody access to anything. You choose which sections go in, you can rename people, and you read the exact text that will be saved. It never carries prompts, delegated text, session identifiers, credentials, authority, other work in the Room, or captured provider history; addresses lose their private parts and folder locations become readable labels.

If Orcheri ever cannot open your profile at all, its refusal offers Restore from a backup beside Close, and the files it could not read are set aside rather than deleted.

One honest limit worth repeating: a handoff and a support message are both shown to you in full before they leave, because no automatic rule can recognise a secret you typed into a sentence. As the handoff preview itself says, people's own words can still hold something private — read it before you save it. The last check is yours.

Request Free Alpha Install help Something went wrong