User guide
Install Hotshot Orchestrator, add a workspace, start your first agents and find your way around the app.
- Installing
- Workspaces
- Starting an agent
- The hub
- The panels
- Settings
- Hotshot Sync and the phone
- Keyboard shortcuts
Short answers to common questions are in the FAQ.
Installing
Windows 10 or 11 (x64), or macOS 12 or later on Apple Silicon or Intel. Linux is not released yet.
At least one agent CLI on your PATH, such as Claude Code or Codex, signed in. Hotshot Orchestrator hosts no AI of its own: the model is whichever CLI the agent runs.
Download the installer for your system from the download page.
Run the installer. Until Hotshot Interactive's Windows code-signing certificate is in place, the installer is unsigned, so Microsoft Defender SmartScreen may show "Windows protected your PC". Choose More info, check that the file came from the download page, then Run anyway. This goes away once releases are signed.
Open the download and move Hotshot Orchestrator to Applications. Releases are signed and notarised by Apple, so it opens without a warning.
The keychain, once. The app keeps its secrets (Sync device keys, your account session, sign-in tokens for services you connect) in the macOS keychain. If you used a build from before the signed releases, macOS asks once per item whether Hotshot Orchestrator may use them. Enter your login password and choose Always Allow; you will not be asked again. Choosing Deny makes the app look like a new device to Hotshot Sync.
Screen Recording and Accessibility. Only needed for computer use (desktop-app workspaces). The approval card says when one is missing and has buttons to the right page of System Settings. Grant them once; they survive updates.
Installed apps update themselves from the download site. Settings → About shows the version and the last update check. To try releases early, switch the update channel to beta in Settings → General; beta users also get every stable release, and switching back to stable never downgrades.
Workspaces
A workspace is something your agents work on: a project, a folder, an application, a legal matter or a remote server. You add it with Add workspace and pick its kind. The kind decides what the agents in it get: which editor or app they share or take turns with, which MCP servers they are given, and which risky operations (a build, an editor restart, a playtest) the hub coordinates.
Every workspace has a card in the rail on the left. The gear on its card opens its settings.
Unreal Engine
Add a .uproject. Agents reach the project's editor through Unreal's MCP server, start on the shared editor and can take a playtest or headless editor of their own, or a git worktree. Play-In-Editor, C++ builds and restarts are taken in turn. Needs Unreal Engine 5.8 with the HotshotMCP plugin.
Unity
Add a project folder. The editor for the project's version is found through the Unity Hub. One editor per checkout, shared by every agent; an agent that needs its own takes a git worktree. Uses Unity's unity mcp server (Unity 6 or later) or any server you set.
Godot
Add a project.godot. Agents get the editor, a headless reimport under the build lock, and the MCP server you set in the workspace's settings, since Godot ships none.
Code repository
Add any folder, ideally a git repository. Agents work in the checkout, or take a git worktree of their own when a change needs one. A build command set on the workspace runs one at a time. Review and merge in the Changes panel.
Desktop app
Add an .exe or .app. Agents drive it by looking at the screen and using the mouse and keyboard, only in the apps you approve. Esc stops the agent acting; Pause, or Ctrl+Alt+Esc (Ctrl+Option+Esc on a Mac), stops every agent's input.
Legal matter
A folder for a case, a dispute or a contract, in any jurisdiction you name. Agents take files in as exhibits with hashes and a custody log, search them, and keep a chronology, deadlines and sources. Nothing is filed without your approval. Hotshot is not a lawyer.
Remote MCP
Add a third-party MCP server by URL (Figma, Linear, Notion or your own). Connect signs you in in your browser, or takes a pasted API token. Use it on its own, or link it into any other workspace from that workspace's settings.
Packages
More kinds of workspace, free, from Add workspace → More workspaces (the first is SQLite). Packages come from a reviewed, signed registry. The Set up card shows the publisher, what the package may do and its size. Updates keep the previous version for Roll back.
Mixed shows every workspace together. Modes shows one kind at a time while the others keep running; a badge on each mode counts hidden agents that need you. Switch in Settings → General or with Ctrl+[ and Ctrl+].
Stop its agents first, then use the × (Remove workspace) on its card. The app forgets it; nothing on disk is touched, and editors or apps it started keep running.
Starting an agent
Open New agent, choose the workspace and the CLI's card, and optionally type a first prompt. Up to eight agents run at a time. Each one gets a real terminal, its own name, and the hub.
- Claude Code: the full integration, with hooks, live status and claim enforcement.
- Codex: MCP tools and hooks, with live status and exact resume.
- Antigravity and OpenCode: MCP tools.
- A shell command: any other program, run as a plain terminal.
Nothing changes in your global CLI settings or your project's files: the app hands each agent its own configuration when it starts it.
Have a work and a personal plan? Settings → Agents → Agent CLI accounts adds a second login of Claude Code or Codex. You sign in inside the CLI, in an agent pane, then pick the account on the CLI's card when you start an agent. Agents never switch accounts by themselves.
Arrange panes as a grid (auto, side by side or stacked) or as tabs. Drag to reorder, maximise one, or pop it into its own window. Drop files on a terminal: images are pasted as images, other files as their paths. Dictation tools such as Wispr Flow type straight into the terminal.
A stopped agent can be resumed or forgotten. Forget asks first and removes the agent from the app; its conversation stays in the CLI's own history, and a clean git worktree is removed.
Now and then an agent asks for another agent to help. A card shows who asks, why, the task and the CLI; you approve, change it, or deny. Settings → Agents → Agents may start agents: Off, Ask each time (the default) or Allow.
The cup in the top bar keeps your computer from sleeping: While agents work (and ten quiet minutes after, the default) or Until I turn it off. It always ends when the app quits.
The hub
How agents keep out of each other's way. Every agent gets hotshot-hub, and the agents use it themselves; you watch it in the panels.
Claims
Before an agent edits a file or asset, it claims it. Another agent's write to a claimed path is refused, not just warned about, and every file an agent writes is claimed for it automatically.
Plans
Each agent publishes the steps it means to take and marks them done as it goes. Other agents see them, and overlaps are flagged. A pill on the agent's pane shows its plan.
Messages
Agents write to each other by name. An idle agent is woken by a message; a busy one reads it at its next step.
Leases and locks
Things only one agent may do at a time: play in the editor, restart it, run a build, use the mouse and keyboard. An agent takes the lease, others wait their turn, and results that arrive later are typed into the agent's terminal.
Memory
A shared team memory: agents write down what they learned, and later agents, in later sessions too, search it.
The panels
The drawer beside the terminals. Some panels only appear for the kinds that use them.
What needs you: permission prompts, finished turns, conflicts, approval cards. Clear all asks first.
Documents your agents produce, including ones made by scripts, and those on your paired devices. Search ignores accents, so "sozlesme" finds "Sözleşme". Filters narrow by type, and you can sort, see Recent, and browse by folder. Works with the keyboard.
Every agent's plan and the status of each step.
Which agent holds which files, assets and locks. You can release a claim; it asks first.
What the agents and the hub have been doing, as it happens.
The messages agents send each other.
The team memory agents share.
Code repositories and Unreal projects. What each live agent changed since its branch point, with a coloured diff per file. Merge back brings a worktree branch into the checkout when both sides are clean, and you can open a pull request (needs gh).
Desktop-app workspaces. Every screenshot an agent took while using the computer.
Legal matters. Exhibits, timeline, statements, deadlines, notes, sources and the custody log. Mark a deadline Done (and Undo it) and add a Note to an exhibit or the matter.
Settings
Update channel: stable or beta.
Language: English, Türkçe, or System to follow your operating system. Switches without a restart.
Interface size: 90 to 150 %, also with Ctrl+=, Ctrl+- and Ctrl+0 (Cmd on a Mac).
Also here: theme, view, the terminal's font, scrollback and cursor, launch at login, reopen agents after a quit, confirm before quitting, keep awake, keyboard shortcuts, the data folder (moving it copies your data and restarts the app there; Sync stays paired), and export and import of your settings.
Two switches, both off until you turn them on: Crash reports (version, operating system, the error and its stack trace) and Usage statistics (version, operating system, the kinds of workspace in use, how often each view is used). Neither contains your name, account, files or prompts. Read the privacy policy.
The version, your operating system, the app's folders and the support address.
Report a problem makes a zip with the recent log, the version and the platform, and shows it in your file manager. Nothing is sent: attach it to an e-mail to support@hotshotinteractive.com.
Recent errors lists what went wrong lately, with Copy all.
Restore a state backup puts your workspaces, agents and settings back as they were in an earlier backup. It works only while no agent runs, and keeps a copy of the current state first.
Also the third-party notices and links to the licence, privacy policy and Sync terms.
Sign in, pair devices, give each device a permission, remove devices, Export my data and Delete account. See below.
Agents: CLI accounts and whether agents may start agents. Desktop app: computer use for every agent. Workspaces: developer mode for package authors. Each workspace kind adds its own settings.
Hotshot Sync and the phone
Your agents on your other devices. Optional, and a free beta for now: everything local works without it.
On your first computer, open Settings → Hotshot Sync and sign in with a Hotshot account. On the next device, sign in to the same account; it waits for approval.
Both screens show the same eight-digit code, such as 1234 5678. Check that they match, then Approve on the device that is already in. The server alone can never add a device. A device on an older version is asked to update before it can pair.
Each device gets a permission: View, Control or Full. Control starts agents and types into their terminals, which is as much as running commands there: give it only to your own devices.
Paired devices appear in the rail with their own workspaces. Their agents show in the grid with a device chip, and New agent can start an agent on another device.
Get the Android app from the download page. Sign in with the same Hotshot account and approve the phone on a computer. It lists your computers and their agents, those that need you first. Open one for its live terminal; tap to type, with a key bar for Esc, Tab, the arrows, Enter and Ctrl-C. Push notifications tell you when an agent needs you or finishes. The phone runs no agents itself.
Everything between your devices is end-to-end encrypted; the server routes it without being able to read it. Export my data writes what the service holds about your account to a file in the data folder. Delete account removes your account from the service, clears this device's Sync keys, and disconnects your other devices. Your local workspaces and agents stay.
Prefer your own server? The relay is open source (MIT) and runs with one Docker command; it needs no accounts, and devices join with an invite code instead.
Keyboard shortcuts
Press ? anywhere outside a terminal for the full list. Rebind any shortcut in Settings → General → Keyboard shortcuts; the sheet and the tooltips follow.
Inside a focused terminal on Windows, keys such as Ctrl+[ and Ctrl+K go to the program running there, so vim and your CLI keep working. Click outside the terminal to use them in the app.
Ctrl+K (Cmd+K): the command palette.
Ctrl+[ / Ctrl+]: switch between Mixed and Modes.
Ctrl+=, Ctrl+-, Ctrl+0 (Cmd on a Mac): interface size up, down, reset.
Esc: stop the agent using the mouse and keyboard right now. Ctrl+Alt+Esc (Ctrl+Option+Esc): stop every agent's input.
In dialogs, Tab stays inside the dialog and Esc closes it. Dangerous buttons put the focus on Cancel.
Read the FAQ, or write to support@hotshotinteractive.com with the zip from About → Report a problem. See how to get help.