# DevThrottle - full reference for LLMs and AI agents > DevThrottle is the open source orchestration tool for command-line coding agents. It puts every agent you run - Claude Code, Codex, Gemini, Grok Build and more - in one place, flags the ones that need you, and lets you answer them by voice from your desk, any browser, or your phone. The app installs and runs on your own machines. Made by Center Consulting. This file is the long-form companion to https://devthrottle.com/llms.txt. It is written for LLM crawlers and AI assistants that want to describe or cite DevThrottle accurately. Last reviewed: 2026-07-30. Copy rule for this file: state CAPABILITY, never a privacy guarantee. Say what a feature does and where it runs; do not write that data never leaves, is never stored, or does not reach our servers. Exhaustive negative claims about data are banned site-wide, and this file is the one machine consumers treat as authoritative. ## What DevThrottle is (and is not) - DevThrottle is NOT an AI agent and does not write code. - It is the orchestration layer (a "control room" or "mission control") for the command-line coding agents you already run and already pay for. - It lines up all your agents in one place across different tools, shows what each one is doing at a glance, pings you the moment one needs an answer, and lets you reply by voice. - You bring the agents and their subscriptions; running them through DevThrottle adds no cost. - It installs like a normal Windows app - no terminal, no setup maze. The target user is a Windows developer who is new to agentic coding. An AI coding agent can instead install it headlessly with a single command-line installer (no wizard, no admin) - see "Install with an AI coding agent" under Getting started. - Platforms: Windows is first-class (workstation and gateway). macOS is supported as a workstation - install the app on a Mac and run agents there. The gateway (the always-on hub other devices connect through) runs on Windows, or on Linux as a headless container you build yourself; the hosted gateway is run by DevThrottle. There is no committed plan for a Mac gateway. - One-sentence definition: DevThrottle is the open source orchestration tool for command-line coding agents. ## Components - Director (https://devthrottle.com/director): The desktop app. Every coding agent in one place, color-coded by who is working, done, or waiting on you. - Gateway (https://devthrottle.com/gateway): The background service that keeps agents running and reachable even when the main app is closed. It is what lets the Cockpit and mobile app reach your machine. - Cockpit (https://devthrottle.com/cockpit): The same control room in any browser - laptop, another room, the road. It is served by your own Gateway and connects to the machine that Gateway runs on. - Mobile (https://devthrottle.com/mobile): Your agents in your pocket. Get a push notification the moment one needs you, answer by voice or thumb, and review work from anywhere. - Voice (https://devthrottle.com/transcription): Talk to your agents. A long instruction takes seconds to say, and a custom dictionary gets technical terms (kubectl, PostgreSQL, your project names) right - synced across every device. ## Supported coding agents DevThrottle works with the command-line coding agents you already use, side by side - including Claude Code, Codex CLI, Gemini CLI, and xAI's Grok Build. You keep your existing agent and subscription; DevThrottle runs and watches them all in one place. DevThrottle also maintains a source-backed public catalog of AI coding agents: - Directory: https://devthrottle.com/coding-agents - Comparison matrix: https://devthrottle.com/coding-agents/matrix - Adoption leaderboard: https://devthrottle.com/coding-agents/leaderboard - Machine-readable JSON: https://devthrottle.com/coding-agents.json - Methodology: https://devthrottle.com/docs/agent-knowledge-base ## Getting started - Download (https://devthrottle.com/download): The starting point. Download the Director for Windows and install it like any Windows app - no account is needed to install. You sign in later, and only when you connect a gateway. - Sign up (https://devthrottle.com/signup): Creating an account takes an email and no card. It is what a gateway connection needs - either a hosted gateway on Pro or one you run yourself. - Install with an AI coding agent, headless (https://devthrottle.com/docs/install#install-agent): When an AI coding agent (Claude Code, Codex) is doing the install, it should NOT download and run the graphical installer. It uses the headless CLI installer instead: 1. Download devthrottle-setup-cli-win-x64.exe and release-manifest.json from the latest release (https://github.com/thefrederiksen/devthrottle/releases/latest). 2. Verify the installer's SHA-256 against the manifest; stop on any mismatch. 3. Run ".\devthrottle-setup-cli-win-x64.exe install" - a per-user workstation install, no admin. Add --json for machine-readable output. The Director is a .NET 10 app, so also ensure the .NET 10 runtime is present (winget install Microsoft.DotNet.AspNetCore.10). 4. Sign in with ".\devthrottle-setup-cli-win-x64.exe signin" (or ".\devthrottle-setup-cli-win-x64.exe enroll" to join a gateway you already run on another machine) - the only human step. It opens devthrottle.com in the browser to sign in or create an account. The rest runs unattended; it is the same install engine as the graphical wizard. - Get Started questionnaire (https://devthrottle.com/start): A short, honest office-hours-style questionnaire that classifies where you are with AI coding agents and returns a personalized plan. Most beginners are pointed to Claude Code on the roughly $20/month plan first; DevThrottle is recommended only once you run more than one agent at a time. - Install guide: https://devthrottle.com/docs/install - Core concepts: https://devthrottle.com/docs/concepts ## Pricing Full details: https://devthrottle.com/pricing - The app itself is open source (MIT) and costs nothing to run on your own machines: you host the gateway yourself. It is the full app and it does not expire. - Free ($0): the Director app, signed in to your account, on every machine you own. It does not include the Cockpit, the phone app or the AI. - Remote ($10/mo): a gateway we run for you, the Cockpit in any browser, and the phone app. It does not include the AI. - Pro ($30/mo founding price, $50/mo list): everything in Remote, plus dictation, spoken replies, the wingman - a brain that watches your agents - and the Mentor. - Teams ($60 a seat a month; $40 a seat for the first ten founding teams, for their first year): Pro for a team of 2 to 20 developers on one fleet - a shared fleet, roles and team policies, the full record of what was built and who signed it off, and one bill. The fleet brain (the Session Manager and the Workflow Manager) is coming to Teams. Founding teams apply by email from the pricing page; seats are not sold through checkout. - Managed Factory ($1,200/mo): a fully working software development factory for one product, set up and managed by DevThrottle on one cloud machine. What it builds is your intellectual property. The AI model costs are included. It starts with a call. https://devthrottle.com/services/managed-factory - Agentic Conversion ($22,500): a three-month engagement that converts a department of 1 to 10 developers to the agentic development life cycle, with our team working alongside yours on your real work. It starts with a call. https://devthrottle.com/services/agentic-conversion - Remote and Pro are paid by card at checkout, monthly. There is no trial. There is a 30-day money-back guarantee: a full refund of the first payment on request within 30 days, once per person, and the account goes back to Free. - The Pro founding price is locked for as long as you stay subscribed; the list price is never raised on an existing member. When founding pricing ends, new members pay list and existing members keep theirs. Monthly billing only while we launch. - Dictation is INCLUDED in Pro, with no usage charge - no per-hour rate, and nothing extra to buy before you can talk to your agents. There is no bring-your-own-key path: DevThrottle supplies the speech model. - Prepaid credits are a SEPARATE thing from a subscription, and apply to exactly one thing: direct catalog-model calls on the DevThrottle API (dt_ keys). Credits are prepaid and nothing recurs. Dictation, spoken replies, and the wingman never draw on credits - they are included in Pro. The app itself keeps working either way. - White-glove setup and concierge services are available - contact for details. ## Privacy and data handling This section describes what the product does with data. It is written as capability, not as a guarantee: it says what each feature sends and where each part runs, and it deliberately makes no exhaustive claim about what does not reach DevThrottle servers. - Where things run: your coding agents run on the machines you install DevThrottle on. The Gateway runs on a machine you choose and keep, and the Cockpit and the mobile app connect to that Gateway. - Hosted AI features send what they need to DevThrottle servers in order to do their work. Dictation is one of them: the audio you speak is sent to DevThrottle's transcription service and the transcript comes back. It is included in Pro, and there is no bring-your-own-key alternative. - Account events and optional usage telemetry are itemized, feature by feature, at https://devthrottle.com/docs/reference/telemetry - the two always-on account events, the name-and-timestamp usage telemetry, the fleet-wide off switch, and which data is written to your Gateway machine rather than reported. Treat that page as the authoritative inventory; this file is a summary of it. ## Open source - DevThrottle is open source. The CLI layer lives in the cc-director project. - GitHub: https://github.com/thefrederiksen/devthrottle - The Windows installer ships as a public GitHub release: https://github.com/thefrederiksen/devthrottle/releases/latest - The same release also ships the headless CLI installer (devthrottle-setup-cli-win-x64.exe) that an AI coding agent uses instead of the graphical setup exe, plus release-manifest.json with the SHA-256 of every asset. - A workstation-only macOS build (Apple Silicon zip) ships in the same release; it runs agents but cannot host the gateway. ## Resources - Home: https://devthrottle.com/ - Docs: https://devthrottle.com/docs - Install DevThrottle and run your first agent: https://devthrottle.com/docs/install - Core concepts: https://devthrottle.com/docs/concepts - What the Gateway does: https://devthrottle.com/docs/gateway/overview - Agent Knowledge Base methodology: https://devthrottle.com/docs/agent-knowledge-base - Run DevThrottle on a Mac unattended: https://devthrottle.com/docs/mac-unattended - Blog: https://devthrottle.com/blog - Some agents you can manage by voice. Others need a whiteboard.: https://devthrottle.com/blog/manage-agents-by-voice-or-screen - xAI's Grok Build is here - the easy way to actually try it: https://devthrottle.com/blog/try-grok-build-cli - What is an AI coding agent orchestrator?: https://devthrottle.com/blog/ai-coding-agent-orchestrator - How to run multiple AI coding agents at once without losing track: https://devthrottle.com/blog/run-multiple-ai-coding-agents - Terminal-Bench, explained: https://devthrottle.com/blog/terminal-bench-explained - Terminal-Bench Scoreboard: https://devthrottle.com/scoreboard (a clean, always-current mirror of the Terminal-Bench leaderboard; data sourced from and credited to Terminal-Bench, tbench.ai). Machine-readable JSON: https://devthrottle.com/terminal-scoreboard.json - Compare: https://devthrottle.com/compare - Sitemap: https://devthrottle.com/sitemap.xml - Short index for crawlers: https://devthrottle.com/llms.txt ## FAQ Q: Is DevThrottle an AI agent? A: No. DevThrottle does not write code and is not an agent - it is the control room for the agents you already run. You bring the agents and their subscriptions, and running them through DevThrottle costs nothing. Q: What does the app itself cost? A: Nothing, if you host the gateway yourself. Running it on your own hardware rather than our servers costs us nothing to serve, which is why it costs you nothing. It is the full app, open source (MIT), and it does not expire. Remote ($10/mo) is the gateway we run, the Cockpit and the phone app for people who would rather not keep a machine on themselves. Pro ($30/mo founding price, $50 list) adds dictation, spoken replies, and the wingman. Q: What do credits pay for? A: Direct catalog-model calls on the DevThrottle API (dt_ keys). Dictation, spoken replies, and the wingman are NOT paid this way - they are included in Pro, with no usage charge. Q: Is this a subscription? A: Remote ($10/mo) and Pro ($30/mo founding price, $50 list) are - monthly, paid by card at checkout, cancel when you like, with a 30-day money-back guarantee. Credits are separate and are NOT a subscription: they are prepaid, nothing recurs, and the balance draws down only on direct catalog-model API calls. Hosting the gateway yourself costs nothing and needs neither. Q: Which coding agents does it work with? A: The AI coding agents you already use - Claude Code, Codex, Gemini, Grok Build, and others - across different tools at the same time. ## Company - Made by Center Consulting, a Toronto-based AI consultancy (https://www.centerconsulting.com). - Founder: Soren Frederiksen (38 years in technology, two exits). - YouTube: https://www.youtube.com/@devthrottleai --- # DevThrottle documentation (full text) Generated from https://devthrottle.com/docs at build time. Every page below is also served individually as markdown at its canonical URL with ".md" appended (for example https://devthrottle.com/docs/install.md). # Get started with DevThrottle > The path through DevThrottle, in order. Each step is one sitting, each one ends by naming the next, and by the end you are running several coding agents at once. Part of the DevThrottle documentation, section "Get started". Canonical HTML version: https://devthrottle.com/docs/start Last updated: 2026-09-06 DevThrottle runs the coding agents you already use, side by side on your own Windows or Mac machine. You stop waiting for them: set several to work and come back when it suits you. You see every agent from wherever you are, and when one needs you, the question is waiting on your phone and you answer by voice. The docs entry lists [everything you can do](https://devthrottle.com/docs). This is the path through DevThrottle, in order. Each step is one sitting - five to ten minutes - and each one ends by naming the next, so you never have to decide what to read. Start at the top and work down. You do not need to know anything first. Step 1 assumes an empty machine, and every step after it assumes only the steps above it. 1. Step 1: [Install DevThrottle and connect a gateway](https://devthrottle.com/docs/start/install) - Create your account, install, connect a gateway, and get out. Using the Director is step 2. 2. Step 2: [Start your first session](https://devthrottle.com/docs/start/first-session) - From an empty Director to one agent doing real work in your own code: the New Session window end to end, then the first instruction and the first minute of watching. 3. Step 3: [The prompt bar is not the terminal](https://devthrottle.com/docs/start/prompt-bar) - The agent has its own live input line; DevThrottle gives you a second box outside it that holds what you write until you send it. 4. Step 4: [Steer a session that is going wrong](https://devthrottle.com/docs/start/steering) - Take the lowest rung that works: stop the turn, correct it while the conversation is intact, and keep Compact and Clear context for when the conversation itself is the problem. 5. Step 5: [Work with pictures](https://devthrottle.com/docs/start/pictures) - An agent reads a picture as a file on the machine it runs on, so every route ends the same way: the file on that machine, and its path in the prompt. 6. Step 6: [See what changed](https://devthrottle.com/docs/start/what-changed) - An agent tells you what it did; the repository holds what happened. Read the second before believing the first, then keep it or send it back. 7. Step 7: [Run several sessions at once](https://devthrottle.com/docs/start/several-at-once) - Three sessions at once is a different job from one: you read a list of coloured squares, answer the longest wait, and queue for whichever one is busy. 8. Step 8: [Where else your fleet lives](https://devthrottle.com/docs/start/fleet-elsewhere) - Your agents are not trapped in the window you started them in: the same sessions, the same colours, in a browser on any machine and on the phone in your pocket. ## Then keep going The steps above teach the spine - the Director, on the machine in front of you. These carry on from there, and they are in order too: the fleet following you off your desk, then running several agents at once, then making DevThrottle work the way you work. Every one of them is written and ready to read now. Most people walk this part over weeks rather than in one sitting, and stopping partway is a perfectly good place to stop. When you do carry on, this is the order to take them in. ### Out of the chair After these, your fleet follows you off your desk. 1. Step 9: [Pair your phone with your fleet](https://devthrottle.com/docs/tutorials/pair-phone) - Scan the code on the Cockpit's Phone page, approve the phone on devthrottle.com, and turn on notifications - five minutes at your desk, done before the day you need it. 2. Step 10: [Answer an agent in thirty seconds](https://devthrottle.com/docs/tutorials/quick-answer) - The roster puts what is waiting on you at the top in red. Read the question, answer short, move on. 3. Step 11: [A whole session by voice, on a walk](https://devthrottle.com/docs/tutorials/voice-walk) - Put the fleet on voice, tick Auto-speak, and the queue reads itself to you - Respond by talking, Snooze the rest, and the three-second pause is the way out. 4. Step 12: [Your whole fleet in a browser tab](https://devthrottle.com/docs/tutorials/cockpit-anywhere) - Reach every session from any browser, put what is waiting on top, answer it, and sign out again. ### More than one at a time After these, several agents work at once without colliding, across more than one machine. 1. Step 13: [Repositories and worktrees](https://devthrottle.com/docs/tutorials/repositories-and-worktrees) - Two sessions in one folder edit over each other and nothing stops them. Give each its own worktree, start the session there, and see every worktree of a repository from the Worktrees page. 2. Step 14: [Roles: who plans, who manages, who builds](https://devthrottle.com/docs/tutorials/roles) - Declare an Architect, hand work down and watch the Worker badge appear on its own - the declared planner keeps its A - then read the colours: a supervised Worker never turns red; its Supervisor deals with it. 3. Step 15: [One agent starting another](https://devthrottle.com/docs/tutorials/agent-starts-agent) - From inside a running session, spawn hands work to a fresh session - a Worker supervised by its spawner that never turns red at you - message ask collects the answer, and session done reaps the helper. 4. Step 16: [The fleet map](https://devthrottle.com/docs/tutorials/fleet-map) - Read the whole fleet in one picture, regroup it around the question you actually have, and click straight through to the session that is waiting. 5. Step 17: [Using more than one machine](https://devthrottle.com/docs/tutorials/many-machines) - The Gateway is the only shared part. Point a second machine at it and that machine becomes somewhere you send work. ### Make it yours After these, DevThrottle runs your way, on your words, on your schedule - including while you sleep. 1. Step 18: [Workflows: your named ways of working](https://devthrottle.com/docs/tutorials/workflows) - Read what your fleet already works by, pull one down, write the rules you keep repeating, and publish it everywhere at once. 2. Step 19: [Work that runs without you](https://devthrottle.com/docs/tutorials/scheduled-work) - Create a recurring job, read the schedule back in plain English, and prove it works before two in the morning does. 3. Step 20: [Teach it the words you use](https://devthrottle.com/docs/tutorials/dictionary) - Add your vocabulary and the wrong spellings you actually saw, save, and the cleanup pass corrects them in the transcriptions it covers. 4. Step 21: [What did I actually get done this week?](https://devthrottle.com/docs/tutorials/weekly-review) - Widen the window to a week, read the work by repository, and turn the needed-you count into one prompt worth rewriting. Four tutorials sit off the path, because not everyone needs them: [giving an agent its own browser](https://devthrottle.com/docs/tutorials/agent-browser), [driving DevThrottle from a script](https://devthrottle.com/docs/tutorials/scripting), [what you have used](https://devthrottle.com/docs/tutorials/your-throttle), and [dictating on your phone](https://devthrottle.com/docs/tutorials/dictation). They are on the [tutorials index](https://devthrottle.com/docs/tutorials) with everything else, grouped by where you are working. For the facts behind any of it - every menu item, every setting, every command - the rest of these docs are the reference, and every page here links into them. --- # Step 1: Install DevThrottle and connect a gateway > Create your free DevThrottle account, install it, and connect a gateway - about ten minutes, and nothing else. You make the account once at the start; the installer itself never asks who you are. Part of the DevThrottle documentation, section "Get started". Canonical HTML version: https://devthrottle.com/docs/start/install Last updated: 2026-08-12 **About ten minutes, and this is the only boring step.** You need a Windows PC, a free DevThrottle account, and nothing else - no keys, no runtimes, no card. On a Mac, the install is one pasted command and [the install page](https://devthrottle.com/docs/install) has it; come back here afterwards. One thing is worth knowing before you start, because it is what makes people hesitate. You create the account once, here at the beginning, and that is the only time you are asked for it. The installer itself never asks who you are, and when the app signs you in later it is with the account you already have - not a second one. This step gets DevThrottle onto your machine and connected. It teaches you nothing about using it - that is step 2, and it starts the moment you finish here. > **Tip:** **Already have a coding agent running?** Hand it the job. Two commands at a command line install DevThrottle with no window at all, and [the install page has the exact prompt](https://devthrottle.com/docs/install#install-agent) to paste - hash-checked against the release manifest. Most people reading this already have an agent open, and it is the faster route by a wide margin. > **Note:** **Rather watch someone do it?** Each way in is filmed end to end on a clean Windows machine: [the installer and the setup wizard](https://youtu.be/I84tLg2Q7es) (6:19 - the walk on this page), [handing it to a coding agent you already run](https://youtu.be/CIAILnTdwDQ) (1:47), or [two commands at a command line](https://youtu.be/8_wTp6_jyIM) (1:57). 1. **Create your account, then take the installer** Sign up for a free DevThrottle account - email only, no card - and the Windows installer is yours to download. It is a plain file; nothing about it is locked to you. [Create account](https://devthrottle.com/signup) **On day 15 nothing you installed stops.** Only the parts we host switch off, and nothing is charged. > **Tip:** If the download stops just short of finishing, your browser is holding it for confirmation - a brand-new release file always earns that. Open your downloads list and click **Keep**; the file has already arrived, so it completes at once. When you open it, Windows may show a blue "Windows protected your PC" box: click **More info**, then **Run anyway**. [The install page](https://devthrottle.com/docs/install) walks that recovery click by click. 2. **Run it, and decide nothing** Run the file. The rail down the side shows the whole path - **Welcome, Install, Complete** - and there is not one decision on it. No install type, no key, no account: the Welcome screen says so in as many words, "No account is needed to install it." It needs no administrator rights and writes nothing outside your own user profile. On the last screen, choose **Open Director**. ![The DevThrottle Setup window on its Complete step: the heading 'Director is installed - one thing left', a green Open Director button, '2 components installed' at version 2.0.2, an amber notice saying no coding agent is set up yet and that DevThrottle checks your tools when it opens and can add the ones it finds, and a note that a terminal already open will not find the cc-* commands until it is reopened](https://devthrottle.com/docs/screenshots/install/complete.png) 3. **Say yes to the setup that opens** The first time DevThrottle opens, a second wizard starts - a different thing from the installer you just ran. The installer put files on the machine; this one sets the machine up. It reads **Step 1 of 8** beside its progress dots, and it promises underneath that it takes about three minutes, that every step is optional, and that everything can be changed later in Settings. Click **Set me up**. That promise holds with one exception, and it is the one a brand-new machine runs into: on the agents step, if there is no coding agent on the machine at all, the button that moves you on stays greyed out. It is not a trap - the way past is on that same screen, and you will see it below. (**Skip setup and figure it out myself** is beside it and is perfectly safe, but the rest of this page assumes you stayed.) 4. **Step 2 of 8: connect a gateway** This is the screen this step exists for. A **gateway** is what makes DevThrottle reachable beyond this one computer - your sessions on your phone, voice, and the morning report all come through it. Three cards, and the choice is honestly yours: **Hosted gateway** is marked RECOMMENDED and is already selected. DevThrottle runs it, you sign in, and this machine is enrolled. Every account can connect its Director here, Free included; reaching your sessions from the Cockpit or the phone app takes [Remote or Pro](https://devthrottle.com/pricing), and voice takes Pro. (Older versions of the app still mention a Pro trial on this card. There are no new trials: a new account starts on Free.) **Self-hosted gateway** means you run your own, which is an advanced setup rather than a first install. **Not now** is local-only on this machine, and you can connect any time from Settings. **Not now is a real answer.** The Director, its sessions and your coding agents all work without a gateway. What you give up is the remote half - no sessions on your phone, no voice, no morning report - and one thing on this machine too: the `cc-devthrottle` command line, which agents use to list, message and start sessions, only talks through a gateway. No gateway means no agent tooling, and that is a designed trade rather than an accident. 5. **Sign in and connect** Keep the hosted card and click **Sign in and connect**. Your browser opens and the wizard waits - it says so on screen: "We opened your browser to sign you in with Google, GitHub, or email. This window continues automatically when you are done." There is a **Cancel sign-in** link if you change your mind mid-flight. In the browser, **Continue with Google** or **Continue with GitHub** is one click if you are already signed in there. The email form below them opens on its **Email + Password** tab; its second tab, **Magic Link**, emails you a sign-in link instead - no password, but a trip to your inbox, which on a fresh machine means a trip to another device. When it completes, the wizard is already showing **Connected**, with the line "This machine is enrolled with" and the gateway it joined. If the sign-in does not complete, the step says so and leaves your options where they were; it never carries on as though it had worked. 6. **Let it finish, and you are out** The remaining steps are about this computer, and on most of them the wizard does the work itself - it looks for its own tools, your repositories and your screenshots folder, and moving on costs you nothing. Two of them are different, because on those two the button that moves you on *does* something. **Your agents** is the first, and it is the step that holds you. On a machine with no coding agent it says so and offers **Install Claude Code for me**, which is the fastest way from nothing to a working setup. **Re-check** rescans after you install one yourself, and **I'll do this later** is the honest way past - it moves you on and carries the job forward instead of pretending it is done. Until you take one of those three the button beside them stays greyed out: DevThrottle cannot run a coding agent it does not have, and it would rather say so than let you finish a setup that cannot work. **Let your agents use a browser** is the second, and it recommends rather than asks. Its button reads **Set up my browser** and pressing it starts that job rather than skipping it. The way past is the quiet link underneath - **Set up browsers later - I want to get going** - and the screen is straight with you that doing it now is easier than wiring it up later. The last screen reads **You are ready** and shows a receipt of what was actually set up. That is the proof, and you do not need a terminal to confirm any of it. > **Warning:** **The installer window itself never asks who you are.** You signed in on our website to get the file, and the app signs you in at its gateway step - but in between, from double-clicking the file to the Director opening, the installer has no sign-in to show and never will. So if that window asks you to sign in, or for a licence key, or for a payment, it is not ours: close it and fetch the file again from your account. Inside the app, the gateway step above is the one legitimate sign-in, and **Not now** sits right beside it. > **Note:** Nothing here is final. Skipped the gateway? Settings connects it later. No coding agent yet? DevThrottle looks for agents every time it opens, so installing one later needs no reinstall. > **Note:** Installing on a Mac, or from a script? Those routes are on [the install page](https://devthrottle.com/docs/install) - the Mac command, the headless installer with no window at all, and the hash check that goes with it. The agent route is there too, with the prompt to paste. ## Next: step 2 DevThrottle is installed and, if you took the hosted card, connected. That is the boring part done, and everything from here is the actual product. **Step 2 is where the real work starts:** you point a coding agent at your own code, give it a first instruction, and watch it work. If the setup found a coding agent on this machine, the last screen offers **Start my first agent** and takes you straight there. If you took **I'll do this later** on the agents step, that same button reads **Install an agent** instead and sends you back to fetch one first - the wizard will not promise a session it cannot start. Step 2 is [Start your first session](https://devthrottle.com/docs/start/first-session). Curious what the gateway is doing on your behalf now that you are connected? [The Gateway overview](https://devthrottle.com/docs/gateway/overview) explains it, and it can wait. --- # Step 2: Start your first session > Pick a repository, pick a coding agent, name the session after the job, give it a first instruction, and watch it work. The second step of the getting-started path. Part of the DevThrottle documentation, section "Get started". Canonical HTML version: https://devthrottle.com/docs/start/first-session Last updated: 2026-08-07 DevThrottle is open on your machine and the list on the left is empty. This is the step that fills it: you pick a repository, pick a coding agent, name the job, and say what you want done. What you get at the end is a **session** - one running coding agent, in one repository of yours, working. The card that appears in the list is that session; there is nothing more to it than that. **About ten minutes**, and most of them belong to the agent rather than to you. You need DevThrottle installed and open, and one coding agent set up with its command line tool installed - that is all [the previous step](https://devthrottle.com/docs/start/install) left you with. If no agent is set up yet, the second step below shows you where to add one. 1. **Click New Session** It is the one coloured button in the toolbar along the top, with a plus sign on it. A window titled **New Session** opens, already on its New Session tab. The other tabs - Named Sessions, Resume Session, Handovers - are for later, once you have sessions worth coming back to. 2. **Pick the coding agent** The **Agent** row across the top has one button for each agent you have enabled, in the order your settings list them, with the first one already chosen. An agent you have set up but switched off does not appear here. If the one you want is showing, click it and this step is done. If the row instead says *No agents configured. Add one in Settings > Agents*, do exactly that. Which agents this window offers, what they are called, and what order they come in all come from [Settings -> Agents](https://devthrottle.com/docs/director/agents), where adding one is a short form that previews the command that entry will launch with - the entry's own command, before anything this window adds to it. 3. **Pick the repository** The search box already has the cursor in it, so just start typing the name. The list underneath comes in two layers: repositories you have opened before, most recently used first, and below them every repository DevThrottle has found under your [root folders](https://devthrottle.com/docs/director/repositories) but you have not opened yet. So even on a first visit the list may already be full - if you gave the setup wizard a folder that holds your code, everything it found there is waiting for you here. Only when there is nothing at all - nothing used, nothing found - does the window say **No repositories yet** and offer a **Browse for a repository...** button. Browse to the folder holding the code you want the agent working in. It joins the list, so next time it is one click. Choose with a little care. A session lives its whole life in this repository, running the agent you picked. The name you can change whenever you like; for a different repository or a different agent, you start another session. 4. **Glance at the approval checkbox** Under the list sits one checkbox - **Run without approval prompts**, ticked by default, with the exact command line option it can add shown in brackets after it. Ticked, it adds that option to the launch, but only if the agent's own settings entry has not already settled the permission question its own way. Unticked, it takes nothing away: the launch still runs with whatever that entry carries. An agent that has no such option at all gets the checkbox greyed out, with the label saying so. For a first session, leave it as it is and read the warning under these steps. The rule worth knowing is that the entry decides first. If the agent's entry in [Settings -> Agents](https://devthrottle.com/docs/director/agents) has already settled the permission question - either way, whether that is an unattended option or one that makes it ask - the entry keeps its own choice and this box changes nothing. The box only matters for an entry that settles nothing, and there it is the whole decision: ticked, the agent runs unattended; unticked, it follows its own defaults. 5. **Start it** Click **Start Session** in the bottom right. The button only comes alive once an agent and a repository are both chosen, so if it is grey, one of those is missing. If the agent's command line tool is not actually installed on this machine, nothing half-happens: DevThrottle tells you before it launches anything, names the program it looked for, and says how to fix it. 6. **Name it after the job** The moment the session starts, a small **Rename Session** box appears over it, already filled in with the repository's folder name and selected ready to be typed over. Type the job and press **Enter**. Name it after the job, not the place: *fix-login-timeout*, rather than the repository's name a second time. The day you have three sessions running in the same repository, cards named after the job are the difference between glancing and guessing. Escape keeps the folder name, and you can rename at any time from the **...** button on the card, whose first menu item is **Rename**. 7. **Say what you want, and how you will know it is done** The new card is now in the list on the left, already selected, and the terminal filling the centre shows the agent starting up. Under that terminal is a box to type in. Type your first instruction there and press **Ctrl+Enter** to send it. Make this first instruction small enough to finish in minutes and concrete enough that you can tell by looking whether it is done. A wording fix a user would notice, a log line you have been meaning to add, one test for the function you never trusted - not the refactor. And say the outcome rather than the keystrokes: what should be different when it is finished, where you believe the relevant code lives if you know, and how you will judge it. *"Users see the new wording instead of the old one"*. *"The new test covers the empty case"*. 8. **Watch the first minute, then stop watching** The terminal in the centre is the agent's own, live: you will see it read your files, decide, and start editing. Watch the first minute, because that is what tells you whether it understood the job. Then leave it alone. Hovering over a working agent is the habit this whole product exists to break. The card carries the state so you do not have to. When the agent stops and wants something from you, the card reads **Needs you**. An amber **chg** badge appears alongside it, counting the uncommitted changes in the working tree it is running in. Read it as that working tree's number rather than this agent's: every session running in the same working tree shows the same count, whoever made the changes. No badge means there is nothing to show, which is not the same as proof that nothing changed. > **Warning:** A Claude Code entry straight out of the box - its recommended Automatic preset, the checkbox left ticked - will change files and run commands in that repository without asking you first, and any other agent whose entry or checkbox supplies an unattended option behaves the same way. That setting is what makes agents worth running, but for this first session pick a repository you have committed recently, so anything you dislike is easy to see and easy to undo. Agents with no such option at all - Pi, OpenCode - launch with no permission option set and follow their own defaults. > **Tip:** A repository-and-agent pair you start every morning belongs on the New Session window's **Named Sessions** tab, where a saved pair launches with one click - no picking, no naming. ## You now have a session doing real work One agent, in your own code, on a job you chose. Everything else in DevThrottle is built on top of what you just did. The next step is the one thing nobody explains, and it is the difference between fighting this product and flying it: there are two places you can type on that screen, and that is on purpose. [The prompt bar is not the terminal](https://devthrottle.com/docs/start/prompt-bar) shows you what the prompt bar can do that the terminal cannot. The facts behind this page live on [Agents and models](https://devthrottle.com/docs/director/agents) and [Repositories and GitHub](https://devthrottle.com/docs/director/repositories). --- # Step 3: The prompt bar is not the terminal > Why there are two boxes you can type into, and what the lower one can do that a terminal line cannot - compose across several lines without the agent seeing a keystroke, expand into a full editor, dictate, send, and queue what comes next. Part of the DevThrottle documentation, section "Get started". Canonical HTML version: https://devthrottle.com/docs/start/prompt-bar Last updated: 2026-08-07 There are two boxes on this screen you can type into, and the first time you notice it, it looks like a mistake. The terminal fills the middle of the window and the agent has its own input line at the bottom of it. Then there is a second box below the whole terminal, with Send, Speak and Queue down its side. They are both real, and the difference between them is the most useful thing to understand about the Director. The agent's line is live: every key you press in the terminal is already in the agent's hands, one character at a time, and it is one line long. The box below holds what you write and gives it to nobody until you say so - so you can take five minutes over a paragraph, read it back, change your mind, and say it out loud instead of typing it. Ten minutes. You need DevThrottle open with one session running, from the previous step, and the Terminal tab showing. ![The prompt bar below the terminal: the message box with the Expand button in its corner, and Send, Speak and Queue stacked down its right-hand side, the Queue button red and reading Queue (3)](https://devthrottle.com/docs/screenshots/director/prompt-bar.png) 1. **Write more than one line, slowly** Click into the lower box - the one under the terminal - and start typing the next thing you want the agent to do. Not six words: the whole thing. The file you already looked at, the approach you do not want, the reason. Press Enter when you want a new line; Enter on its own is a line break here, not a send. Watch the terminal above while you do it. Nothing is happening. The agent is carrying on with whatever it was doing and has no idea you are typing, because this box is not connected to it yet. That is the whole point of the second box, and it is why you can write a careful instruction to an agent that is in the middle of something. 2. **Open it out into the larger editor** A paragraph is uncomfortable in a box that size. Click **Expand** in the top-right corner of the box and the same text opens in a large, resizable editor window with room to work - your text on the left, a preview beside it, and a Speak button in the corner if you would rather talk than type. Edit it properly there. **Apply** brings your edited text back into the box; **Cancel** leaves it as it was. Neither one sends anything - you come back to exactly where you were, with better words in the box. 3. **Say it instead of typing it** The instruction you would give a person out loud is longer and clearer than the one you are willing to type. Click the green **Speak** button, or press **Ctrl+H** from anywhere in the window while a session is selected, and talk. When you stop, **Insert** drops what you said into the box at your cursor - inside anything you had already typed, not on the end of it - so dictating is just another way of filling the same box. **Send** submits it straight away. Everything else about dictation, including what it costs and what to do when the words come out wrong, is its own tutorial: [Say it instead of typing it](https://devthrottle.com/docs/tutorials/dictation). 4. **Send it, and watch where it lands** Press **Ctrl+Enter**, or click **Send**. Now look at the terminal: your message appears in the agent's own input line, as if you had typed it there, and then submits. That is exactly what happened: DevThrottle put your message into the agent's own line and pressed Enter for you. It does not then walk away and hope. After pressing Enter it watches the terminal until the agent visibly starts the turn, and nudges it if the message is sitting there unsent - which is what stops a prompt being quietly swallowed by an agent that was busy repainting its screen. If a message genuinely cannot be delivered, the session says so rather than losing it silently. One consequence worth knowing, because it surprises people: the line breaks you typed were for you, not for the agent. On send, your message is joined into a single line, because the agent's input is a single line. Your paragraph arrives whole; it just arrives flat. 5. **Send something far too long for one line** Now do the thing a terminal will not let you do. Write - or dictate - a message several hundred words long and send it. It still arrives whole, and it is not truncated. Typing a very long message into an input line one character at a time is exactly where a terminal drops text, so DevThrottle does not do that. It hands the message over in one piece instead, by whichever means the agent in front of it understands - some accept a whole block pasted at once, others are given a file to read. Which one you get depends on the coding agent, and you do not choose it. What holds either way is the part that matters: your message arrives whole and is not cut short, however long it is. If your agent is one of the ones given a file, you will see a `.temp` folder appear in the repository, holding the text you sent in files named `input_` and a timestamp. Those stay where they are - nothing removes them for you - so they build up quietly over a long session. They are only copies of your own messages, and you can delete those `input_` files once no session still needs them. Leave the rest of the folder alone: DevThrottle does not own it, and other things keep working files there too. 6. **Queue what comes next instead of interrupting** You will think of the next job while the agent is still on this one. Interrupting a working agent to say it is a bad trade, and holding the thought means being there at the moment it finishes. Write it in the box as normal, then press **Ctrl+Shift+Enter** - or click **Queue**, under Send and Speak. The box empties and your instruction is queued on this session. The Queue button turns red and starts counting, reading **Queue (1)**, and the list appears in the panel on the right. **Nothing in the queue is sent until you send it.** DevThrottle does not wait for the agent to finish and feed it the next item - a stopped agent has either finished or stopped to ask you something, and those look the same from outside. The queue is a notepad with an order to it, attached to the right session. That is enough to start the habit. Sending items back out, reordering them, editing one you wrote an hour ago, and what survives a restart are all in [Line up the next instruction](https://devthrottle.com/docs/tutorials/queue-next). > **Note:** An unsent draft belongs to the session, not to the window. Click another session and come back, and the half-written message is still in the box where you left it - so a thought you started for one agent is not lost by looking at another. > **Tip:** Type `/` as the first character in the box and DevThrottle offers the slash commands this session's agent actually has, with descriptions, in this repository. Arrow keys to choose, Tab or Enter to insert. ## When you do want to type in the terminal There is one moment the agent's own line is the right box: when the agent's tool stops and asks for a keypress - an arrow-key menu, a yes-or-no confirmation, a pager. Click into the terminal and answer it directly. Arrows, Enter, function keys and the control strokes a command-line tool leans on - Ctrl+C, Ctrl+D, Ctrl+Z and Ctrl+L - pass straight through to the agent, exactly as if you had started it yourself. > **Warning:** Sooner or later you will select a line of output in the terminal and press Ctrl+C to copy it. With text selected, it copies. With nothing selected, it does what Ctrl+C has always done in a terminal - sends the interrupt character and stops the agent mid-task. **Ctrl+Shift+C** never interrupts: it copies the selection, and with nothing selected it does nothing at all. Make Ctrl+Shift+C the habit. For everything longer than a keypress, come back down to the box. It is the intended way to talk to an agent; the terminal above it is chiefly your window into what the agent is doing. Every control and shortcut in one place is on [The embedded terminal](https://devthrottle.com/docs/director/terminal). ## Next You can compose, expand, dictate, send and queue. The next step is what to do when the answer coming back is wrong - stopping an agent, redirecting it, and knowing when to take over rather than let it run: [Steer a session that is going wrong](https://devthrottle.com/docs/start/steering). The step after that is showing the agent a picture instead of describing one - dragging a screenshot onto this same box: [Work with pictures](https://devthrottle.com/docs/start/pictures). --- # Step 4: Steer a session that is going wrong > The action bar above the message box: Stop, Interrupt, Compact, Clear context and History - what each one does, which to reach for, and how to tell when to take the work over yourself. Part of the DevThrottle documentation, section "Get started". Canonical HTML version: https://devthrottle.com/docs/start/steering Last updated: 2026-09-06 The agent has been working for ten minutes and it is confidently doing the wrong thing - the wrong files, the wrong approach, or a careful answer to a question you never asked. Closing it down and starting again is the expensive reflex. Almost every one of these is recoverable, usually in one sentence. Look just above the message box you typed in during the previous step, [The prompt bar is not the terminal](https://devthrottle.com/docs/start/prompt-bar). There is a row of small buttons there - **Stop** in dark red, then **Interrupt**, **Compact**, **Clear context** and **History**. That is the action bar, and it is a ladder: the buttons on the left end a turn, the ones in the middle operate on the conversation itself, and the further right you reach the more you throw away. Take the lowest rung that works. Six minutes. You need DevThrottle open with one session working on something real, so there is output to read. 1. **Read it for thirty seconds before you touch anything** Click the session and read the terminal. Agents narrate as they work, so it usually says not just what it is doing but why - and a surprising route is not the same thing as a wrong destination. An agent opening files you never mentioned is often just working out where things are. Interrupting one that was fine costs you the minutes it needs to find its place again. What you are looking for is a wrong *goal*, not a wrong step: it is solving a problem you do not have, editing something you asked it to leave alone, or explaining at length instead of doing. Any of those, act. Otherwise leave it be and come back in a minute. 2. **Stop it, mildly first** **Stop** is the mild brake. It presses the agent's own soft cancel - the Esc you would press yourself if you were sitting in the bare command-line tool. The current turn ends there and then, and nothing else changes: the conversation is intact, the agent still remembers the task and everything it has read, and your files are exactly as they were a second ago. Watch the bar rather than the terminal while you click. The button greys out and reads back to you - `stopping...`, then `turn stopped` - and the note clears itself a few seconds later. That small line exists because this is the one button people click three times in a row: a second click while the first is still running is ignored, so an agent that takes a moment to let go is not a reason to keep pressing. If it genuinely will not let go, **Interrupt** is the hard version - the Ctrl+C a terminal has always understood. Reach for it when Stop bounced off, not before. Neither button asks you to confirm; both are meant to be pressed the instant you decide. 3. **Say what you actually wanted** Most steering ends here, and it is worth seeing why. After Stop, the conversation is whole. So do not re-explain the task from the beginning - just correct it, in the message box, and name both halves: what to abandon and what to do instead. "Stop rewriting the parser - the job was only to add the new date format, leave everything else alone" lands. "No, not like that" does not. Then read the first minute of what comes back, because the quality of your correction decides whether you are standing here again in ten minutes. If two corrections in a row have not landed, stop correcting - the next two steps are for when the conversation itself has become the problem. 4. **Compact when the room is the problem, not the reasoning** On agents that can report it - Claude Code, Codex and pi - the right-hand end of the bar carries a small gauge reading something like `ctx 42k / 200k (21%)`: how full the agent's working memory is, re-read every few seconds. It runs green, turns amber the moment it reaches seventy percent, and red above ninety. An agent whose context is nearly full starts forgetting the beginning of its own task, and that looks exactly like an agent going wrong. **Compact** is the answer to that, and it is not a brake at all. It asks first, then summarizes the conversation so far and frees the room back up. The session keeps what it has learned and stays exactly where it is - **nothing is sent to it afterwards**, so it will sit there until you say something. It can take a minute or two. When the gauge is red but the work is going fine, this is the whole intervention: compact, then carry on. 5. **Clear context when the misunderstanding is load-bearing** Sometimes the wrong turn is not a moment, it is a residue: the agent misread the task early and now everything it believes is built on that. Summarizing would just carry the misreading forward in fewer words. **Clear context** resets the conversation in place - the process keeps running, the same session on the same card, and what goes is the conversation you have had with it. It asks before it does it, and the question it asks is deliberately not the question Compact asks - one preserves the conversation and one destroys it, and two identical-sounding confirmations would teach one reflex for two opposite outcomes. Read which one you are looking at. Afterwards, write the task out again from scratch, as if to an agent that has not heard any of it - because it has not. It is still sitting in your repository, with whatever it reads for itself when it starts; what you took away is everything the two of you said. 6. **Read back to where it went off** On a Claude Code session there is one more button. **History** opens the agent's own rewind picker inside the terminal, listing the earlier points in the conversation - but only on a session that has stopped. The button presses Esc twice, and Esc is also what Stop sends, so on an agent that is still working the first press ends the turn instead of opening anything. Stop it first, or wait until it is finished, then press History. Walk back through the list to find the exchange where things turned. That is worth doing even when you have already fixed the problem, because the turn is so often a vague instruction of yours rather than a bad decision of the agent's. You can restore to the point just before it and take the fork again with better words. Esc closes the picker. > **Warning:** Clear context cannot be undone, and the button sits inches from the ones you press without thinking. An afternoon of accumulated understanding goes with one click - that is why it asks first, and why Compact sits beside it as the version that keeps what the session has learned. > **Note:** The bar shows only the verbs DevThrottle has verified for this session's agent, so it is not the same row for every agent - pi has Stop but no Interrupt, and History belongs to Claude Code alone. An absent button means the keystroke has not been established for that tool, which is not the same as the tool being unable to do it; for pi's missing Interrupt it is stronger than that, because Ctrl+C there clears the editor and twice over quits, so a hard interrupt would be a kill. The full list, agent by agent, is on [Starting and steering agents](https://devthrottle.com/docs/director/steering). > **Tip:** If you had queued instructions waiting, read them again before you send them. They were written for the path you just stopped, and one of them may now be an instruction to keep going down it - see [Line up the next instruction](https://devthrottle.com/docs/tutorials/queue-next). ## When to take it over instead The steps above assume the agent can still get there. Sometimes it cannot, and the skill worth having is noticing that early rather than after the fifth correction. The signals are consistent: you have corrected the same misunderstanding twice and it came back; the agent is confidently wrong about how your code works rather than about what you asked for; or the task turns out to need something only you know, and every prompt is you slowly typing out the answer anyway. Taking over does not mean giving up on the session. It means one of three things, in rising order of cost. Click into the terminal and answer the agent directly, which is right when it is stopped on a menu or a yes-or-no question. Stop it and make the edit yourself, then tell it what you changed and let it carry on from there - agents deal with that far better than people expect. Or, when the whole approach was wrong, Clear context and start the task again with the better description you now have, which is the one thing this hour bought you. Closing the session is the last resort, from the "..." menu on its card, and the part you actually care about is safe: **your repository and working directory are untouched**. Every change the agent already made to your code is still there, and closing undoes none of it. What ends is the agent's process and the card, along with the conversation in that terminal. DevThrottle does tidy up after itself, though. Closing a session clears out files it keeps for that session in its own storage - among them the preamble file it writes for the agent, the small note the agent's own hook leaves saying where that session's conversation has moved to, and the session's terminal recording folder, which goes even if you never turned recording on. None of them is in your project, and this is not a complete list. The one worth acting on is the recording: if you want a session's recorded screens, copy them out before you close it. If you think you may want the conversation back, look at **New Session** before you close rather than after: its **Resume Session** tab lists earlier sessions, and that is where picking one up again starts. Whether the session you are about to close will be waiting there is not something this page can promise you, so close it when you mean to stop. None of this is tied to the desktop. The Cockpit's session view in a browser has the same five buttons, chosen by the same per-agent gating, and asks the same two questions before compacting or clearing - its clear wording names the command where the desktop does not. The one thing it does not carry is the context gauge: [Working in a session](https://devthrottle.com/docs/cockpit/session-view). ## Next You can stop an agent, correct it, reset what it is holding, and tell when to take the keyboard yourself. The next step is the fastest way to make yourself understood in the first place - showing the agent a picture instead of describing one: [Work with pictures](https://devthrottle.com/docs/start/pictures). --- # Step 5: Work with pictures > Drag a screenshot onto the prompt bar, paste one into the browser, send a photo from your phone, and find the pictures your agent produced - four routes doing one job. Part of the DevThrottle documentation, section "Get started". Canonical HTML version: https://devthrottle.com/docs/start/pictures Last updated: 2026-09-06 You can spend five minutes describing what is wrong with a screen, or you can show the agent the screenshot. Showing it is faster, and it is exact - there is no gap between what you saw and what you managed to put into words. There is one idea underneath every way of doing it, and it is worth having before the steps. An agent reads a picture the same way it reads your code: as a file on the machine it is running on. So each route below is doing the same job - get the file onto that machine, and put its path in the prompt. Once you have seen that, your desk, your browser and your phone stop being three separate features and become one habit. Six minutes. You need DevThrottle open with one session running, and a picture worth showing it - a screenshot of the thing that looks wrong, a design, a photo of a whiteboard. 1. **Drag the picture onto the prompt bar** Find the image in your file manager and drag it onto the prompt bar - the same box under the terminal you have been typing into. Its full path is inserted where your cursor was, followed by a new line. Nothing is uploaded and no second copy is made: the agent is running on this machine, so it opens the picture where it already lies. Now write the sentence that goes with it - *the button in this screenshot is behind the header* - and send it the way you always do. The path is just words in your message, so it can sit anywhere in the sentence. One picture per drag. If you grab several files at once, the first one is the one that lands. 2. **Check it is the right picture before it goes** A path is not a picture, and screenshots taken a minute apart have names that look identical. Press **Expand**, in the top-right corner of the prompt bar, and the large editor opens with a preview beside your text in which a line that is a path to an image appears as the image itself. Look at it, then **Apply** and send. This is worth doing the first few times. Sending the wrong screenshot is not an error anybody catches - the agent answers confidently about a picture you did not mean to show it. 3. **Let the Screenshots panel save you the trip** The panel on the right of the Director opens on its **Screenshots** tab: the newest pictures in one folder on this machine, each a thumbnail with the time it was written and a row of buttons. Drag a thumbnail onto the prompt bar and you get its path, exactly as in the first step, without opening a file manager at all. ![The Director's right-hand panel on its Screenshots tab: a SCREENSHOTS header with Refresh and Clear All, and three recent images as thumbnails, each with the time it was written and View, Copy, Issue and Del](https://devthrottle.com/docs/screenshots/director/screenshots-panel.png) Which folder it watches is a setting, and it is the one part of this step that needs your attention: until that setting has been given a folder, the panel is not watching the one your own screenshots go to. It watches a folder the Director keeps inside its own data folder - the one pictures uploaded from a browser or a phone are filed into. So point it at yours. Open [Settings - Directories](https://devthrottle.com/docs/director/settings), press **Detect**, which fills in the folder this operating system saves screenshots to, or **Browse** to choose one yourself, then Save. The panel re-points immediately, with no restart. The setup wizard asks the same question, so on some machines it is already done, and that settings box shows you what it is set to today. Once it points at your own folder, take a screenshot however you normally take one and it is in the panel a moment later, ready to drag. If one you have just taken never turns up, that setting is the first thing to look at. 4. **Paste one - in the browser** Open the same session in the [Cockpit](https://devthrottle.com/docs/cockpit/session-view) and its message box takes a picture three ways: drag one onto the box, paste one into it, or press **Attach** and pick a file. All three do the same thing - the picture is uploaded from the device you are sitting at to the machine the session runs on, saved there, and its saved path dropped into the box, with *Image attached* confirming it. Add your sentence around the path and send. Paste is the one to make a habit of: take a screenshot to the clipboard, click into the box, Ctrl+V. Pasting ordinary text behaves exactly as it always did - only a picture on the clipboard is treated as an attachment. At your desk it is the other way round. Pasting a picture into the Director's prompt bar does not attach it - drag the file in, or drag it out of the Screenshots panel. Copying a screenshot to the clipboard and pressing Ctrl+V is the reflex most people arrive with, so it is worth knowing before you try it and wonder what you did wrong. 5. **Send a photo from your phone** You are standing in front of the screen that is wrong, or a whiteboard someone just filled. Open the session on your [phone](https://devthrottle.com/docs/mobile/sessions) and press **Attach**: the phone's own picker opens, offering the camera and your photo library, so you can take the photo there and then or pick the screenshot you took ten minutes ago. What happens next is the same shape as everywhere else, and one detail in it is worth being exact about. The photo does not go *into the session*. It is uploaded to the machine that session is running on, filed into that Director's screenshots folder, and the path where it landed is what arrives at your cursor. Add your sentence and send. So a photo you sent from a train is now a file on the machine at home, and the agent has been told where. Whether it also *appears* in the Screenshots panel there depends on what your phone photographs in - see the note below. 6. **Find the picture the agent made** Pictures come back the other way too - a chart it plotted, a page it rendered, a screenshot it took of your app. Do not go hunting for the file: **ask the agent to print the path**. Nothing obliges an agent to say where it wrote something, and they often do not, so make asking the first move rather than the thing you try after five minutes of looking. Once the path is on the screen, click it. In the Director, the small menu that opens offers **View File** and the image opens in the app. In the browser, clicking a path in **Terminal** or **Chat** opens it in place with a Download button. On your phone, tap it. > **Warning:** The buttons under each thumbnail act on the file, not on the list. **Del** deletes that image from disk straight away, with nothing to confirm and no way back, and **Clear All** - which does ask first - empties that folder of the picture types it recognises. Once you have pointed the panel at your own screenshots folder, that is your own pictures going, not a panel being tidied. > **Note:** The Screenshots panel is a filtered view of a folder rather than the folder itself, and an upload accepts picture types that nothing here displays. A phone that photographs in `.heic` sends a file that is accepted and saved on that machine, with its path handed over exactly as any other picture's would be - and that neither the panel at your desk nor the gallery in the browser will list. So if a picture is not where you expect it, open the folder itself before concluding it never arrived. Whether your agent can then open a `.heic` is its own affair, as it is for any image. Which surface recognises what is on [Working with pictures](https://devthrottle.com/docs/tutorials/pictures). > **Tip:** Handing over the path is where DevThrottle's job ends, and it ends in the same place for every coding agent the Director can run - none of them is handed a picture any other way. Whether the agent can then look at it is that agent's own ability. So if one ignores your image, describe what you want it to notice as well as showing it. ## The rest of it The Copy and Issue buttons under each thumbnail, exactly which file types each panel shows and which ones Clear All deletes, and the full set of routes in one place are all on [Working with pictures](https://devthrottle.com/docs/tutorials/pictures), which is the deeper version of this step. For the prompt bar itself - why the box you dropped the picture into is not the terminal above it - see [The prompt bar is not the terminal](https://devthrottle.com/docs/start/prompt-bar). ## Next You can show an agent something instead of describing it, from your desk, a browser or your pocket. The next step is the one that makes an agent trustworthy: seeing exactly what it changed in your code, reading the real difference, and deciding to keep it. That is [See what changed](https://devthrottle.com/docs/start/what-changed). --- # Step 6: See what changed > The amber changes badge, the Source Control tab, the line-by-line difference, and the decision to keep it - how to tell what an agent did to your code without taking its word for it. Part of the DevThrottle documentation, section "Get started". Canonical HTML version: https://devthrottle.com/docs/start/what-changed Last updated: 2026-09-06 An agent that has finished a job tells you what it did. It is a good account, written in confident prose, and it is the agent's own account of its own work. Your repository holds what actually happened. This step is the habit that sits between the two - reading the second before believing the first - and it is the one that turns an agent from something you supervise into something you trust. **About eight minutes.** You need DevThrottle open with a session whose agent has changed some files - the job you gave it when you [started your first session](https://devthrottle.com/docs/start/first-session) is exactly right. Come back with those changes unread. 1. **Start from the badge, not the terminal** Look at the session cards down the left. A small amber badge on a card - **4 chg** - counts the uncommitted changes sitting in that session's working tree. It is a count of change entries rather than of files, so a file that was staged and then edited again is counted in both halves of its life; treat it as a rough size, not an inventory. Read it as the working tree's number, not this session's. Every session running in the same checkout wears the same badge, whoever made the changes, so the count can include work this session never did. And no badge means *nothing to show*, which is not the same as nothing changed: it never renders *0 chg*, and it is equally absent when DevThrottle has not managed to produce a count at all. Start here anyway. Picking a card with a badge beats scrolling terminals looking for one. 2. **Read the agent's story, then stop reading it** Click the card and read the last thing the agent printed in the terminal: what it says it changed, and why. Hold that in your head - two or three files, a reason each. That is all you need from the terminal, and everything that follows happens somewhere else. The story is not evidence. It is the claim you are about to check. 3. **Open Source Control and read the list against the story** Select the **Source Control** tab, next to Terminal. Its Changes page names your branch along the top, and under it a **Changes** tree lists the files with edits, a letter on each for what happened to it - **M** modified, **A** added, **D** deleted, **U** for a new file git is not tracking yet. If nothing has been staged you will see one tree and no other, which is the ordinary case after a first job: the **Staged Changes** tree appears above only once something is actually staged, so do not go looking for it. The view refreshes itself while you watch. Now compare. An agent that said it changed the greeting in two files should be showing two files you expected. A file the summary never mentioned is not an alarm - it is simply the first one you open. Double-click it, or right-click and choose **View File**, and it opens: readable kinds in a tab inside the Director, anything else in whatever program your machine uses for it. A single click does nothing, and a file the agent deleted has nothing left to open - the next step is where you see what was in it. 4. **Drop to the line-by-line difference** The Source Control tab answers *what changed*. Before you keep anything, you want *exactly what, line by line* - and that lives somewhere else, because the session's tab has no Stage, no Commit and no Discard on it. Open **Repositories**, the pinned entry at the bottom of the left rail, and select this session's repository. You land on its **Changes** tab: the changed files down the left under **STAGED** and **CHANGES**, and, on the right, an empty pane reading *Select a file to see its changes*. **Click one.** Nothing is selected when you arrive, and until you pick a file the pane stays empty and the buttons that act on a file are not there at all. Click a changed file and its difference fills the pane - old and new line numbers down the side, added lines on green, removed lines on red - and **Stage**, **Unstage** and **Discard changes** appear in the header above it, for that file. The two steps below both start from a file selected here. Read it properly, but not evenly. Slow down in the files that matter and wherever the change is bigger or stranger than the job called for; skim the rest. If the difference is doing something the story never mentioned, you have found the thing this whole step exists for. 5. **Keep what you accept** The easy way to keep the work is the loop you are already in: go back to the session and tell the agent *"commit this"* in [the prompt bar](https://devthrottle.com/docs/start/prompt-bar). Or do it here by hand - click **Stage** on each file you accept, write a message in the box under the file list, and click **Commit staged**. Either way, watch the screen agree with you. A commit takes everything staged: the Staged Changes tree empties and hides, and the amber count on the card drops by what was committed, while anything you deliberately left unstaged stays sitting in the Changes tree. Only when nothing uncommitted is left does the tab read **No changes detected** and the badge leave the card. If your branch tracks a remote, the branch bar now shows a green caret and a number - **^1** - for the commits the remote has not got yet. Read, kept, not yet pushed. 6. **Send back what you do not accept** Most changes you dislike are not wrong, only wrong yet, and the cheapest fix is the one you already have: tell the agent what is wrong with it and let it go round again. The work in the tree is the conversation, not a verdict. For work you want to unhappen, select the file in that same Changes tab and click **Discard changes**. It asks first, in plain words - *This permanently deletes your changes in 1 file. There is no undo.* - and lists the file above two buttons, **Keep changes** and **Delete changes**. Read the list, not just the button. Discard offers itself only on a file git can restore, which is a tracked file with unstaged edits; a brand new file the agent created has no earlier version to go back to, so if it is wrong you delete the file yourself. > **Warning:** **Delete changes** is the one button on this page that destroys work, and there is no undo. What comes back is the file as git is currently holding it: if part of it was staged, that staged version returns and stays staged - so a discard is not a way to clear a file of everything the agent did. Otherwise it returns to the last commit. The confirmation is the only gate. > **Tip:** Review after every job, not after five. Each new job you send lands its changes in the same tree as the last one, and three jobs later the difference is one tangle nobody can honestly read. The amber count climbing instead of clearing is the early warning that you are storing up a review you will not enjoy. > **Note:** The count is produced once per working tree, on your machine, and the one answer is handed to every session on that tree. That is why two sessions sharing a checkout show the same badge - and why, on the day you have two sessions in one folder, the honest reading of **12 chg** is "twelve changes are in there" and nothing at all about which session made them. Giving each session its own copy of the code so the two never mix is [its own subject](https://devthrottle.com/docs/tutorials/repositories-and-worktrees), and a later step on this path. > **Note:** The count is produced once and handed round, so the session rail in your [browser](https://devthrottle.com/docs/cockpit/sessions) carries the same amber badge with the same number. Seeing **12 chg** from another room is how you know tomorrow starts with a review. ## Next You can now tell what an agent did to your code without taking its word for it, which is the thing that makes it safe to run more than one at a time. That is the next step: [Run several at once](https://devthrottle.com/docs/start/several-at-once) - starting a second and a third, reading the whole rail at a glance, and dealing with the one that has gone quiet. Every badge, tree and state on the review surfaces, as reference - the full set of status letters, the other sync badges, staging file by file, and how untracked files behave: [Source control and history](https://devthrottle.com/docs/director/source-control). --- # Step 7: Run several sessions at once > Start a second and a third session, then stop watching terminals: the needs-you count, the colour on each card, the waiting time that says which one to open, and the changes badge - plus queuing work for a busy session instead of interrupting it. Part of the DevThrottle documentation, section "Get started". Canonical HTML version: https://devthrottle.com/docs/start/several-at-once Last updated: 2026-09-06 Everything so far has been one agent and one terminal - which is a nicer way to run a coding agent, and not a reason to have built anything. This is the reason. Three sessions working at once is not three times the typing; it is a different job. You stop composing and start deciding: who needs an answer, who can wait, and what to line up next. The trick is that you never watch three terminals. You watch a list of coloured squares, and you open exactly one card at a time - the one the list sent you to. Ten minutes. You need DevThrottle open with the session you started earlier, and two more pieces of work you can hand out - ideally in different repositories, for the reason in the warning below. 1. **Start a second session while the first one is still working** Do not wait for anything to finish. With the first agent mid-task, click **New Session** in the toolbar at the top of the window and set up a second one exactly as you did the first - repository, coding agent, a name that says what the job is. That window is unchanged and taught in [Start your first session](https://devthrottle.com/docs/start/first-session). The new card appears at the bottom of the list on the left, and the window switches to it. Look at the card you just left: it is still blue, still working. Nothing paused. Give the new session its first instruction. 2. **Start a third, and give it something slow** Once more, and this time hand out something that will take a while - a test suite, a dependency upgrade, a refactor across a lot of files. You want one session that is genuinely busy for the next few minutes, because the next two things you learn are only useful when something is busy. Three cards, three colours, three jobs running in parallel on your machine. That is the fleet. Everything from here is how to read it. 3. **Look away from the terminal, deliberately** Click each card in turn. The terminal in the middle of the window shows one session at a time - the selected one - and swapping between them is the whole navigation. What matters is what does not happen. Looking away does not slow, pause or interrupt the session you looked away from: the window stops drawing that terminal, the session carries on regardless, and when you come back the terminal is rebuilt from what that session recorded while you were elsewhere. A half-written message in the prompt bar goes with it too, so a thought you started for one agent is still there when you return to it. This is the habit the rest of the step depends on. If you sit and read terminals as they scroll, three sessions will feel like three times the work. They are not meant to be watched. 4. **Read the count above the list** Above the session list is the word **SESSIONS**, and beside it, in amber, a count: **2 need you**. It is hidden when the number is zero, so you never read a zero - it is either there or it is not. That count is the answer to the only question you have to ask a hundred times a day. Not what are my sessions doing - is anything waiting on me. When it is not there, go and do something else. Two things it deliberately leaves out, so you do not read it as a health check: a session you have snoozed is not counted, and neither is one whose agent process has died. The second is why the last step of this list exists. 5. **Read the colour, not the words** Every card carries a coloured square on its left edge. Blue means the agent is working - leave it alone. Red means it has stopped and cannot go further without a human, and the label under the name says **Needs you**. With three sessions you can afford to read only that. Scan the squares down the left edge in one movement, and you have the state of everything you are running. The other colours - a session on a long background task, one whose agent has died, one being read for you - and every label they carry are on [Session cards and states](https://devthrottle.com/docs/director/sessions), which is worth ten minutes once. Hovering a square tells you why it is that colour. **Nothing a session does moves its card, and this is the single most important thing to know about reading the list.** A card holds the slot you put it in. When a session turns red it changes colour where it stands - it does not rise, and the card at the top is not the one that most needs you. The only thing that ever moves a card is you dragging it. So do not build the habit the list will not support. You cannot glance at the first card and be told what is urgent; you read the squares, all of them, every time. That is a second of work and it is the whole method - which is exactly why colour is on the outside edge where nothing competes with it. What position means is entirely up to you, and the step below is how to make it mean something. 6. **Let the waiting time choose which one you open** A red card shows how long it has been waiting - **waiting 9m**, ticking upward, in orange next to the state. Only red cards show it. The clock is stamped once, when the Gateway first sees the session waiting, and held at that moment for as long as it keeps waiting - so it measures the wait rather than the session, and it is cleared the moment the session stops waiting. Read it as a cost meter rather than a timestamp: it is how much of your day that session has already lost. A session that started three hours ago and has waited two minutes is fine. One that started ten minutes ago and has waited nine is the one to open. When several are red, work down from the longest wait, and the arithmetic takes care of itself. 7. **Notice the badge nobody finds** On the right of a card, an amber badge: **4 chg**. There is uncommitted work in that session's repository - real work sitting in a working tree, waiting to be reviewed or lost. It is the quietest useful thing in the window, and it is the one to look for. Read it as *there is something here* and no more than that, because the number is smaller than it looks. It counts entries in the repository's status, not files: a file you have staged and then edited again is two of them. So **4 chg** is four things to look at, which may be three files or four. What the number is counting, and what to do with it, is [See what changed](https://devthrottle.com/docs/start/what-changed). **The badge belongs to the working tree, not to the session.** The Director counts a repository once and puts that one answer on every card sharing it. So two sessions in the same repository show the same number, and it is the state of the tree - not a tally of what either of them did, and not a claim about who did it. Your own editor changes it too. Which means: never read **4 chg** on a card as work that agent did. On a repository one session has to itself it usually is. On a shared one it is not, and crediting a session with work it never touched is how you approve a change nobody reviewed. The warning below is the way out of that. One honest limit, because it decides how far you can lean on the badge. The count is refreshed on a timer for every session, not only the one you are looking at - but a refresh that cannot read the repository leaves the last number it did read sitting on the card. If the folder is renamed, or the repository is mid-rebase, the badge does not go blank or go to zero: it keeps saying what was true the last time anyone could tell. A badge is good evidence that there is work to look at, and it is not proof of what is in the tree right now. A card with no badge at all is a tree nothing has ever successfully read, which is not the same as a clean one. 8. **Queue work for the busy one instead of interrupting it** The slow session from earlier is still working, and you have thought of the next thing you want it to do. Interrupting a working agent to say so is a bad trade, and holding the thought in your head means being at the desk at the moment it finishes. Select it, write the next instruction in the prompt bar as normal, and press **Ctrl+Shift+Enter** - or click **Queue**. The box empties, the button turns red and starts counting, and a red badge appears on that session's card, so from the list alone you can see which sessions have work lined up. Click the badge to read it back. **Nothing in the queue is sent until somebody sends it.** No queued item ever leaves on its own - not when the agent finishes, not on a timer. From the Director the queue panel offers exactly five things to do with an item: move it up, move it down, edit it, remove it, and **Pop**, which takes it out of the queue and drops the text back into the prompt bar for you to send yourself. There is no send button on it at all. That is deliberate rather than unfinished: a stopped agent has either finished or stopped to ask you something, and from outside those look identical, so firing the next instruction at it would sometimes be answering a question with unrelated text. The queue is an ordered notepad attached to the right session. Popping items, reordering and editing them - and the browser Cockpit, which does have a per-item send you can press - are [Line up the next instruction](https://devthrottle.com/docs/tutorials/queue-next). 9. **Deal with the one that is red** If none of the three has gone red yet, make one on purpose - it is the cheapest way to learn the rescue before you need it. Send a session a prompt that ends in a question and tells the agent to wait for your answer: *"Which of these three names do you prefer? Ask me and wait."* It works briefly, stops, and asks. You have just made a stuck agent, safely, and everything above - the colour, the clock, the count - fires on it while you watch. Now the other half. Click the red card, select the **Terminal** tab if another tab is showing, and read the last thing the agent printed - when a session needs you, that is the question. Answer it in the prompt bar and press **Ctrl+Enter**. The square turns blue, the waiting time disappears, and the count above the list drops by one. Then go back to the squares. That loop - read the count, open the longest wait, answer, return - is the whole job of running a fleet, and it does not get more complicated at thirty sessions than it is at three. When a red card is one you genuinely do not want to deal with now, say so rather than ignoring it: **Snooze** from the card menu drops it out of the count for a while and brings it back on its own. Every state, colour and badge a card can wear, snoozing included, is [Session cards and states](https://devthrottle.com/docs/director/sessions); how a waiting session reaches you when you are not at the desk is [Put your fleet in your pocket](https://devthrottle.com/docs/tutorials/pair-phone). 10. **Put the list in the order you work in** Because nothing rearranges the list for you, arranging it is worth doing. Drag a card by its coloured square to move it, and it stays where you put it, including after a restart. Put the work you care most about at the top and the long-running background jobs at the bottom. The Director reads no meaning into the order at all, which is precisely what leaves it free to carry yours - and why the order still says what you meant a week later. 11. **Before you walk away, scan for the dark red one** One last pass, and it takes a second. A session whose agent process died shows a darker red and reads **Crashed**. It has no waiting time - there is nothing left to wait - and it is deliberately not in the count at the top. So it will never come and find you. Scan for it on purpose before you decide the Director is quiet. > **Warning:** Two sessions pointed at the same repository at the same time are writing into one set of files. If they touch different files nothing goes wrong; if they touch the same one, one of them can overwrite the other's work, and neither is told. Nothing in the Director watches for it - the shared changes badge above is the only hint you get, and it says one tree changed, never who changed it. Do not rely on being lucky about which files each one picks. Give each session its own repository for now. The proper fix - a separate checkout per session, from the same repository - is [Repositories and worktrees](https://devthrottle.com/docs/tutorials/repositories-and-worktrees), and it is what makes running several agents on one codebase safe. > **Note:** The session list can be collapsed to a narrow strip of the same coloured squares, each one clickable and named on hover. It gives the terminal the width back without giving up the one thing you actually watch. > **Warning:** Minimise the Director - do not close it. Your sessions live inside it, so closing the window ends every agent process it is running, all three at once, and it does that to every session whatever state it was in. > > There is a confirmation, and it is narrower than it looks: it appears when a session is working or waiting on you, which is what a busy Director usually contains. Do not read its absence as permission. A session that is snoozed, transcribing, or between states does not raise it, so the window can close quietly on sessions you meant to keep. Whatever the sessions already wrote to disk stays exactly where it is; the work in flight stops where it stands. > **Tip:** For one day, refuse to open a terminal that did not ask for you. Act only when the count says something needs you, and go back to the squares afterwards. It feels careless for about an hour, and then it feels like the tool doing its job. ## Next You are running a fleet rather than babysitting a terminal. The next step is where else that fleet turns up - the same sessions, the same colours, in a browser tab and in your pocket: [Where else your fleet lives](https://devthrottle.com/docs/start/fleet-elsewhere). --- # Step 8: Where else your fleet lives > A five-minute look at the two other windows onto the same sessions - the Cockpit in a browser, opened with one button from the Director, and your fleet on your phone. One fleet, not three copies of it. Part of the DevThrottle documentation, section "Get started". Canonical HTML version: https://devthrottle.com/docs/start/fleet-elsewhere Last updated: 2026-09-06 Everything so far has happened inside one window on one machine, and it is a fair conclusion from that the window *is* DevThrottle - that your agents are somewhere inside it, and that they are only reachable from the chair you are sitting in. The second half of that is not true. Your agents run on your machine, started and owned by the Director, and what *draws* them on a screen is a different question from what *runs* them. Two other things draw them, and the sessions you have been running are already in both. Five minutes of looking; you need the Director open with the sessions from [Run several at once](https://devthrottle.com/docs/start/several-at-once). ## Open the Cockpit Along the top of the Director, beside **Settings**, is a button reading **Cockpit**. Click it. That is the only thing this page asks you to do. The Director asks your gateway where its Cockpit is and opens the address it gets back. If you run your own gateway and its private network is down, there is no address to give: the Director says so and opens nothing, rather than sending you somewhere that would only work on this one machine. The first time, the browser lands on a sign-in rather than on your fleet, and that is the flow working - this browser is not your machine, and it is let in on its own account. One screen, then devthrottle.com asking **Connect this device?** and naming the browser it means, something along the lines of Edge on Windows. It stays signed in from then on, until that device is removed from the account. Then the **Fleet Map**, which is where the Cockpit opens: a node for your gateway, branching down through your machine to a card for each session you have been running. Same names, same colours. A rail down the left leads to Sessions, the Fleet Map, Assistant, History, Directors and more - what each one does is on [The Cockpit](https://devthrottle.com/docs/cockpit/overview). Behind **Sessions**, the roster is your fleet again, and opening one gives you its terminal - live, and typeable, every keystroke going through to the agent as it does on your desk. None of it is read-only. And none of it has to be on this machine. It is a browser tab: a hotel laptop, a borrowed desktop, a machine with nothing of yours installed on it. ## The same fleet, in your pocket The other window is your phone. There is nothing to download from an app store - your gateway has one address, and when a phone asks that address for a page, the gateway sees what is holding it and serves the phone app instead of the desktop pages. Same address, and the choice is made before either one loads. ![The DevThrottle phone roster with a red Needs you section listing two waiting sessions - Export notes to CSV in the notes-cli repository and Add task filtering in demo-app - each showing how long it has been waiting, when it started, its idle time and turn count](https://devthrottle.com/docs/screenshots/mobile/roster-needs-you.png) Sessions waiting on you are lifted to the top under **Needs you**, longest wait first, so the roster reads as a queue to work down rather than a wall to scan. A card shows what is known about its session - when it started, how long it has been open and idle, how many turns it has taken, and, on one that is actually waiting on you, how long it has been waiting. Facts the machine has not reported are left off rather than shown as zero. A session opens onto a screen it can be answered from, by thumb or by voice. And with notifications on, the app icon carries a dot while something needs you and loses it when nothing does - which is the part that changes the shape of a day, because it is the end of checking. ## One fleet, not three copies of it These are not three programs each holding their own version of your work. There is one fleet, and one verdict about it. That is more literal than it sounds. A session's colour is decided in exactly one place: the Gateway folds everything it knows about the session and stamps the answer onto it, and the Director, the Cockpit and the phone all render that stamp. None of the three works it out for itself. The desktop used to, and that was the bug rather than the design - it could only see its own machine, so a session snoozed from a phone still read as waiting on the desk while the other two had it right. The browser and the phone go further and refuse to guess at all: handed a session the Gateway has not stamped, they raise an error rather than invent a colour. That is why the three cannot quietly disagree about your own fleet. So closing the tab and pocketing the phone changes nothing. Nothing was running in either of them. > **Warning:** The Director is the exception, and it is the one thing to carry away from this page. It is not a window onto your fleet - it is what runs it. Closing its window ends its sessions with it: each agent is asked to stop, given about three seconds, and then ended. Which piece keeps running when, and what comes back after a restart, is on [keeping agents running](https://devthrottle.com/docs/gateway/lifecycle). ## Next You have seen where else your fleet lives. What turns the second half of this page from a screenshot into your own roster - and puts the dot that means something is waiting on your own phone - is the next step: [Pair your phone with your fleet](https://devthrottle.com/docs/tutorials/pair-phone). --- # Install DevThrottle in three steps > Install DevThrottle on Windows, Mac or Linux in three steps: create your account, put it on your machine, open it and start your first agent. Plain words, no keys to paste. Part of the DevThrottle documentation, section "Get started". Canonical HTML version: https://devthrottle.com/docs/start/easy-install Last updated: 2026-09-05 **Three steps: an account, the install, your first agent.** No keys to paste. 1. **Create your account, or sign in** Sign up with Google, GitHub, or an email address and a password - or sign in if you already have an account. [Create account](https://devthrottle.com/signup) **On day 15 nothing you installed stops.** Only the parts we host switch off, and nothing is charged. 2. **Put DevThrottle on your machine** **On Windows,** press **Download for Windows**: it is offered as soon as your account exists, and on [your account page](https://devthrottle.com/account) after that. If your browser holds the file back and says it is not commonly downloaded, open its full downloads list and press **Keep**. Run the file; if Windows shows a blue "Windows protected your PC" box, click **More info**, then **Run anyway**. Press **Next**, and on the last screen press **Open Director**. **On a Mac with Apple silicon,** open Terminal and paste this one line. **Terminal** ``` curl -fsSL https://raw.githubusercontent.com/thefrederiksen/devthrottle/main/scripts/install-mac.sh | bash ``` 3. **Open DevThrottle, sign in, start your first agent** When DevThrottle opens, a short setup starts: press **Set me up**. On the gateway screen keep the **Hosted gateway** card that is already selected and press **Sign in and connect**. Your browser opens, you sign in with the account from step 1, and the setup shows **Connected**: press **Continue**. On the agents screen press **Use these agents**, and if it says you need one, press **Install Claude Code for me** first. Then take the way on that each following screen offers: the button at the bottom right, except on the browser screen, where it is the quiet **Set up browsers later** link. The last screen reads **You are ready**: press **Start my first agent**, choose the folder that holds your code with **Browse for a repository**, and press **Start Session**. > **Note:** Your first session continues at [Start your first session](https://devthrottle.com/docs/start/first-session). Want every screen explained? [Install and connect](https://devthrottle.com/docs/start/install) walks the same install click by click, and [the install reference](https://devthrottle.com/docs/install) has the Mac and headless routes in full. > **Note:** If anything goes wrong, reply to the email that brought you here, or write to [soren@centerconsulting.com](mailto:soren@centerconsulting.com). A person reads it. --- # What DevThrottle is > DevThrottle is the open source control room for command-line coding agents - run, watch, and steer every agent from one place on your own machine. Part of the DevThrottle documentation, section "Get started". Canonical HTML version: https://devthrottle.com/docs/overview Last updated: 2026-09-06 DevThrottle is the open source control room for command-line coding agents. It is an MIT-licensed app for Windows, Mac and Linux that runs, watches, and steers the coding agents you already use - tools like Claude Code, Codex or Gemini that write and edit code for you - so you can start them and walk away. It tells you the moment one of them needs you. The app installs and runs on your own machine, and your agents run there too. ## What it does for you You stop waiting for agents: set several to work and come back when it suits you. You see every one of them from wherever you are, on any of your machines or in a browser. When one of them needs you, the question is waiting on your phone and you answer by voice. That is the short version - the docs entry lists [everything you can do](https://devthrottle.com/docs), each line linking to the page that shows how. ## The problem it solves A coding agent works on one task at a time in a terminal window. That is fine with one agent. The moment you run two or three, you are juggling windows: which one is still working, which one finished, and which one quietly asked a question twenty minutes ago and has been sitting idle ever since. The agents are fast; you become the bottleneck, and the waste is invisible. ## What DevThrottle does DevThrottle puts every agent in one place. Each agent session is a card, color-coded by state, and the card says which state in words: **Working** means leave it alone, and **Needs you** means it is waiting on a decision. Sessions that are snoozed, running in the background, or have exited say so on the card too. One glance tells you where to spend your attention. Click the card that needs you, answer, and move on. The same fleet is reachable from any browser and from your phone, so you can answer an agent while you are away from the desk - in a meeting, or on a walk - and you can answer by voice instead of typing. ## What DevThrottle is not DevThrottle is not another coding agent, and it does not replace the one you use. You bring your own agent and its subscription or API key; DevThrottle orchestrates it. It is vendor-neutral - Claude Code, Codex, Gemini, and more all run on the same Director - and running your own agents through it costs nothing. > **Note:** DevThrottle is a local app rather than a cloud service that runs your projects somewhere else: it installs on your machine and your agents execute there. When you use Pro, the hosted gateway, dictation, and spoken replies use DevThrottle services - the privacy page describes the data flow of each. ## Who it is for DevThrottle is built for developers on Windows, Mac or Linux who want the productivity of agentic coding without living inside a terminal. If you have tried a coding agent and liked it, but running more than one felt like chaos - or if you have not started yet and want a guided, point-and-click way in - this is the tool. On Windows you do not need to touch a command line to install it or to run your first agent; on a Mac or Linux the install is one pasted Terminal line. ## The pieces, in one paragraph The app you watch is the [Director](https://devthrottle.com/docs/director/overview). The background service that keeps agents reachable is the [Gateway](https://devthrottle.com/docs/gateway/overview). The same fleet in a browser is the [Cockpit](https://devthrottle.com/docs/cockpit/overview), and it also fits in your pocket on [mobile](https://devthrottle.com/docs/mobile/overview). [Voice](https://devthrottle.com/docs/voice/overview) lets you answer agents by talking. That is the whole map, and each name links to the section that covers it. ## What it costs The app is open source (MIT). On the **Free** plan you run your own agents with your own subscriptions or keys on every machine you own, and DevThrottle does not meter that. **Remote** adds the gateway we run, the Cockpit and the phone app, and **Pro** adds dictation, spoken replies and the wingman. Paid plans come with a 30-day money-back guarantee. The prices are on the [pricing page](https://devthrottle.com/pricing), and only there, so a change there never leaves a stale number here. ## Where to go next - [Take the path](https://devthrottle.com/docs/start) - the steps in order, one sitting each, from an empty machine to several agents at once. - [Install DevThrottle](https://devthrottle.com/docs/install) - download to running app in a few minutes, on Windows, Mac or Linux. - [Start your first session](https://devthrottle.com/docs/start/first-session) - from an empty Director to your first working agent. --- # Install DevThrottle and run your first agent > Create your free DevThrottle account, download it for Windows, and run your first coding agent in a few minutes. No command line required, and DevThrottle sets itself up when it opens. Part of the DevThrottle documentation, section "Get started". Canonical HTML version: https://devthrottle.com/docs/install Last updated: 2026-09-06 **Just installing on Windows, by hand?** Take [step 1 of the path](https://devthrottle.com/docs/start/install) instead - it is the same install, walked through in ten minutes, and it hands you straight on to your first agent. This page is the full reference: every install route, including the ones that page sends you here for. DevThrottle is a normal desktop app. Start with a free DevThrottle account - [sign up here](https://devthrottle.com/signup) - and the download follows it. On Windows: double-click and you are running. On a Mac: one pasted Terminal command installs it ([see below](https://devthrottle.com/docs/install#install-mac)). On Linux: the same, one pasted terminal command ([see below](https://devthrottle.com/docs/install#install-linux)). This guide takes you from nothing to your first coding agent in the Director, and DevThrottle's own setup handles the rest. Want an AI coding agent to do the whole install for you? See [Installing with an AI coding agent](https://devthrottle.com/docs/install#install-agent). ## Before you start DevThrottle is the control room. It runs and watches *coding agents* - tools like Claude Code or Codex that write and edit your code. You bring the agent and its subscription or key; DevThrottle puts it in one place and keeps it running. If you do not have a coding agent yet, that is fine - DevThrottle can install Claude Code for you when it first opens, and [our Get Started quiz](https://devthrottle.com/start) will tell you honestly which agent and plan fit you best. - **Operating system:** Windows 10 or 11, or macOS on Apple Silicon (workstation only - see [Installing on a Mac](https://devthrottle.com/docs/install#install-mac)). - **A coding agent:** Claude Code is the simplest start. DevThrottle can install it for you at its setup's agents step. - **A DevThrottle account:** email only. It is the first step here and the download follows it. (The installer itself asks you for nothing, and the app's own sign-in comes later, at its gateway step.) ## Step 1 - Create your account, then download Create a DevThrottle account - email only, and it starts on the Free plan - and the Windows installer is on your account waiting for you. No payment is required to run the app on your own machine with your own agent. [Create account](https://devthrottle.com/signup) **On day 15 nothing you installed stops.** Only the parts we host switch off, and nothing is charged. **If the download stops just short of finishing, your browser is holding it.** This is what Edge does; Chrome lets the file through and Windows asks at the next step instead. Windows decides whether to trust a file partly by how many people have downloaded it before, and every DevThrottle release is a brand-new file, so the first people to get it are asked to confirm it by hand. Click the download icon near the top right of your browser - it will be showing a small warning badge. The short panel that opens says the installer is not commonly downloaded, but it has *no* Keep button: click **Downloads** at the top of that panel to open your full downloads list. There the same file offers **Keep** and **Delete** as plain buttons - click **Keep**, and because the file has already downloaded in full it finishes at once. The publisher shown is Center Consulting Inc. On a work computer, your organisation's rules can remove the Keep option - if it is not there, ask whoever manages the machine. ## Step 2 - Install Run the installer you downloaded and follow the prompts - Welcome, Install, Complete. The first time you open a new installer, Windows may show a blue "Windows protected your PC" box with only a **Don't run** button. Click **More info**, check the publisher is Center Consulting Inc., then click **Run anyway**. It takes about a minute, needs no admin rights, and never asks you for an account: it places DevThrottle and the background launcher that keeps it available, and nothing else is required of you. Then choose **Open Director** on the last screen. ## Step 3 - First run Launch DevThrottle. The first time it opens, it walks you through an eight-step setup wizard - and *this* is where the app offers to sign you in, using the account you already made. The installer never asked, and it never will. After a welcome screen, the gateway is step 2 of 8, and it is a choice of three cards rather than a sign-in you have to take. **Hosted gateway** is marked RECOMMENDED and is already selected: you sign in through your browser and this machine is enrolled. **Self-hosted gateway** is for people running their own. **Not now** is local-only on this machine, needs no account at all, and connects any time afterwards from Settings. **Not now is a real answer** - the Director, its sessions and your coding agents all work without a gateway; what you give up is the remote half (your sessions on your phone, voice, the morning report) and the `cc-devthrottle` command line, which is the one `cc-` tool that talks through a gateway. The six steps after it are all about this particular machine, and on most of them the wizard does the work itself: the coding agents on it (it offers **Install Claude Code for me** if it finds none), its own command-line tools, the folders your projects live in, where your screenshots land, and a browser an agent can drive. The last screen reads **You are ready** and lists what was actually set up. Then you land on the Director - empty for now, waiting for its first agent. Step 1 of the path walks the same wizard screen by screen: [Install and connect](https://devthrottle.com/docs/start/install). ## Step 4 - Start your first agent Pick a project folder - a new empty one is perfect for a first try - and start an agent on it from the Director. Then talk to it like a person. A good first task: > Create a simple web page that shows the current time, then make it update every second. Watch the agent write the files in the Director. While it works, its card reads **Working**; when it needs a decision from you it turns red and reads **Needs you**. Snoozed, background and exited sessions each say so on the card in the same way. That one glance is the whole point - you never have to go hunting through terminal windows to find out where things stand. ## Installing on a Mac The Mac build is workstation-only: it runs your agents on the Mac, and it connects to a gateway hosted elsewhere. Install it by pasting one command into **Terminal**: **Terminal** ``` curl -fsSL https://raw.githubusercontent.com/thefrederiksen/devthrottle/main/scripts/install-mac.sh | bash ``` The command downloads the latest installer from our GitHub releases, verifies it against the release manifest, places **DevThrottle Setup** in your Applications folder, and opens it. From there the wizard works just like the Windows one. Why a command instead of a download button? The Mac installer is not yet notarized by Apple, so macOS blocks it when a *browser* downloads it ("Apple could not verify... is free of malware") - and modern macOS offers no way past that dialog. Terminal downloads are not quarantined, so the command above opens cleanly every time. ### On a Mac, without opening anything The command above installs the graphical wizard and opens it, which is what you want if you are sitting in front of the machine. If you are **not** - a coding agent doing the install for you, a setup script, or a machine you reached over ssh - use the headless installer instead. It is the same install engine with no window at all: **Terminal** ``` curl -fsSL -o devthrottle-setup-cli https://devthrottle.blob.core.windows.net/download/devthrottle-setup-cli-mac-arm64 chmod +x devthrottle-setup-cli ./devthrottle-setup-cli prereqs ./devthrottle-setup-cli install ``` `prereqs` checks a coding agent is present; `install` lays down the app and every `cc-*` tool per-user. Add `--json` to either for machine-readable output. Fetching the binary with `curl` is what keeps Gatekeeper out of the way - the same reason the wizard command uses it. Apple Silicon only. ## Installing on Linux The Linux build is for 64-bit Intel and AMD machines, and like the Mac build it is workstation-only: it runs your agents on the Linux machine and connects to a gateway hosted elsewhere. Install it by pasting one command into a terminal: **Terminal** ``` curl -fsSL https://raw.githubusercontent.com/thefrederiksen/devthrottle/main/scripts/install-linux.sh | bash ``` The command downloads the latest setup wizard, verifies it against the release manifest, makes it executable, and starts it. A browser download would arrive without the executable bit and unchecked, which is why Linux gets a command too. With nobody at the screen - a script, an ssh session, a coding agent - use the headless installer instead: **Terminal** ``` curl -fsSL -o devthrottle-setup-cli https://devthrottle.blob.core.windows.net/download/devthrottle-setup-cli-linux-x64 chmod +x devthrottle-setup-cli ./devthrottle-setup-cli install ``` ## Installing with an AI coding agent (headless) Already running a coding agent like Claude Code or Codex? You can have it install DevThrottle for you, start to finish, without touching the graphical installer. There is a headless command-line installer built for exactly this - it lays down the app and every `cc-*` tool per-user, with no wizard and no admin rights. It is the same install engine the graphical wizard uses, so an agent and a person end up with an identical setup. Point your agent at these steps. All three routes are filmed end to end on a clean Windows machine: this [agent route](https://youtu.be/CIAILnTdwDQ) (1:47), the [command-line route](https://youtu.be/8_wTp6_jyIM) (1:57), which is these same two commands, and the [desktop installer and setup wizard](https://youtu.be/I84tLg2Q7es) (6:19). 1. **Download** The headless installer and the release manifest, from the latest public release: **PowerShell** ``` curl.exe -L -o devthrottle-setup-cli-win-x64.exe https://devthrottle.blob.core.windows.net/download/devthrottle-setup-cli-win-x64.exe curl.exe -L -o release-manifest.json https://devthrottle.blob.core.windows.net/download/release-manifest.json ``` 2. **Verify** Check the installer against the manifest before running it - `Get-FileHash devthrottle-setup-cli-win-x64.exe -Algorithm SHA256` must match the manifest's entry for that asset. Stop on any mismatch; do not run it. 3. **Install** `prereqs` only reports whether a coding agent is already on the machine - it installs nothing, and on a clean machine it usually exits non-zero because there is none yet. That is informational: run `install` regardless. This is why the copy-paste block on the download page omits it - a script that stops on a non-zero exit would never install. `install` defaults to a per-user workstation install (no admin). Add `--json` to either for machine-readable output. **PowerShell** ``` .\devthrottle-setup-cli-win-x64.exe prereqs .\devthrottle-setup-cli-win-x64.exe install ``` 4. **Do not install a .NET runtime** The Director and the Launcher carry their own, so nothing needs to be on the machine first - an agent that adds one out of habit is doing work the install does not want. 5. **Sign in** Run `.\devthrottle-setup-cli-win-x64.exe signin` - the *only* step that needs you. It opens this website in your browser, where you sign in, or create an account, and it hands the session back automatically. Joining a gateway you already run on another machine? Use `.\devthrottle-setup-cli-win-x64.exe enroll` instead - it signs in and connects this machine to that gateway. Your agent runs everything else unattended. ## What is next That is the full loop: download, install, run, talk to your agent. From here, read [What DevThrottle is](https://devthrottle.com/docs/overview) to understand the Director, the Gateway, and how to reach your agents from a browser or your phone with [voice](https://devthrottle.com/transcription). Not sure which agent or plan is right for you? [Take the two-minute quiz](https://devthrottle.com/start) - it gives you an honest, personalized path, not a sales pitch. --- # DevThrottle tutorials > The tutorial library you reach for after the path - one job per tutorial, start to finish, grouped by what you are doing and by where you are working: your desk, your phone, or any browser. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials Last updated: 2026-09-06 Each tutorial is one job, start to finish, with the screens you will actually see. They teach you a path through something; the rest of these docs hold the details, and every tutorial links out to them. ## New here? Start with the path, not this page. There is a numbered path that takes you from an empty machine to running several coding agents at once. Read it in order - each step is one sitting and ends by naming the next. [THE PATH**Get started with DevThrottle**Install it, run your first agent, and build up from there - in order.](https://devthrottle.com/docs/start) ## Where are you working today? DevThrottle is built for three situations, and the tool you reach for changes with where you are. Most people end up using all three in the same week. At the office**The desktop app** Fastest of the three. Every agent's terminal is right there and you can type straight into it. 1 tutorial Out and about**Your phone** Answer an agent in thirty seconds while shopping - or work by voice for hours on a long walk. 3 tutorials Away, but at a keyboard**The Cockpit, in any browser** As close to being at your desk as it gets, with nothing to install - plus your week in review. 5 tutorials 19 tutorials ## The daily loop The handful of things you do every day once agents are running for you. **Talk instead of typing** Dictate a prompt anywhere you would have typed one - much faster once it is a habit, on the desktop, in the browser, and on your phone. Read it **Working with pictures** The detail behind the pictures step: which file types each surface recognises, what the Screenshots panel buttons do, which folder it watches, and where DevThrottle hands a picture over to the agent. Read it ## Running more than one Where DevThrottle stops being a nicer terminal and starts being a team. **Roles and who manages whom** Split one job across several sessions so they help each other instead of colliding - what each role does and when to use one. Read it **One agent starts another** Hand a piece of work to a fresh session from inside the one already running, and get its answer back. Read it **Repositories and worktrees** What stops two sessions fighting over the same copy of your code, and how to give each one its own place to work. Read it **Workflows** Write down how a job should be run once, publish it, and sessions launched after each Director's next poll see it in their briefing - starting from a built-in workflow rather than a blank file. Read it At the office ## At your desk: the desktop app The fastest of the three ways to work. Nothing sits between you and the agent - every session carries a real terminal you can type straight into. **Queue the next instruction** Queue what comes next while the agent is still busy, instead of sitting there waiting for a free moment to type it. Read it Out and about ## Out and about: your phone Two quite different jobs. One is rescuing an agent in half a minute while you are shopping. The other is a long walk where the phone is the only thing you are working on. **Pair your phone** Set your phone up once, and every session you are running is in your pocket from then on. Read it **Answer in 30 seconds** An agent has stopped and is waiting on you while you are out. Open your phone, read the question, answer it, and put the phone away - the short interaction you will do most often. Read it **A session by voice** Voice mode reads each turn out loud and you answer by talking - hours of real work from a footpath or a quiet bench, with no screen. Read it Away, but at a keyboard ## Any browser: the Cockpit Away from the office with a real keyboard in front of you - and the place you go at the end of a week to see what actually happened. **Your fleet in a browser** A hotel laptop, a client machine, a spare desktop - sign in and every agent you are running is there, with nothing to install on the machine you are borrowing. Read it **The fleet map** Every machine and every session you have running, drawn as one picture - so the only question that matters, is anything waiting on me, is answered before you read anything else. Read it **What got done this week** Your agents worked while you were elsewhere. The Cockpit history shows what ran, in which repository, how many turns it took and how often it needed you - which is the number worth acting on. Read it **Teach it your words** Dictation keeps mangling your product and repository names. Fix it once: teach your Gateway dictionary the right spellings and the wrong ones you have seen, and they are corrected everywhere you dictate. Read it **What you have used** How you actually drive your fleet - spoken vs typed, phone vs desktop, and which repositories and agents the work went into. Activity in turns and characters; no money anywhere, by design. Read it ## Going further Once the daily loop is second nature - the bigger, less obvious things. **Give an agent a browser** Create a separate browser profile, sign it in once by hand, and have an agent drive it through Browser Harness - so which accounts an agent acts as is a decision you made on purpose, never your everyday browser. Read it **Work that runs without you** Schedule an agent to run every night or every Monday morning through the Gateway - pick the machine, say when in plain English, and run it once by hand before you trust it. Read it **More than one machine** One machine runs out before you do. Add a second computer to the same fleet by enrolling it with the Gateway you already have, then give it its own clone of the code it will work on. Read it **Driving it from a script** The command line, for when you want DevThrottle to act while nobody is watching - read your fleet, message a session, and put it on a schedule. Read it --- # Talk to your agents instead of typing > Dictate a prompt anywhere you would have typed one - much faster once it is a habit, on the desktop, in the browser, and on your phone. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/dictation Last updated: 2026-08-07 The instruction you would actually give a person - all the context, the thing to avoid, the file you already looked at - is the one you never type. You type six words instead and the agent guesses the rest. Said out loud it takes fifteen seconds. This walks you through dictating one message, about five minutes. You need DevThrottle open with a Gateway connected, a session selected, a microphone, and an account on [Pro](https://devthrottle.com/pricing) - dictation is part of Pro. Nothing to install and no key to supply. If you are not on Pro, the dictation box tells you so instead of recording. It is the deeper half of [The prompt bar is not the terminal](https://devthrottle.com/docs/start/prompt-bar), which introduces Speak as one more way of filling the same box. > **Note:** One thing before you start, because it looks like a fault: while you are talking, no text appears. That is deliberate. Your words are kept as audio and turned into text in one piece when you ask for them, which is more accurate than transcribing as you go. 1. **Press Speak** The green **Speak** button sits beside the message box under the terminal, stacked between **Send** and **Queue**. **Ctrl+H** does the same thing from anywhere in the window, as long as the prompt bar is showing - so a session has to be selected, because otherwise there is nothing to dictate into. ![The prompt bar below the terminal: the message box with the Expand button in its corner, and Send, Speak and Queue stacked down its right-hand side, the Queue button red and reading Queue (3)](https://devthrottle.com/docs/screenshots/director/prompt-bar.png) A box opens and says GETTING READY until your microphone actually delivers audio, then turns red and plays a short sound. If the wrong microphone is selected, the dropdown at the top of the box changes it. 2. **Say the whole thing** Talk normally, in full sentences, the way you would explain it to someone at your desk. Bars move and a timer counts, and the text area stays empty - that is the part to trust. Pausing to think is fine; the timer is only telling you how long you have been talking. 3. **Press Pause to read back what you said** **Pause** stops the microphone and turns everything you have said so far into text, in the box, where you can edit it by hand. It is a checkpoint rather than an ending: **Resume** starts a fresh stretch of talking that gets added onto what is already there, edits included. Resume stays greyed out until the text has landed. This is what makes a long instruction workable. Say a paragraph, pause, check it got the file name right, carry on. 4. **Choose Insert or Send** **Insert** puts the text into the prompt box at your cursor and sends nothing - your typed words and your spoken words end up in one message, and you read it before the agent does. **Send** submits it into the session for you. Press Send while you are still talking and the box closes immediately: the transcribing happens afterwards, in the background, and the session shows orange with **Transcribing...** while it does. You do not sit and watch a progress bar. **Enter** is Send and **Escape** is Cancel. Cancel closes the box without putting anything in the prompt or sending anything to the agent - though it does not reach back and erase pieces you already checkpointed with Pause, which have been transcribed by then. The [Voice](https://devthrottle.com/docs/voice/overview) page says what is kept after a transcription and for how long. > **Tip:** Use **Insert** for your first week. Reading what came back is how you learn which of your words it fumbles - and those are exactly the words to put in your dictionary. Switch to Send once you have stopped being surprised. 5. **Do the same thing in a browser and on your phone** It is one dictation box, so there is nothing new to learn on the other two. In the [Cockpit](https://devthrottle.com/docs/cockpit/session-view), open a session and **Speak** is beside Send under the message box. On [your phone](https://devthrottle.com/docs/mobile/sessions), open a session's terminal and tap **Keys** to bring up the controls - Speak sits next to Send there too. The same four buttons, doing the same four things. The one difference is that neither browser surface has a microphone dropdown; they use whichever microphone the browser is already set to. > **Warning:** On the desktop, while a dictated message is still transcribing, that session's prompt box, Send, Speak and Queue go grey - one dictation at a time, so two cannot land on top of each other. It is not stuck; it clears itself when the words go in. The brakes are never taken away: **Stop** and **Interrupt** - whichever of the two your agent supports; not every coding agent has both - stay live throughout. ## What happens if it cannot get through The two answers are different, on purpose, and it is worth knowing which you are standing in. On your phone and in the browser, the recording is saved on the device before any network work happens, so a dropped signal does not lose it. While the page is open, delivery retries on its own; a closed tab or a phone that went to sleep does not deliver in the background, but nothing is lost either - the recording waits on the device, and delivery picks up the moment you are back in the app with a connection. That is what makes dictating on a walk sensible: say it, and it is safe; it goes while the app is up and there is signal, or the next time you open it. A status strip under the session tells you where it has got to, and it tells you the awkward cases too rather than going quiet. A send that cannot get through yet shows as waiting - saved, still trying - with an **Upload now** button to push it the moment you have bars. A failure that will not fix itself by retrying shows **Retry** - the recording is still safe on the device. The one case that can actually lose a recording is when it could not even be saved on the device in the first place; that shows as a red alert that stays until you dismiss it, so it cannot slip past you. The desktop app deliberately does not do that. A dictation sent there either goes into the session immediately or you are told immediately, with a message you cannot miss and no quiet queue retrying behind you. If the message had already been turned into text, the whole of it is put back in the prompt box so you can send it again yourself. If the failure came before the words could become text, what you had typed comes back, and the app tries to keep the last stretch of recording - when that save succeeded, the message says where to find it - but text you had already checkpointed with Pause on that dictation is not put back on this path. Dictating again is the way back. ## When it keeps getting the same word wrong It will get your product name wrong, or your repository, or the library nobody outside your team has heard of. Fixing that by hand every time is the thing that makes people give up on dictation, and it takes about five minutes to fix permanently: [Teach it the words you use](https://devthrottle.com/docs/tutorials/dictionary). ## Next For what dictation is, which surfaces it runs on, what it costs, and what leaves your machine when you use it, see [Voice](https://devthrottle.com/docs/voice/overview). If you want your agents to talk back as well as listen, that is [voice mode on the phone](https://devthrottle.com/docs/mobile/voice). --- # Working with pictures > The detail behind the pictures step: which file types each surface recognises, what the Screenshots panel buttons do, which folder it watches, and where DevThrottle hands a picture over to the agent. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/pictures Last updated: 2026-08-07 This is the detail behind [Work with pictures](https://devthrottle.com/docs/start/pictures), the step on the getting-started path. That step teaches the routes - dragging a picture onto the prompt bar, pasting one in the browser, sending a photo from your phone, and finding the picture an agent made. This page is what it sends you here for, and none of it is worth reading until you have used one of them. ## Which file types work where Three sets, and they nest - each one is the set above it plus one more type. That shape is the whole answer, and it is easier to remember than the lists. | What recognises it | Types | | --- | --- | | The Screenshots panel at your desk | png, jpg, jpeg, bmp, gif | | The Expand preview, and the gallery in the browser | those five, plus webp | | What an upload will accept | those six, plus heic | The first gap is `.webp`: the Expand preview will show you one inline and the Screenshots panel beside it will not list that same file at all. > **Note:** The second gap is the one to plan around, because nothing in DevThrottle shows you a `.heic`. An upload keeps the extension it was sent, so a phone that photographs in `.heic` files a `.heic` onto the machine your session is running on - accepted, saved, path handed to the agent, and listed by **neither** the panel at your desk nor the gallery in the browser. The file is not lost - it is on that machine and its path was handed over exactly as any other picture's would be, and DevThrottle neither converts it nor knows anything about the format. It is simply not in any of DevThrottle's lists, and whether your agent can open a `.heic` is its own affair, the same as for any image. Open the folder itself before concluding it never arrived - and if the agent cannot use it, set the phone to photograph in JPEG, which is a setting on the phone rather than anything here. ## The Screenshots panel, button by button The panel lists the newest fifty matching files in the folder it watches, newest first, each with the time it was written. **Refresh** re-reads the folder and **Clear All** empties it; under each thumbnail: - **View** opens the picture in the app. - **Copy** puts the *image itself* on the clipboard on Windows - not its path. That is what you want when the picture is going into an issue or a document rather than to an agent. - **Issue** does the same copy and then opens GitHub's new-issue form for the selected session's repository, so the picture only has to be pasted in. - **Del** deletes that file from disk. Dragging a thumbnail hands over the file's path as text, which is why it lands in the prompt bar exactly as dragging the file from a file manager does. > **Warning:** **Del** and **Clear All** act on the files, not on the list. Del deletes immediately, with nothing to confirm and no way back. Clear All does ask first, and then deletes every `.png`, `.jpg`, `.jpeg`, `.bmp` and `.gif` in that folder - so anything of another type, a `.webp` or a `.heic` among them, survives a Clear All that looks like it emptied the folder. Once the panel points at your own screenshots folder, that is your own pictures going. ## Which folder the panel watches A setting, under [Settings - Directories](https://devthrottle.com/docs/director/settings), and until it has been given one there is no operating-system default underneath it. With the setting empty, the folder resolves to one the Director keeps inside its own data folder - which is also where every picture uploaded from a browser or a phone is filed, and is why uploads appear in the panel while your own screenshots do not. **Detect** fills in the folder this operating system saves screenshots to, **Browse** lets you choose one, and Save re-points the panel immediately with no restart. The setup wizard writes the same setting, so on some machines it is already pointed somewhere - the box on that settings page is the only place that tells you where. ## Several at once Only one surface takes more than one picture at a time, and none of them says so. **The browser is the one that does**: its Attach opens a multiple-selection picker, and every image you choose is uploaded and its path inserted alongside the others. At your desk a drag takes the **first file only** - drag five and four are silently ignored. On a phone, Attach picks **one** at a time, so five pictures is five rounds of Attach. If you have a set to send, send it from the browser. ## Where DevThrottle's job ends Every route ends at the same boundary, and it is the same boundary for all nine kinds of coding agent the Director can run - Claude Code, pi, Codex, Gemini, OpenCode, a raw command line, Cursor, Grok and Copilot. None of them is handed a picture by any other means: the path goes into the prompt, the prompt reaches the agent through one shared path in DevThrottle, and no agent gets image handling of its own on the way. > **Tip:** That is why an agent ignoring your picture is not a DevThrottle failure to diagnose. Whether it can open the file is that agent's own ability. Say what you want it to notice as well as showing it, and if it produced a picture and did not say where, ask it to print the path - nothing obliges it to. ## Where the rest of it lives The prompt bar and its controls are on [Starting and steering agents](https://devthrottle.com/docs/director/steering); the browser's message box on [the Cockpit session view](https://devthrottle.com/docs/cockpit/session-view); the phone composer on [sessions on your phone](https://devthrottle.com/docs/mobile/sessions); and the screenshots folder setting on [Director settings](https://devthrottle.com/docs/director/settings). For why the box you drop a picture onto is not the terminal above it, see [The prompt bar is not the terminal](https://devthrottle.com/docs/start/prompt-bar). --- # Roles: who plans, who manages, who builds > Split one job across several sessions so they help each other instead of colliding - what each role does and when to use one. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/roles Last updated: 2026-08-07 One session is easy to follow. The trouble starts around the third: you gave one of them the plan, another is grinding through a refactor, a third is running errands for the second - and every card on the rail looks the same. Roles fix the reading problem. The method has five - **Standalone**, **Architect**, **Manager**, **Worker**, and **Reviewer** - and each session carries one word that says its place in the work. DevThrottle records the first four today, and works most of them out for you. About ten minutes. You need a Gateway, the DevThrottle command line, and at least one running session - [start one](https://devthrottle.com/docs/start/first-session) if nothing is running. 1. **Look at what you have - and notice the silence** Open the Director and look at the session rail, or open the [fleet map](https://devthrottle.com/docs/tutorials/fleet-map) in the Cockpit. Unless a session is already supervising another - or already wears a role someone declared - you will see no role anywhere: no badge on the rail, no role word on the cards. That silence is the design. Every undeclared session starts as Standalone - working alone, facing you - and Standalone shows no badge, so a fleet of solo sessions stays quiet. A role only appears when it says something: someone plans, someone supervises, someone builds - or someone declared it. 2. **Declare the planner** One role never appears on its own: **Architect**, the session that settles the design and directs the rest. DevThrottle can work out who supervises whom by watching the wiring, but nothing in the wiring says which session is the planner - so the Architect is the one role you must declare yourself. Start a session as one: **An Architect at birth** ``` cc-devthrottle session spawn D:/work/my-repo --role architect --name "Checkout flow - Architect" --prompt "Plan the checkout rework. Settle the design and the phases before anything is built." ``` Or promote a session that is already running - it defaults to the session you are in, or name a target: **An Architect after birth** ``` cc-devthrottle session role architect ``` On the Director rail the session now carries a small **A** badge (hover it for the full word); on the fleet map its card says Architect. Notice it is there already, before this session supervises anyone: a declared role wins from birth, not from the wiring. It is also sticky - it stays until you clear it with `cc-devthrottle session role none`. 3. **Hand work down and watch the roles appear** Now the part you never set by hand. Ask any running session to hand a piece of work to a fresh session - prompt it with something like "spawn a helper session in this repository to write the migration script, and collect its answer". From inside a session, the spawn command it runs defaults to starting the new session *supervised by the one that spawned it*. The moment that happens, the Gateway resolves both ends. The new session shows as a **Worker** (a W on the rail). Your planner keeps its A: a declared Architect that hands work down stays an Architect, so do not look for an M here. The **Manager** badge is what an *undeclared* spawner earns - any session with no declared role of its own shows as a Manager while it has a live supervised session under it, whatever role that session itself wears - and when the last one ends, the badge goes with it. Derived roles track the live work, not history. On the fleet map, a Worker's card nests under its Supervisor when both sit in the same lane of the grouping you have chosen - group by machine, and a Worker tucks under its Supervisor on that machine's lane. A Worker whose Supervisor sits in a different lane renders as a root of its own lane instead; the nesting never reaches across lanes. > **Note:** Two different edges connect sessions, and only one drives any of this. The **Supervisor** is the live relationship that roles and colours are computed from. The **Parent** - who started the session - is plain history and changes nothing on screen. They usually coincide, but a session can start a peer for you with `--standalone`: that peer has a Parent and no Supervisor, faces you, and wears no Worker badge even though an agent started it. 4. **Read the colours through the roles** Roles change what the colours mean, and this is the point of the whole arrangement. A Standalone, Manager, or Architect that needs input turns red - those sessions face you, so their red is your business. A Worker's red is its Supervisor's business - and that Supervisor need not be a Manager; a Worker can answer directly to an Architect. A waiting Worker under a live Supervisor never turns red at all. It recedes to a quiet slate - the Cockpit's fleet-map legend calls that colour **Sub-agent** - and its Supervisor deals with it while you get on with your day. There is an escape hatch, with one deliberate exception. A Worker whose role was worked out from the wiring stops being a Worker if its supervising session dies, so anything it needs from a human turns red again - nothing waits silently on a Supervisor that will never answer. A Worker you *declared* is different: the declaration is sticky, so it keeps the role and the quiet slate even after its Supervisor exits, until you clear the declaration. 5. **Put names on the pattern** What you just built by hand - a planner, a supervisor, a builder - is the cast of the Team way of working, shipped in the workflow catalog as **mission**: an Architect settles the design, a Manager drives the phases, and Workers build. The catalog's other two built-in workflows are smaller casts of the same idea - standalone is one session working alone, and standalone-with-review adds a second, separate session that checks the work before it is called done. Every session is briefed with the catalog's one-line summary of each workflow; a session that participates in a workflow run is told to fetch that workflow's pinned conduct and follow it. The [workflows tutorial](https://devthrottle.com/docs/tutorials/workflows) shows how those ways of working are written down and published to your fleet. > **Note:** The Reviewer in standalone-with-review is the method's fifth role - a different session from the one that wrote the work, checking it before it lands. It is agreed but not yet recordable: the role flag accepts four values today and no badge shows for a Reviewer, so the workflow staffs the role rather than the rail displaying it. > **Tip:** Declaring roles is not only for Architects. All four recordable roles can be declared - at birth with `--role` or later with `cc-devthrottle session role` - and a declared role wins first over anything DevThrottle would have derived. A mistyped role is rejected outright, never silently dropped. The full facts - the resolution order, every badge surface, and the exact colour behaviour - live on [session roles and missions](https://devthrottle.com/docs/director/roles). For giving each session its own copy of the code so a team of them can build in parallel, read [repositories and worktrees](https://devthrottle.com/docs/tutorials/repositories-and-worktrees). --- # One agent starting another > Hand a piece of work to a fresh session from inside the one already running, and get its answer back. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/agent-starts-agent Last updated: 2026-09-06 Your session is deep in a real job and a side task falls out of it - a migration script, a test data generator, a question about another part of the codebase. You could open a new session yourself and paste the context across. The better habit: tell the agent to hand the work off itself, and collect the answer when it is ready. One word before the first step, because the title uses a shorthand. An agent is the tool - Claude Code, Codex. What an agent starts is a **session**: a new running instance, with its own terminal, its own context, and its own place on the rail. Your agent starts one by running a single command. About ten minutes. You need a Gateway, the DevThrottle command line, and one running session - [start one](https://devthrottle.com/docs/start/first-session) if nothing is running. 1. **Tell your session to hand the work off** Prompt the session you already have with something like: "Spawn a helper session in this repository to map every place the orders table is read or written, and collect its answer when it is done." Underneath, the agent runs: **What your agent runs** ``` cc-devthrottle session spawn D:/work/my-repo --name "Map the orders table usage" --prompt "Find every place the orders table is read or written in this repository. When you are finished, print a list of the files and what each one does with the table, then wait." ``` One judgment call sits in that command: this errand only *reads* the repository, so the helper can share the folder your session is already working in. The moment a helper must *edit* files, give it its own copy of the code first - two sessions writing in one folder edit over each other - by cutting a worktree and spawning the session there: [repositories and worktrees](https://devthrottle.com/docs/tutorials/repositories-and-worktrees) shows how. There is nothing to configure first - provided your Director is attached to a Gateway. A session launched on a Gateway-attached Director is given its own credential pair, stamped into its environment at launch - `CC_GATEWAY_URL` says which Gateway to call and `CC_GATEWAY_SESSION_KEY` is that session's own key for it, stamped as a pair or not at all - which is why the fleet commands simply work from inside your sessions. Without that pair - a Director with no Gateway, or a shell outside any session - the commands stop with a plain sentence saying they only work inside a DevThrottle session on a machine attached to a Gateway; nothing half-works. 2. **Read the rail: a Worker appears, and it will never page you** The new session shows up like any other - on the Director rail, on the [fleet map](https://devthrottle.com/docs/tutorials/fleet-map), and in `cc-devthrottle session list`. But it arrives with a difference: a session spawned from inside another session defaults to a **Worker** supervised by its spawner. The spawner - if you declared no role for it - wears a Manager badge while its Worker lives. The [roles tutorial](https://devthrottle.com/docs/tutorials/roles) walks the whole cast; here only one consequence matters. **A supervised Worker never turns red.** When it stops and needs input, it does not join your "needs you" pile - it recedes to a quiet slate colour (the fleet map's legend calls it Sub-agent), and its supervisor deals with it. For you that means red stays honest: a red session is always one that faces *you*, and a handoff between agents never pages the human in the middle. If the supervising session dies, the Worker stops being a Worker and anything it needs turns red again - nothing waits silently on a supervisor that will never answer. That quiet is only safe because the Worker has a channel of its own, and v2.0.6 shipped it. When a Worker hits something it cannot decide inside its mandate, it puts its hand up to the session driving it: **What a blocked Worker runs** ``` cc-devthrottle session raise "Two schemas fit the requirement and only one is reversible - which?" ``` The command's own help draws the line: raise it only while you are *still working* and have hit an ambiguous requirement, an irreversible step, a real design fork, or an authorisation you do not hold - "not for progress, and not for 'I finished' - stopping already says that". The hand lowers itself when the turn ends, and `--clear` takes it back down once the decision is answered. The other half is the read. A supervisor is not meant to be messaged "notice me"; it looks: **What the spawner runs** ``` cc-devthrottle session workers ``` That lists the sessions you are driving, what state each is in, and which of them have their hand up with what they are blocked on - one line instead of opening each in turn. Both commands default to the current session and take a `--target` if you mean another one. > **Note:** The subordinate Worker is the default, not the only shape. A session can start a human-facing *peer* instead with `--standalone`: that session has no supervisor, faces you, and turns red at you like any session you started yourself. 3. **Get the answer back** When the spawner wants the result, it asks - and waits: **Ask and wait for the answer** ``` cc-devthrottle message ask "Map the orders table usage" "Are you done? Give me the list." ``` The question lands in the Worker's terminal like any prompt. The asking session holds the line until the Worker finishes its turn - up to two minutes by default, longer with `--timeout-ms` - and then prints what the Worker wrote as the answer. For a one-way nudge that does not wait, there is `cc-devthrottle message send`. Either way the message arrives stamped by the Gateway with the sender's own name, machine, and id - the receiving agent always knows who is talking, and the sender cannot forge the stamp. > **Warning:** A message is an interruption: it lands in the receiving agent's stream even mid-task. That is why messaging is fenced - `send all` reaches only your own team, and a genuine fleet-wide broadcast needs a human-issued grant. The full safety rails are on [sessions talking to sessions](https://devthrottle.com/docs/gateway/fleet-messaging). 4. **Close the loop: the spawner cleans up** A finished helper should not linger on your rail - and closing it is the spawner's job, not the helper's. Once the answer is collected and read, the session that opened the helper flags it: **Collect first, then close** ``` cc-devthrottle session done "Map the orders table usage" ``` It is not an instant kill. The flag starts a grace window of about thirty seconds - long enough for the flagged session's final output to flush - and the owning Director's reaper sweeps about every thirty seconds after that, removing a flagged session once it is no longer working. The helper is gone within about a minute. Resist the tempting shortcut of telling the helper to flag *itself* as its last act. A helper that runs `session done` the moment it finishes can be reaped before anyone comes back for the answer - the reaper does not know an ask is still coming. Collect, review, then close: make "after you have read the answer, run session done on the helper" part of the handoff habit, so a day of handoffs does not leave a rail full of exited helpers to sweep up by hand. > **Tip:** The new session does not have to be on your machine. `session spawn --machine ` starts it on another computer in your fleet, through the Gateway - see [your agents on more than one machine](https://devthrottle.com/docs/tutorials/many-machines). ## Next The full facts behind this page - the three verbs, the sender stamp, team scope, and the broadcast rails - live on [sessions talking to sessions](https://devthrottle.com/docs/gateway/fleet-messaging). For giving a writing helper its own copy of the code, read [repositories and worktrees](https://devthrottle.com/docs/tutorials/repositories-and-worktrees). And when one helper becomes a team with a plan, put names on the pattern with [workflows](https://devthrottle.com/docs/tutorials/workflows). --- # Repositories and worktrees > What stops two sessions fighting over the same copy of your code, and how to give each one its own place to work. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/repositories-and-worktrees Last updated: 2026-08-07 Put two sessions in the same folder and they will not fight loudly. They will fight quietly: one edits a file while the other is halfway through rewriting it, one stages the other's half-finished work, and the change you finally read is a mixture of two intentions that neither of them meant. Nothing in DevThrottle stops you doing this. A session's working folder is just a path, and two sessions may hold the same one. The fix is not a rule about taking turns. It is giving each session a folder of its own - which git already knows how to do, and the Director already knows how to keep track of. About ten minutes. You need one repository you can push from, and git on your machine - everything below is the Director driving git rather than replacing it. 1. **Understand what a worktree actually is** A **worktree** is a second working folder for a repository you already have, checked out on its own branch. It is not a second clone: there is one repository, one history, one set of remotes, and the new folder simply holds a different branch of it. Creating one costs a checkout, not a download. That is exactly the shape the problem wants. Two sessions, two folders, two branches, one repository - so they cannot touch each other's files, and their work still merges the ordinary way. 2. **Make one, beside the repository** **From inside the repository** ``` git worktree add ../myapp-login -b login-form ``` That creates the folder `myapp-login` next to your repository, on a new branch called `login-form`. Name both after the job rather than the session that will work there - the folder outlives it. > **Warning:** Put it *beside* the repository, not inside it. git will happily create a worktree in a subfolder, and it does not ignore it for you - so the repository around it starts reporting untracked content, which makes it look permanently dirty. A repository that always looks dirty is one whose change badge you stop believing. 3. **Start a session in it** Hit **New Session** in the toolbar and browse to the worktree folder - it is an ordinary folder, so it goes in the path box like any other. From that moment the session's world is that folder and that branch. The quiet fights from the top of this page are over: two sessions can no longer edit or stage over each other. What the worktrees still share is the repository itself - one history, one set of branches, one set of remotes and one configuration - so a session can still push, or move a branch the other cares about. Worktrees isolate the working files, not the repository. Everything else the dialog asks is covered by [starting your first session](https://devthrottle.com/docs/start/first-session) - the only thing different today is the folder you point it at. > **Note:** Do not go looking for the worktree in the repository list - it is not there, and that is deliberate rather than a scan that missed it. Worktrees are shown under the repository they belong to, which is the next step. 4. **See every worktree you have** Two ways in, showing the same thing. From a session, open the **Source Control** tab and pick **Worktrees** in its left rail. Or open **Repositories** - pinned at the bottom of the main left rail - click the repository, and choose its **Worktrees** tab. > **Note:** One precondition: the Director only tracks repositories under a registered root folder. If the page answers "This folder is not under a registered root directory. Add its root under Repositories.", do exactly that - open **Repositories**, pick **Root folders**, hit **+ Add root folder**, and point it at the folder that holds your repository. Then come back. Every worktree of that repository is listed, sorted into groups, and each row carries a one-line reason from the Director saying where it put that worktree. Read that line rather than the group heading above it: the line is the Director's own account of what it found in that particular folder. The worktree you just started a session in appears here like any other, with its branch and its own line. That is what this view is for - one place that answers "what have I got open, and where is it?" Once several sessions are running this way, the Cockpit's fleet map can answer a related question fleet-wide: pick **By working tree** in the pivot row and your *running sessions* are grouped by the name of the folder each one is working in, where grouping by repository would fold them back together. It is a picture of the sessions, not of the folders: a worktree nothing is running in does not appear there - this Worktrees page is where those live. Reading the map is [its own tutorial](https://devthrottle.com/docs/tutorials/fleet-map). > **Warning:** This tutorial stops at seeing them. The Worktrees page can also show a button reading **Remove 3 orphaned worktrees** - the count is real and the button only appears when it is above zero - and removing a worktree deletes that folder from your disk with no undo. What its checks do and do not establish needs a page of its own rather than a paragraph at the end of this one. Until that page exists, treat those removals as yours to decide. ## Next Which folders get scanned in the first place is on [Repositories and GitHub](https://devthrottle.com/docs/director/repositories). For reading what a session changed before you merge it, see [Source control and history](https://devthrottle.com/docs/director/source-control). And when one machine stops being enough - a separate problem with a separate answer - see [Using more than one machine](https://devthrottle.com/docs/tutorials/many-machines). --- # Workflows: your named ways of working > Write down how a job should be run once, publish it, and sessions launched after each Director's next poll see it in their briefing - starting from a built-in workflow rather than a blank file. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/workflows Last updated: 2026-08-07 You have explained the same thing to agents more than once. Always branch before you change anything; never call it done until the tests pass; tell me once at the end rather than four times along the way. Written into a prompt, that guidance lasts one session. Written into a workflow, it reaches every machine: sessions launched after each Director's next poll see it in their briefing, and the ones that do that kind of work read it and follow it. A session started before the poll can still get the old catalog, and sessions already running keep the briefing they started with. About fifteen minutes. You need a Gateway and the DevThrottle command line, which installs with the product. 1. **See what your fleet already works by** **The catalog** ``` cc-devthrottle workflow list ``` Three come built in - **mission**, **standalone** and **standalone-with-review**. The first is the Team way of working - an Architect, a Manager, and Workers - shipped in the catalog under the name mission. They are not examples; they are in force right now, and every one of your sessions starts with them in its briefing. 2. **Read one properly** **What a session actually receives** ``` cc-devthrottle workflow instructions standalone ``` Read the output before writing anything of your own. Notice how short it is, and that it is guidance rather than a script - a few hard rules, stated plainly. That is the shape you are aiming for. A workflow nobody can hold in their head is one sessions will follow unevenly. 3. **Start from one that already works** Do not start from an empty file. Pull an existing workflow into a directory and edit it: **Pull it down** ``` cc-devthrottle workflow pull standalone --dir ./my-workflow ``` You get the workflow's definition in `workflow.json`, its instructions in markdown, and any helper files. The markdown is the part that matters - it is the conduct a session following the workflow reads. 4. **Write the rules, then give it an id of its own** Edit the instructions. Write the handful of things you find yourself saying over and over, and say why for each - a session that understands the reason applies a rule sensibly in a case you did not foresee, and one that only has the rule will not. Then open `workflow.json` and change the `id` (and the name) - the pulled file still says `standalone`. This is not optional: built-in workflows are read-only, so a push aimed back at `standalone` is refused, and a push aimed at a new id is refused until the id inside `workflow.json` agrees with it. Pick the id you want to live with - `my-branch-rules` in the steps below. 5. **Push it as a draft, then publish** **Draft first, then live** ``` cc-devthrottle workflow push my-branch-rules --dir ./my-workflow cc-devthrottle workflow publish my-branch-rules ``` Pushing creates a draft and changes nothing about how your fleet behaves. Publishing is the moment it takes effect: the Gateway serves the new version at once, with nothing to deploy and no restart. Each Director picks it up on a poll about every minute, and from its next poll onwards the sessions it starts see the new catalog entry. Nothing is retroactive: a session already running keeps the briefing it started with, and one started in the first moments after you publish can still carry the old catalog. 6. **Check it landed** Open **Workflows** in the Cockpit. Yours is in the list, marked in force, with its version and the date it changed. Within about a minute, newly started sessions anywhere in your fleet see it in their briefing - sessions already running are not interrupted with it. > **Note:** Publishing will not disturb work already in progress. A run keeps the version it was pinned to when it started, so you can improve a workflow without rewriting the rules under a job that is halfway done. > **Tip:** The best first workflow is the shortest one. Take the single instruction you are most tired of repeating, write only that, and publish it. You can always add to it - and a workflow that is actually followed beats a thorough one that is skimmed. ## Next For the full command surface - turning a workflow off without deleting it, cloning one in a single command, and reading past runs - see [Workflows](https://devthrottle.com/docs/gateway/workflows). If your workflow describes work split across several sessions, see [Roles: who plans, who manages, who builds](https://devthrottle.com/docs/tutorials/roles). --- # Line up the next instruction > Queue what comes next while the agent is still busy, instead of sitting there waiting for a free moment to type it. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/queue-next Last updated: 2026-08-04 You are watching an agent work and you think of the next thing you want it to do. It is two minutes into a task and going well. Interrupting it now to say the next thing is a bad trade, and holding the thought until it finishes means you have to be there at the moment it finishes. There is a third option, and it is the habit that makes running several agents bearable: write the instruction now, queue it, and send it when you are ready. Five minutes. You need DevThrottle open with one session that is actually working on something. This is the deeper half of [The prompt bar is not the terminal](https://devthrottle.com/docs/start/prompt-bar), which introduces the queue; everything below is what to do once you are using it. 1. **Write it while the agent is still busy** Type the next instruction into the prompt bar under the terminal, exactly as you would any other. Nothing has reached the agent - the prompt bar is a separate box that lives outside the terminal, so you can write slowly, change your mind, or dictate it, and the agent carries on undisturbed. 2. **Queue it instead of sending it** Press **Ctrl+Shift+Enter** - or click **Queue**, the third button down beside the box, under Send and Speak. The box empties, and your instruction is now in the session's queue. Two things on screen tell you so: the Queue button turns red and starts counting, reading **Queue (1)**, and the queue itself appears in the panel on the right of the window. If that right panel is collapsed, expand it with the chevron at its edge to see the list. 3. **Understand what the queue is, because it is not an autopilot** This is the step that decides whether the habit works for you or quietly costs you an afternoon. **Nothing in the queue is sent until you send it.** DevThrottle does not watch for the agent to finish and feed it the next item. The queue is a list of instructions you have written and not yet delivered - a notepad with an order to it, attached to the right session. That is a deliberate limit rather than an oversight. An agent that has stopped has either finished cleanly or stopped to ask you something, and those look the same from outside. Firing the next instruction into the second case would answer a question with unrelated text. 4. **Stack a few, and put them in the order you want** Queue two or three more the same way. Each item in the panel carries its own controls: arrows to move it up or down the list, **Edit** to open it in the larger editor and reword it, and **X** to drop it. Use them - the order you thought of things in is rarely the order you want them done in. 5. **Send one when the agent stops** When the session goes quiet, open the queue and click **Pop** on the item you want. Its text lands back in the prompt bar and it leaves the queue. Read it once - the agent's last turn may well have changed what you want to say - then send it with **Ctrl+Enter**. Popping and sending are two separate actions on purpose. That gap is where you adjust an instruction you wrote twenty minutes ago against what the agent actually did in the meantime, and it is the main reason queueing beats remembering. > **Warning:** **Clear** at the top of the queue panel empties it immediately, with no confirmation and no undo. Several carefully written instructions can go with one click. Remove items one at a time with **X** unless you really do mean all of them. > **Tip:** Pop appends to whatever is already in the prompt bar rather than replacing it, so send or clear what you are holding before you pop, or the two run together into one message. > **Note:** The queue belongs to the session, not to the window. Queued prompts are saved with the session and are still there after you restart DevThrottle - so an instruction you wrote last night survives to the morning. > **Note:** The same queue is in your [browser](https://devthrottle.com/docs/cockpit/session-view), where each item has a **Send** button of its own that submits it straight away - one press instead of pop-then-send. ## Next Once you have sent an instruction and the agent has acted on it, read the difference before you keep it: [See what changed](https://devthrottle.com/docs/start/what-changed). For every prompt-bar control and shortcut in one place, see [The embedded terminal](https://devthrottle.com/docs/director/terminal). --- # Pair your phone with your fleet > Set your phone up once, and every session you are running is in your pocket from then on. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/pair-phone Last updated: 2026-09-06 The phone is the piece of DevThrottle you set up before you need it, because the moment you need it - a session waiting on one word from you while you are in a queue at the supermarket - you are by definition away from the computer that could set it up. The thirty-second rescue tutorial starts from a phone that is already paired. This is that pairing: once, about five minutes, and you do it at your desk. You need DevThrottle installed and connected to a gateway - that is [step 1 of the path](https://devthrottle.com/docs/start/install) - and your phone. There is no app store download: the app is served to the phone's browser by your own Gateway, and the only install is pinning it to your home screen near the end. 1. **Open the Cockpit's Phone page and scan the code** The phone reaches your fleet through your Gateway, so the first job is getting the Gateway's address across the gap to the phone - and there is a page for exactly that. Open the Cockpit in a browser and click **Phone** in the rail, just under **Account**: *Open DevThrottle on your phone - the same fleet, sized for one hand.* The first card is **Scan this with your phone camera**. Point the phone's camera at the code and open what it offers. The address it carries is the one you reached the Cockpit on, so the phone has to be on a network that can reach this Gateway - the page says exactly that under the code. The second card, **Or type it in**, shows the same address in full with a **Copy link** button beside it, which is the easy way to send it to yourself in a message. And where a code could not work at all - a Cockpit opened on `localhost`, whose address no phone can reach - the page says so in the Gateway's own words rather than drawing a code that would scan perfectly and then time out. 2. **No Cockpit to hand? Read the address off the Director** The address is on the desktop too, if that is where you are. If you took the hosted gateway in the setup wizard, its connected badge read **This machine is enrolled with**, followed by exactly this address; any time after that the Director keeps it in **Settings**, under **Gateway**. Type it into the browser on your phone. The Gateway notices it is a phone and serves the phone app instead of the desktop pages - same address, no special path to remember. Running your own gateway instead of the hosted one? Read the warning at the end of this page before going on - the address the phone needs is the secure https one, not a plain local one. Either way, what comes up on the phone is a sign-in screen: the app knows nothing about you yet, and says so - "Sign in to connect this phone to your account." 3. **Tap Sign in, and approve the phone on devthrottle.com** The phone is sent to devthrottle.com to sign in - Google, GitHub, or email, the same choice as when you connected the machine. Then comes the screen this flow exists for: **Connect this phone?** It names the device asking (an iPhone or an Android phone) and shows which account it would join, on a line reading **Signed in as** your email. Read that line before you tap. The phone must join the *same DevThrottle account you connected this machine with* - if the browser happens to be signed into a different one, **Use a different account** is right there next to it. Then tap **Connect this phone**. (A deny button sits below it, and it means what it says: nothing is handed over.) 4. **Land on your sessions** The phone returns to your Gateway, shows **Connecting...** for a moment, and lands on the roster - your sessions, the same ones the Director shows, in your pocket. That is the pairing done; it does not need doing again. 5. **Add it to your home screen** Before the notification step, put the app on your phone's home screen -**Add to Home Screen** on an iPhone, **Install app** on Android, the same two names the Cockpit's Phone page gives them. It opens full screen like any other app from then on, and on some phones - iPhones in particular - notifications only work once the app is installed there; in a browser tab that cannot show them, the next step's banner simply never appears. Open the app from its new home-screen icon before going on. > **Note:** One phone can hold more than one DevThrottle account, and you switch between them from the phone's own **Account** screen - so a work fleet and a personal one live side by side on the same handset without pairing anything twice. 6. **Turn on notifications before you put the phone away** At the top of the roster is a banner: "Get an app-icon dot when a session needs you", with an **Enable notifications** button. Tap it and allow the permission. This is the step that makes the phone worth pairing - the app icon gets a dot while a session needs you, and the dot clears when nothing does. (One deliberate exception: a waiting session on a machine that cannot be reached right now stays on the roster but does not light the dot - there is nothing you could do about it yet.) Skip it, and the phone only helps on the days you remember to check it, which is exactly the job you were trying to give away. The banner answers every outcome rather than failing quietly. No banner at all - when notifications are not already on for this device - means this browser cannot show push notifications at all; on an iPhone that is what a plain browser tab does, and opening the app from its home-screen icon (the previous step) is what makes push exist there. Dismiss the permission prompt and the banner says so and offers **Try again**. And if notifications are blocked outright, it tells you the block lives in your browser's site settings, which is where to lift it. > **Note:** What the phone keeps is a key for this one device, not your account. With the hosted gateway, the approval hands the phone a short-lived sign-in token that the gateway checks once, trades for that device key, and discards. Pairing with a self-hosted gateway instead registers the phone on your account's [Devices](https://devthrottle.com/docs/account/devices) page, where it can be revoked if it is ever lost. The full security model, and the enrolment flow in detail, are on [the pairing reference page](https://devthrottle.com/docs/mobile/pairing). > **Warning:** Running your own gateway rather than the hosted one? Two things must be true before the flow above can finish. Your Gateway must itself be signed in to your DevThrottle account - it verifies the phone's key against that account, and if it is not signed in, the connecting screen says exactly that and offers the sign-in that fixes it. And the phone must reach the Gateway at its secure https address - self-hosted, that is its Tailscale front door, reachable once the phone has joined your tailnet. A plain http address on your Wi-Fi cannot complete the approval: devthrottle.com refuses to hand a device key back to an insecure address. ## Next The thirty-second version of using what you just set up: [Answer an agent in thirty seconds](https://devthrottle.com/docs/tutorials/quick-answer). For everything the phone can do with a session - the roster, chat, the live terminal, sending photos - see [Sessions on your phone](https://devthrottle.com/docs/mobile/sessions). --- # Answer an agent in thirty seconds > An agent has stopped and is waiting on you while you are out. Open your phone, read the question, answer it, and put the phone away - the short interaction you will do most often. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/quick-answer Last updated: 2026-08-03 An agent has stopped and is waiting on you, and you are in a supermarket. The work is done in thirty seconds if you can see the question - and sits idle for two hours if you cannot. This is the short interaction, the one you will do most often. You need your phone already paired; if it is not, [do that first](https://devthrottle.com/docs/tutorials/pair-phone), because you cannot set it up from the aisle. 1. **Open DevThrottle on your phone** In the session list, anything waiting on you sits under a red **Needs you** heading, longest-waiting first, above the other sessions. No Needs you section means nothing is waiting - with one caveat: a machine or repository filter you applied earlier sticks on the phone and can hide waiting sessions. If a strip under the title bar names a filter, tap **Clear** before trusting an empty list; if there is no strip, you can put the phone away. ![The DevThrottle phone roster with a red Needs you section listing two waiting sessions - Export notes to CSV in the notes-cli repository and Add task filtering in demo-app - each showing how long it has been waiting, when it started, its idle time and turn count](https://devthrottle.com/docs/screenshots/mobile/roster-needs-you.png) Each card tells you how long it has been waiting, which repository it is in, and how many turns it has taken. The waiting time is the one to read: it is how much of your day this agent has already lost. 2. **Open the one that is waiting** Tap the card. You get the conversation, ending with whatever the agent last said - which, when it is waiting on you, is the question. Read that and nothing else. You are not here to review the work. One exception: a session in voice mode opens on its Voice screen instead, ready to speak its update aloud - that is working by voice on a walk, and [its own tutorial](https://devthrottle.com/docs/tutorials/voice-walk) covers it. 3. **Answer it** Type your answer and send. Short is fine - "yes", "do the second one", "leave that alone for now". The agent picks up where it stopped. If it is easier to say than to type, tap **Speak** instead of the keyboard: talk, tap **Pause** to see the words and fix any of them, then **Insert** them into the box or **Send** them straight to the agent. Standing in a queue, talking is usually faster and less error-prone than thumbs. 4. **Put the phone away** That is the whole loop. Do not stay to watch - the roster refreshes itself every few seconds and will put the session back under Needs you when it wants you again. Check back when it tells you to, not before. > **Note:** Turn on notifications: when the roster offers **Enable notifications**, tap it and allow the permission - from then on the app icon carries a dot while a session needs you. The offer only appears in a browser that can show notifications; on some phones, iPhones in particular, that means adding the app to your home screen and opening it from its icon, as the [pairing page](https://devthrottle.com/docs/mobile/pairing) explains. Without the dot this only works if you remember to check, and the entire value here is not having to remember. > **Tip:** If a question needs more context than you can get from a phone screen, it is reasonable to answer "wait, I will look at this properly later". An agent left waiting on purpose is better than one steered badly in a hurry. ## Next For the phone roster, chat controls and file viewer in detail, see [Sessions on your phone](https://devthrottle.com/docs/mobile/sessions). For hours of real work by voice rather than a thirty-second rescue, see [A whole session by voice, on a walk](https://devthrottle.com/docs/tutorials/voice-walk). --- # A whole session by voice, on a walk > Voice mode reads each turn out loud and you answer by talking - hours of real work from a footpath or a quiet bench, with no screen. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/voice-walk Last updated: 2026-08-07 There is a version of this product where you close the laptop, put one earbud in, and keep working - not checking on work, doing it. Voice mode reads each agent's turn out loud as it finishes, you answer by talking, and the phone moves to the next one waiting. An hour's walk becomes an hour of steered work, and you never look at the screen. Setting it up takes about ten minutes the first time. The walk can be as long as you like. You need your phone already paired, and at least one session running on a machine you are leaving behind. If the phone is not paired, [do that first](https://devthrottle.com/docs/tutorials/pair-phone) - you cannot set it up from the footpath. 1. **Before you leave: put the whole fleet on voice** Open DevThrottle on your phone and switch the roster to the **Voice sessions** tab. At the top is one button that counts your fleet as it asks: **Turn on voice mode for all 4 sessions** if you are running four, **Turn on voice mode for all 1 session** if just one. Tap it once. From now on every session sends each completed turn that has a written answer in it for narration - including sessions that start after you walk out the door. A clip is not guaranteed for every turn; when one cannot be made the screen says why, and [Voice on your phone](https://devthrottle.com/docs/mobile/voice) lists those answers. This is a fleet-wide switch, not a phone setting: your sessions are now speaking, whether or not this phone is listening. If a machine is offline when you tap it, its sessions join when it comes back - the button tells you what changed and what was skipped. 2. **Turn on Auto-speak** On the same tab, tick the **Auto-speak** checkbox. This one is about your phone, not the fleet: when a session finishes a turn and is waiting on you, the phone opens it by itself, oldest first, and plays the narration without a tap. The two switches are separate on purpose. Voice mode on with Auto-speak off is a fleet that speaks when you choose to listen; both on is the hands-free queue this walk needs. 3. **Start walking, and just listen** When a session needs you, the phone opens it and reads the turn out loud - what the agent did, and what it is asking. If you miss something, the player at the top has play, pause, restart, and a seek bar. The full text is on screen below the controls, but the point of this mode is that you do not need it. 4. **Answer with Respond** The two buttons you act with sit at the top of the screen, same place in every state, big enough to hit while moving. The first is **Respond** - it is there whenever a narration is up. Tap it, say your answer, and tap **Send**. If you want to check what the transcription heard, tap **Pause** first and read it; otherwise just send. Your reply is transcribed and delivered in the background, and the screen goes straight back to the queue. You do not wait for the agent - after the queue's deliberate pause, the next session waiting on you opens and is read to you. 5. **Clear the rest with Snooze** Not everything on a walk deserves an answer. The second button is **Snooze**: one tap silences that session for your default length and returns to the queue. Once your own snooze lengths have been read from your Gateway, a narrow caret sits beside it and opens a **Snooze for** sheet listing them, for the session that needs longer than your default. Snooze is the verb that keeps the walk moving. An agent asking something that needs a screen, a session you want to think about at your desk - snooze it, and it will be waiting when you are back. Answering badly at pace is the only real mistake this mode lets you make. 6. **Know the way out of the loop** After a Respond or a Snooze, the queue waits three seconds before opening the next session, and says so on screen: uncheck **Auto-speak** in that pause and the loop stops. That pause is the designed exit - without it you would be carried from session to session with no moment to leave. A session you have just listened to is also passed over for a short while, so a single busy session cannot trap you in a one-item loop. 7. **Come home** Back at your desk, open the **Voice sessions** tab again. The same button now reads **Turn voice mode off for all sessions**. Tap it, untick Auto-speak, and the fleet is silent again. > **Note:** This is a screen-on mode. While the app is in the foreground the phone asks the browser to keep the screen awake - where the browser does not support that, it cannot, and the screen sleeps on its own schedule. A narration that would start while the app is hidden or the phone is locked is skipped; whether one already playing keeps going under lock is your phone's decision, not DevThrottle's. When you return to the app, if the next narration does not start on its own, tap the session and it plays. And Auto-speak does not know where the phone is: an unlocked phone with the app open keeps opening sessions and talking from a pocket. Phone in hand, one earbud; untick Auto-speak when you want the queue to stop. > **Tip:** You can put a single session on voice without touching the fleet: open it, pick the **Voice mode** tab, and tap **Switch to voice mode**. That is the right size for one long-running job you care about; the fleet-wide button is for the walk. ## Next The Voice mode screen in full - the player, the status cards, and the language and voice the narration speaks with - is on [Voice Mode on your phone](https://devthrottle.com/docs/mobile/voice). Dictation everywhere else, and the custom dictionary that stops it mangling your project's names, is on [Voice](https://devthrottle.com/docs/voice/overview). For the thirty-second version of working from your phone - one agent, one question, back in your pocket - see [Answer an agent in thirty seconds](https://devthrottle.com/docs/tutorials/quick-answer). --- # Your whole fleet in a browser tab > A hotel laptop, a client machine, a spare desktop - sign in and every agent you are running is there, with nothing to install on the machine you are borrowing. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/cockpit-anywhere Last updated: 2026-09-06 You are away from the office with a real keyboard in front of you - a hotel laptop, a client's spare machine, a desktop that is not yours. Your agents are still running at home. This gets you back to all of them in a browser tab, with nothing installed on the machine you are borrowing. About five minutes. You need DevThrottle already running somewhere with a Gateway, and the sign-in you use for DevThrottle. 1. **Open the Cockpit in any browser** Go to your Gateway's address in a browser and sign in. That is the whole install step - there isn't one. The Cockpit is a web page your Gateway serves, so any machine with a browser can reach it without downloading anything. One habit worth keeping on a machine that is not yours: open a private browsing window first. Signing in registers the browser as a device on your account, and a private window forgets that the moment it closes - so the enrolment cannot outlive a walk away from the desk you forgot to tidy. It is belt and braces rather than the only way out: the last step signs out properly, and this is what covers you if you never get to it. 2. **Find your sessions** Signing in lands you on the fleet map - the whole fleet as one picture. For working through what is waiting on you, the list is the better tool: click **Sessions** in the rail on the left. The session list shows every session in your fleet, listed under the Director that runs it - the heading is that Director's machine name. A machine usually runs one Director, so the sections mostly read as machines; a machine running two Directors shows as two Director sections. Each card shows what the session is doing, how long it has been waiting, and how many files it has changed but not committed. ![The Cockpit session rail listing three sessions on SOREN_NORTH, each showing Needs you, a started time, open and idle timers, a turn count, and a yellow uncommitted-changes badge reading 4 chg, 2 chg and 3 chg](https://devthrottle.com/docs/screenshots/cockpit/session-rail.png) Switch the ordering to **Attention first** and whatever is waiting on you comes to the top. On a borrowed machine, with limited time, that is usually the only ordering you want. 3. **Answer one** Click a session. You get its live terminal, the prompt box, and its queue - enough to read what the agent did, tell it what you want, and move on. Type your answer and send it exactly as you would at your own desk. 4. **Sign out before you hand the machine back** Signing in enrolled that browser as a device on your account, and closing the tab does not undo it. Undo it deliberately: open **Account** in the rail and look at **Signed in on this browser**, at the top of the page. With one account it offers **Sign out**; with several, **Sign out of this account** and **Sign out of all**. Each asks first, and the button that commits reads **Yes, sign out**. Read what comes back rather than walking away on the click. Sign-out clears the credential on the Gateway before it forgets the key in the browser, and if the Gateway cannot be reached it does neither and says so - nothing is signed out, and you can try again. There is no half-done state to leave behind. Then finish the job from a machine that is yours. Signing out is this browser forgetting its key; the device itself stays on your account's roster until you remove it there. Open **Account**, find the borrowed machine under **Your devices**, and remove it - that is what revokes its access. The **Log out** button further down that page is not this: it belongs to **This Gateway's account**, the Gateway's own sign-in, not the browser you borrowed. > **Warning:** Whether a borrowed machine can reach your Gateway depends on which Gateway you chose. The hosted Gateway is a public web address, reachable from any browser on any network - nothing to prepare. A self-hosted Gateway runs on your own machine, and reaching it from outside your own network is yours to arrange - the part worth sorting out *before* you travel rather than in a hotel lobby. Both cases, in detail, on [Answering from another machine](https://devthrottle.com/docs/cockpit/remote). > **Note:** This is the same Cockpit you would open at your own desk - there is no reduced remote mode. The fleet map, your history, the dictionary and your usage are all there too. ## Next For reachability in detail see [Answering from another machine](https://devthrottle.com/docs/cockpit/remote) and [network speed and diagnostics](https://devthrottle.com/docs/gateway/network). If you only have your phone rather than a keyboard, read [Answer an agent in thirty seconds](https://devthrottle.com/docs/tutorials/quick-answer) instead. To see the whole fleet as one picture, see [The fleet map](https://devthrottle.com/docs/tutorials/fleet-map). --- # The fleet map > Every machine and every session you have running, drawn as one picture - so the only question that matters, is anything waiting on me, is answered before you read anything else. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/fleet-map Last updated: 2026-08-07 Once more than one session is running, the question stops being "what is this session doing" and becomes "is anything waiting on me". The fleet map answers that in one picture: every machine, every session, and who needs you - across your whole fleet rather than one window. This takes about five minutes. You need at least one session running; the map is more useful the more you have, but it reads the same either way. 1. **Open the fleet map** In the Cockpit, choose **Fleet Map** in the left rail. The map remembers whichever grouping you used last, so before reading on, make sure **By machine** is selected in the row of buttons at the top right - that is the view this tutorial reads. The line along the top is then the whole answer before you look at anything else: how many sessions exist, how many machines they are spread over, and how many repositories they touch. When sessions are busy, a blue *working* count joins that line; when any session is waiting on you, a red *needs you* count appears at the end. The red number is the thing to look for. If it is there, that many sessions are waiting for you. If there is no red number at all, nothing needs you and you can close the tab. That is the point of the page. 2. **Read the shape** Underneath, the fleet is drawn as a tree. Your Gateway sits at the top, each machine hangs off it, and each session is a card on its machine. A card carries the session number (when the session has been assigned one), the session's name, and its state in words, next to a relative time - "2m" means the session was last active two minutes ago. It is the same time on every card, whatever its state, not a count of how long a red one has been waiting. The card's other tags - which coding agent is running it, which model, which repository or machine - adapt to the grouping, so a card never repeats what its own column heading already says. The coloured dot is the state, and the key along the bottom tells you which is which. Red is the one that matters: it means the session has stopped and is waiting for a human. 3. **Group it a different way** The buttons above the map re-draw the same fleet around a different question. There are eight groupings: **By machine**, **By director**, **By repository**, **By working tree**, **By agent**, **By model**, **Fleet list**, and **Missions**. Three of them cover most days: **By machine** answers "is one computer overloaded", **By repository** answers "how many sessions are in this codebase at once", which is the one that catches two sessions about to collide, and **By agent** answers "what am I actually running". Click between two of them now. Nothing changes about your fleet - only how it is arranged in front of you. One grouping changes the top line too: on **Missions** it counts missions and standalone sessions instead of machines and repositories, though the working and needs-you counts still behave the same. 4. **Find one session and go to it** Type part of a name into the search box - every grouping except Missions has one - and the map narrows to matching sessions. Click a card to open that session and answer it. That is the whole loop the map exists for: spot the red one, click it, deal with it, come back. > **Note:** With a single machine the map looks modest, and that is fine - it is still the fastest way to see everything waiting on you. It earns its keep when you are running several machines, which is when no single window can show you the fleet any more. > **Tip:** The fleet map is a browser page served by your Gateway, so it is also what you open from a laptop that is not yours. Nothing to install, and the same picture. ## Next For what each grouping does in detail, how the fleet list differs from the map, and what an unreachable Director looks like, see [The Fleet Map](https://devthrottle.com/docs/cockpit/fleet-map) in the Cockpit reference. To reach all of this from somewhere other than your desk, see [Your whole fleet in a browser tab](https://devthrottle.com/docs/tutorials/cockpit-anywhere). --- # What did I actually get done this week? > Your agents worked while you were elsewhere. The Cockpit history shows what ran, in which repository, how many turns it took and how often it needed you - which is the number worth acting on. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/weekly-review Last updated: 2026-08-03 Agents work while you are elsewhere, which is the point of them - and it makes Friday afternoon strange. Plenty happened, and almost none of it happened in front of you. This is how to find out what your fleet actually did. Five minutes, and worth making a habit rather than a one-off. You need a Gateway and some history to look at. 1. **Open History and widen the window** In the Cockpit, choose **History**. It opens on a short window; switch it to **Week**. The line beside the buttons is the first real answer - how many sessions ran, across how many repositories. That number is usually higher than people expect, which is the whole reason to look. 2. **Read it by repository, not by session** The page groups work under the repository it happened in, and then by day. That grouping is deliberate and it is the useful one: it answers "where did my week go" rather than "what was session 101". ![The Cockpit History page over a three day window showing seven sessions across four repositories, grouped by repository and day, each entry listing the instruction given, the session name and number, the coding agent and model, when it started, how many turns it took and how often it needed a human](https://devthrottle.com/docs/screenshots/cockpit/history.png) The line each entry leads with is filled in a fixed order: a session on a mission shows the mission, with the session's role on it; otherwise it shows the first instruction the session was given; and a session with neither falls back to its name and repository. Day to day that usually means the instruction, which is far more useful than a name - names are what you called something hopefully at the start; the instruction is what really happened. 3. **Look at the turns and the needed-you count** Two numbers on each entry are worth more than the rest, and they read literally as **7 turns** and **needed you 3x**. Turns counts the agent's completed turns - each stretch of work that ended with the agent stopping for input - not exchanges in some looser sense; records from older Directors fall back to counting the instructions sent in. Needed you counts how many times the session started waiting on a human. The needed-you count is a raw tally, not a diagnosis: a real question, a permission prompt and plain finishing all enter it the same way, and the number never says why the agent stopped. Treat it as a pointer rather than proof. A job that needed you four times is usually worth reading back, because often the instruction left something open - and that habit is still the most useful thing on this page: it turns a vague sense that agents are hard work into a specific prompt worth rewriting. 4. **Pick one thing to change** Find the entry with the worst needed-you count and read the line it leads with - if it does not show an instruction, pick the worst prompt-led entry instead. Not every high count hides a bad prompt; some of those waits were permission clicks, or the job simply finishing. But if the instruction did leave something open, rewrite it in your head to close the opening you found. That is the whole review - not a report, one improvement. > **Note:** History covers every repository and machine in your fleet, including the sessions running right now, so it is a fair picture rather than a tidy one. Days show a summary line once one has been written for them. > **Tip:** Do this on a Friday with the week window open. Looking back over one day tells you almost nothing; over a week the pattern in your own prompts becomes obvious. ## Next History tells you what the fleet did. **[Your Throttle](https://devthrottle.com/docs/tutorials/your-throttle)**, at the bottom of the same rail, tells you how you drove it - how much you spoke versus typed, and from which surface. It shows activity, not money: agents running on your own subscriptions and keys never appear as spend on [Usage](https://devthrottle.com/docs/account/usage). To make an agent stop needing you so often, see [Steer an agent that is going wrong](https://devthrottle.com/docs/start/steering) and [Workflows](https://devthrottle.com/docs/tutorials/workflows), which is how a good instruction gets reused instead of retyped. --- # Teach it the words you use > Dictation keeps mangling your product and repository names. Fix it once: teach your Gateway dictionary the right spellings and the wrong ones you have seen, and they are corrected everywhere you dictate. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/dictionary Last updated: 2026-08-07 You dictate a prompt, and the one word that matters comes out wrong. Your product name, your repository, the library nobody outside your team has heard of. You fix it by hand, and the next time you dictate it happens again. This walks you through fixing that permanently - about five minutes, once. The fix covers everywhere you dictate, on DevThrottle's hosted Gateway and on a Gateway you host yourself alike. You need DevThrottle running and a Gateway connected. You do not need a session running, and you do not need your phone. 1. **Open the Dictionary in the Cockpit** Open the Cockpit in your browser and choose **Dictionary** in the left rail. What you are looking at belongs to your Gateway, not to this browser or this machine - which is the whole point. Teach it here and every Director connected to that Gateway gets it, along with transcription of the voice notes you record on your phone. 2. **Add the word under Vocabulary** Click **+ add term**, type the word the way it should be spelled, and press Enter. It appears as a chip. Add as many as you like before moving on - product names, repository names, the tools you say out loud all day. These are your canonical spellings - the way you want each term written. A term on this list is not enough on its own: the cleanup pass does not go looking for them, and the next step is what actually gets one corrected. 3. **Tell it the wrong spellings you actually saw** Under **Common mistranscriptions**, click **+ add a term to correct** and enter the correct spelling. A row appears with a **+ wrong spelling** box beside it. Put in what you really got - if dictation gave you "dev throttle" and "def throttle", add both. This is the step that does the work. A wrong spelling you have listed is corrected every time it appears, exactly; as DevThrottle ships, a wrong spelling you have not listed is left exactly as you said it. So the moment you catch one, add it here - that is what makes the fix happen at all. 4. **Save** Click **Save**. The button goes inactive once there is nothing unsaved, which is how you know it took. If you try to leave the page with unsaved edits it stops you and asks first. ![The Cockpit Dictionary page with seven vocabulary chips including DevThrottle and Kubernetes, and a correction row pairing DevThrottle with the wrong spellings dev throttle and def throttle](https://devthrottle.com/docs/screenshots/cockpit/dictionary.png) 5. **Say it again** Go back to a session and dictate a sentence with the word in it. There is nothing to restart and nothing to copy anywhere - the dictionary is read fresh each time it is used, so the change applies on your very next dictation, and on your next phone voice note transcript too. ## What is worth adding Start with the words you say most and that are least like ordinary English: your product, your repositories, your framework names. Do not try to fill this in one sitting. The useful habit is to add a word the moment it annoys you - by then you know both the right spelling and the wrong one, which is exactly what the two lists want. > **Tip:** Corrections happen on the text, after transcription, inside your Gateway. Your dictionary is never sent anywhere with your audio. > **Note:** DevThrottle also scans your dictations overnight and offers terms it thinks it keeps getting wrong - that is the banner across the top of the page. Ticking suggestions and pressing **Add** writes them to your dictionary immediately - the banner is separate from the Save button below it, and nothing changes until you press Add. ## Next For what each list does under the hood, how the cleanup pass is deliberately limited, the one setting that widens what it may change, and what happens if the dictionary is unavailable, see [Your dictation dictionary](https://devthrottle.com/docs/voice/dictionary). If you have not tried dictating yet, start with [Talk to your agents instead of typing](https://devthrottle.com/docs/tutorials/dictation). --- # Your Throttle: what you have used > How you actually drive your fleet - spoken vs typed, phone vs desktop, and which repositories and agents the work went into. Activity in turns and characters; no money anywhere, by design. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/your-throttle Last updated: 2026-08-07 After a few weeks of driving agents you start to wonder about your own habits. How much of this do I actually speak rather than type? How often am I steering from my phone? Which repositories is the work really going into? Your Throttle is the page that answers those questions - a private dashboard of how you drive your fleet. One thing to know before you open it: the page shows **activity, not money**. It counts turns and characters - never cost, credits, balance, or tokens. That is a deliberate product decision, and it holds everywhere in DevThrottle: your agents run on your own subscriptions and keys, so there is no meter running behind this page. Five minutes. You need the Cockpit open - if you have never opened it, start with [Open the Cockpit from any browser](https://devthrottle.com/docs/tutorials/cockpit-anywhere). 1. **Open Your Throttle** In the Cockpit, look at the **bottom** of the left rail - the short list pinned under the fleet destinations, where Account and Settings live. Choose **Your Throttle**. If you have never sent anything, the page says so and asks for a turn rather than showing a made-up zero. Send one message to any session and come back. 2. **Read the three rings** The page opens on **Overview**: three rings, one question each. **Voice vs typing** is how much of your driving you speak. **Mobile vs desktop** is how much of it comes from your phone. **Wingman (voice mode)** is how much happens with voice mode on, with a note counting the sessions that used it. The unit everywhere is the **turn** - one submitted message. One spoken utterance and one typed message each count as one turn, which is what makes the voice share a fair comparison. Below the rings, a single bar shows where your turns come from - desktop, cockpit, phone - and three tiles give the totals: turns, characters driven, and the most sessions you have ever had running at once. 3. **See your working day on the Activity tab** **Activity** holds two charts of the last 24 hours. **Turns per hour** is the shape of your working day - each bar an hour, voice stacked over typed, empty bars where you were away. **Sessions per hour** is the fleet's shape - how many sessions were loaded or running each hour, with the darker portion actively working. The hours read in the time zone set in Settings, so the axis matches your clock. 4. **See where the work went on the Repos tab** **Repos** ranks the codebases you work in by how much driving each one took. It is badged **Private - only you**: which repositories take your time is nobody else's business, so this tab never renders next to the shareable splits - you have to select it. Each row is one repository, with a bar split into spoken and typed turns. Every worktree and every machine you check a repository out on rolls up into its one row - and when more than one checkout fed a row, the working directories are listed under the name. Switch the ranking between **Turns**, **Characters**, and **Sessions** - sessions is the count of distinct sessions that drove input into that repository. Time spent is deliberately not shown: an idle hour looks the same as a heads-down hour, so it would lie. Turns and characters track what you actually pushed through. 5. **See which agents you drive on the Agents tab** **Agents** is the same ranking by the agent CLI the work goes through - Claude Code, Codex, and the rest. It is also where the fleet's own driving shows up: turns one agent drove into another are counted separately from yours, never added in, and once they exist a **Leverage** card states how many turns the fleet spent off the back of each turn of yours. This tab states the date its attribution started, and its numbers can be smaller than the all-time totals on the other tabs: sessions that finished before the breakdown existed never recorded which agent they ran under, and the page will not guess. > **Note:** The **Breakdown** tab holds the supporting tables: fleet concurrency now, this week, and all-time; turns by surface; the full voice-and-typed by surface table; and a plain list of what the numbers do not include. When a figure on the other tabs surprises you, this is where to check what it is made of. > **Note:** The page refreshes itself every ten seconds, and it remembers which tab you were on in this browser. Your phone has a compact Your Throttle too - the three rings and the totals under the menu - and a separate Repos item; the full charts and breakdown stay on the desktop page. > **Tip:** Counting happens at the Director, so turns you type into the desktop app count the same as turns sent from the phone or the Cockpit. If your voice share looks low, remember it is measuring everything - including the quick typed one-liners you forget about. ## Next Your Throttle is how *you* drove; for what the *fleet* did, work through [What did I actually get done this week?](https://devthrottle.com/docs/tutorials/weekly-review). Separate from all of this, your account on devthrottle.com has a [Usage](https://devthrottle.com/docs/account/usage) page - the record of requests to DevThrottle hosted AI, such as dictation. As a member you see activity there too, in each service's own units; the only money on it is shown to the service's administrators, not to you. Sessions running on your own subscriptions and keys never appear there at all. --- # Give an agent its own browser > Create a separate browser profile, sign it in once by hand, and have an agent drive it through Browser Harness - so which accounts an agent acts as is a decision you made on purpose, never your everyday browser. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/agent-browser Last updated: 2026-08-07 Sooner or later you ask an agent to do something on the web that sits behind a sign-in: check an order, read a dashboard, file a form. The obvious move - let it use your browser - is the wrong one, twice over. Technically it no longer works: Chrome and Edge refuse to be remote-controlled on your everyday profile, and they encrypt its saved logins so they cannot be copied out. And even if it did work, you would not want it: a browser holds your whole life, and an agent driving it would be acting as you, everywhere, with every account you have ever stayed signed in to. DevThrottle's answer is a **browser profile**: a real browser - Chrome, Edge, Brave or Opera - running in a separate profile of its own: its own folder on disk, its own sign-ins, starting completely empty. You sign it in once, by hand, to exactly the accounts you want an agent to reach. From then on an agent on that machine can drive it - click, read, fill forms - through Browser Harness, the browser-driving tool DevThrottle installs for you. What the profile can act as is precisely what you signed in, nothing else. About ten minutes, most of it you signing in. You need the Director open, and Chrome, Edge, Brave or Opera installed on the machine. The command line steps at the end additionally need a working Gateway and a shell spawned by a DevThrottle session - that is where the environment they ride on is already set; anywhere else you supply the three variables (named in the note below) by hand. 1. **Open Browser profiles** In the Director, click **Browser profiles** - it is a pinned row in the left rail, and also a menu of its own in the menu bar. Both land on the same place: the Browser profiles tab in Settings. On a machine with no profiles yet, the tab opens on a full explanation of what a profile is, ending in a **+ Create browser profile** button. If a banner titled **Turn on browser control** is showing, click **Install Browser Harness** first. Browser Harness is the tool DevThrottle uses to drive these profiles, made by browser-use; DevThrottle installs it for you, into its own environment. Your profiles work without it - they just cannot be driven until it is installed. 2. **Name it after the identity it will hold** Click **+ Create browser profile** at the bottom of that explanation - on a machine with no profiles yet, it is the only create button on the screen. (Once at least one profile exists, the explanation gives way to a short header whose **+ New browser profile** button opens the same form.) The form asks one question that matters: *what will this profile be signed in as?* Name it after the identity - **Work**, **Personal**, a client's name - not after what you plan to do with it. "Acme Corp" tells you what an agent can reach when you point it there; "testing" tells you nothing, six weeks from now. Pick which browser underneath - only browsers actually installed on this machine are listed - and click **Create and sign in**. You are creating a brand new, empty profile, not adopting one you already use. Your everyday browser keeps running, untouched: not its tabs, not its bookmarks, not its logins. 3. **Sign it in once, by hand** A new browser window opens, and the Director asks you to sign in to whatever you want this profile to hold. This is the step that cannot be automated, on purpose: you type the credentials in the browser window yourself. DevThrottle opens the page, never types, and never sees a password. Two routes, both legitimate. Signing in to a Google account (Chrome) or a Microsoft account (Edge) carries a whole profile across in one go. Or skip that and sign in to just the individual websites this profile is for - which is how you keep a client profile to exactly that client's portal and nothing else. When you are done, click **Done - I am signed in**. The logins live in the profile's own folder, so stopping the browser or restarting the machine does not clear them - though any site can still sign the profile out on its own schedule, exactly as it could sign you out. 4. **Read the card back** The profile now has a card on the Browser profiles tab: its name, which browser it is, the account it is signed in to, and a status - **Ready** when it is running and you have confirmed a sign-in, **Needs sign-in** when it is running but no sign-in has ever been confirmed, **Stopped** when it is not running. Be precise about what that means: the card checks that the browser is up and remembers that you once said "Done" - it does not re-check whether the sites still consider the profile signed in. If a site signs it out later, the card still reads Ready; the tell is an agent reporting a login page, and the fix is opening the window and signing in again by hand. The card offers the actions that fit its state: a stopped profile offers **Start**; a running one offers **Stop**, plus **Sign in once** if it has never been signed in or **Copy attach command** if it has. Stopping a profile keeps its logins; the trash button removes the profile and permanently deletes its folder, sign-ins and all. The pinned rail row now shows your profile count, with a green dot when at least one is running - your one-glance answer to whether an agent has a browser available right now. 5. **Point an agent at it** Three things have to be true before an agent's clicks land in this profile: the profile is running, the two attach variables are set, and the thing doing the clicking is Browser Harness - the only tool that reads them. None of that happens by itself, and for an agent it must all happen in **one shell**: each command an agent runs is its own process, so a variable exported in one tool call has vanished by the next. The shape that works is a single block - start, attach, drive: **One shell, end to end: start, attach, drive** ``` cc-devthrottle browser start 'work' eval "$(cc-devthrottle browser attach 'work')" browser-harness <<'PY' new_tab("https://example.com") print(page_info()) PY ``` Line by line: `start` launches the profile's browser if it is down - attaching does *not* start anything, and with the profile stopped the address the variables point at simply refuses to answer. `attach` prints the two variables Browser Harness reads, `BU_NAME` and `BU_CDP_URL`, as shell `export` lines the `eval` applies to the rest of the block. The `browser-harness` lines then drive the profile: open a tab, read the page back - and the read-back is your proof the attach worked. The export form is made for a POSIX shell; in PowerShell run the attach command bare to see the two values, then set them yourself before invoking the harness in that same shell: **PowerShell** ``` cc-devthrottle browser attach 'work' # prints the two values $env:BU_NAME = 'work' $env:BU_CDP_URL = 'http://127.0.0.1:9310' # the port the attach output printed ``` Those variables do not redirect an agent's built-in web tools, and telling an agent a profile name does nothing on its own - the agent has to run this block itself. DevThrottle installs the `browser-harness` tool; teaching your agent to reach for it is yours to set up: put the block above, with the profile name to use, where your agent reads its standing instructions - the repository's agent instructions file (a CLAUDE.md or AGENTS.md) or a skill, whichever your agent supports. From there its browser work lands in the profile, already holding the sign-ins you gave it. The full lifecycle is on the command line too: `cc-devthrottle browser list`, `create`, `signin`, `start`, `stop`, `attach`, `rename`, `remove`. > **Warning:** A signed-in profile is a credential. An agent driving it acts as whoever is signed in there - it can do anything those accounts can do, on every site they reach. Profiles do not make that risk disappear; they make it explicit and chosen. Which identity an agent holds becomes a decision you made once, on purpose, when you signed the profile in - never something it inherits by borrowing the browser you live in. So make one profile per identity, sign each in to only what that identity needs, and give a client profile that client's accounts and nothing else. > **Note:** The `cc-devthrottle browser` commands reach the profile through your Gateway, using three environment variables: `CC_GATEWAY_URL`, `CC_GATEWAY_SESSION_KEY` and `CC_DIRECTOR_ID`. A session DevThrottle spawned carries all three already - the commands just work there. A terminal you opened yourself does not, and the commands say so rather than guessing. > **Note:** On disk, a profile is a folder of its own under DevThrottle's data directory, plus a fixed local debugging port from a range reserved for browsers (9310 to 9499). The range starts where it does deliberately: it sits well above 7879-7898, the range older Directors listened on, so an old install mid-upgrade can never collide with a browser - today's Director has no listening port of its own. The browser's port answers only on the machine itself, which is why a profile belongs to one machine and only agents on that machine can drive it - like repositories, browsers are per-machine. > **Tip:** The first sign-in is the whole setup cost, and it survives restarts of the browser, the Director and the machine - the logins sit in the profile's own folder, held for as long as the sites themselves keep the session. Set up the two or three identities you actually use once, and from then on giving an agent the web is handing it the one start-attach-drive block above. ## Next The `browser` verbs are one corner of a larger command line surface - [Driving DevThrottle from a script](https://devthrottle.com/docs/tutorials/scripting) walks the rest of it, from reading your fleet as text to putting commands on a schedule. --- # Work that runs without you > Schedule an agent to run every night or every Monday morning through the Gateway - pick the machine, say when in plain English, and run it once by hand before you trust it. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/scheduled-work Last updated: 2026-08-03 Some work does not need you present. Checking dependencies, sweeping issues, running a report first thing Monday - the kind of job you always mean to do and never quite do. DevThrottle can start an agent on a schedule and let it get on with it. About ten minutes. You need a Gateway and at least one machine with a Director running, because a scheduled job has to have somewhere to run. 1. **Open Schedule and start a new job** In the Cockpit, choose **Schedule** in the left rail, then **New cron job**. Give it a name you will recognise in a list months from now. The list will also show what the job runs, where, and on what schedule - but the name is the first thing you will scan for when you come back wondering what this is. 2. **Choose where it runs** Pick the machine under **Run on**, and give the repository path the session should open in. Both matter: a scheduled job is a real session on a real machine, not something that happens in the cloud. > **Warning:** If the machine list is empty, no machine is currently known to this Gateway. Entries leave the list when a Director shuts down cleanly or has been silent for a day, so an empty list is about now - it does not mean no machine ever reported. Start DevThrottle on the machine you want the work to happen on, then come back. 3. **Say when** Switch **Schedule** to **Recurring** and enter a five-field cron expression. `0 2 * * 1-5` means two in the morning, Monday to Friday. You do not have to trust yourself with that syntax. Underneath the box, the page reads your expression back in plain English - "At 2:00 AM, Monday through Friday". If that sentence is not what you meant, the expression is wrong. Set the time zone too, or the job will fire on a schedule that is not yours. 4. **Write the instruction as if you will not be there** The prompt is what the agent wakes up to, and nobody will be around to clarify it. Say what to do, and say what to do when there is nothing to do - otherwise an agent with no work to report will invent some. Then choose whether it tells you how the launch went. The notification reports whether a session *started*, not what the agent went on to do. **Only on failure** - tell me only when a run failed to start - is the setting most people actually want; a nightly job that notifies on every successful start becomes noise you stop reading within a week. 5. **Create it, then run it once by hand** Click **Create job**. It appears in the list with its target, its schedule in plain English, and when it will next fire. ![The Cockpit Schedule page listing one job called Nightly dependency sweep, targeting the machine SOREN_NORTH and the demo-app repository, scheduled at 2:00 AM Monday through Friday, next run in 3 hours, status enabled, with a Run now action](https://devthrottle.com/docs/screenshots/cockpit/schedule.png) Now press **Run now**. Do not wait until two in the morning to find out that the path was wrong or the instruction was ambiguous. The Schedule page tells you the session started; what the agent actually did lives in the session itself. Open the new session in the rail, read what it did, and fix the prompt while you still remember what you meant. > **Note:** The schedule belongs to your Gateway, not to Windows Task Scheduler and not to the machine you created it from. You can create a job from your phone for any machine the Gateway currently knows - the picker offers exactly that list, and there is no way to type a machine name in free-hand. And when the time comes the machine has to be awake. If it is off, the Gateway asks that machine's Launcher to start a Director, the launch fails, and the run is recorded as not started; a recurring job then simply waits for its next scheduled time. Nothing runs when the machine wakes up. > **Tip:** Start with one job, on a weekday schedule, that only notifies on failure. Scheduled work goes wrong quietly, and one job you trust is worth more than six you have stopped reading. ## Next For every field, the REST interface, exactly how firing works and where jobs are stored, see [Scheduled runs](https://devthrottle.com/docs/gateway/cron). To create jobs from a script instead, see [Driving DevThrottle from a script](https://devthrottle.com/docs/tutorials/scripting). To check what your overnight jobs actually did, see [What did I actually get done this week?](https://devthrottle.com/docs/tutorials/weekly-review) --- # Using more than one machine > One machine runs out before you do. Add a second computer to the same fleet by enrolling it with the Gateway you already have, then give it its own clone of the code it will work on. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/many-machines Last updated: 2026-09-06 One machine runs out before you do. A long build blocks everything else, or you want agents working overnight on a spare desktop while your laptop travels with you. DevThrottle was built for a fleet rather than a computer, and adding the second machine is the point where that starts to show. This is a walk-through of the idea and the order to do it in. About twenty minutes, most of it the installer running on the second machine. You need DevThrottle working on one machine first, with a Gateway connected. 1. **Understand what the Gateway shares, and what each machine needs of its own** The shared part is the **Gateway**, and it is worth knowing what it holds before you add a second computer to it. It knows what every session in your fleet is doing, which is what makes one roster out of two machines. It holds what belongs to your *account* rather than to a desk - your model choices, your voice settings, your snooze lengths, your language, and the dictionary of your own words. It keeps your conversation history, which is how you can read back a session from a machine you are not sitting at, and how a supervising session can follow one it is driving. And it is what your phone talks to; the phone never talks to a Director. What is not the Gateway's is each machine's own arrangements - the Director itself, and the settings that describe that computer rather than you: its network addressing, whether it starts on boot, its diagnostics. The new machine keeps its own. So the work of adding a machine is telling a second computer to report to the same Gateway. The one copying job in the story is yours, and it comes later: any repository you want the new machine to work on needs its own clone there, exactly as if you were setting that machine up by hand. 2. **Install on the second machine and enroll it** Install DevThrottle there as you did the first time. The joining happens on the setup wizard's gateway step, and what you do there depends on the Gateway your first machine uses. On the hosted gateway - the recommended default - you simply **sign in with the same account**: the wizard enrolls the machine, and the moment it shows Connected, your two machines are one fleet. Running your own gateway? Take **Self-hosted gateway** instead - it scans for gateways it can reach and lets you type an address when the scan cannot see yours. The exact steps are on [Running more than one machine](https://devthrottle.com/docs/gateway/machines). On a normal install nothing on your machine listens - the Director and the Launcher only dial out to the Gateway. The one exception is a self-hosted Gateway: the machine you install it on listens on a port (7878) and must be reachable at its address. The hosted Gateway involves no listener of yours at all. 3. **Check the fleet map** Open the Cockpit and go to the fleet map. The new machine appears as its own node with its own sessions hanging off it. If it does not appear, do not reach for the router first: enrollment can fail at the sign-in - the wizard says so plainly when it does, and keeps your options - and a machine that enrolled but has no Director running shows nothing to the fleet yet. [Running more than one machine](https://devthrottle.com/docs/gateway/machines) walks through what to check, in order. 4. **Start something on the far machine, from where you are** From the fleet map, start a session on the other machine and give it work. You do not need to be sitting at it. That is the whole payoff: the second computer becomes somewhere you send work rather than somewhere you go. > **Note:** Each machine works on its own clone of your code. Two machines are not two sessions sharing one checkout - if you want several sessions in one repository on one machine, that is a different problem, solved by [worktrees](https://devthrottle.com/docs/tutorials/repositories-and-worktrees). > **Tip:** A machine that goes to sleep does not fall out of your fleet - it stays on the map, dimmed and dated, its sessions still listed. What it cannot do is accept work until it wakes. So if you want overnight work, the spare desktop has to stay awake - which is worth settling before you rely on it. ## Next For the setup detail see [Running more than one machine](https://devthrottle.com/docs/gateway/machines), and [Connecting machines without opening a port](https://devthrottle.com/docs/gateway/portless) for the listener story in full - on a normal install nothing on your machine listens, and only a self-hosted Gateway's own machine does. To make the far machine work while you sleep, see [Work that runs without you](https://devthrottle.com/docs/tutorials/scheduled-work). --- # Driving DevThrottle from a script > The command line, for when you want DevThrottle to act while nobody is watching - read your fleet, message a session, and put it on a schedule. Part of the DevThrottle documentation, section "Tutorials". Canonical HTML version: https://devthrottle.com/docs/tutorials/scripting Last updated: 2026-08-07 Everything the Director does, something else can do too. There is a command line, and it serves a person typing and a program asking equally well - the fleet commands go through your Gateway. This is what you reach for when you want DevThrottle to act while nobody is watching. Fifteen minutes, and you should be comfortable on a command line. You need DevThrottle running with a Gateway - and run the commands from inside a DevThrottle session, the easiest place being any agent you already have open. A session's environment carries the Gateway address and the session's own key (`CC_GATEWAY_URL` and `CC_GATEWAY_SESSION_KEY`); in a plain terminal without that pair, the fleet commands stop and tell you they only work inside a session. Export the pair if you want them from your own terminal. 1. **See your fleet from a terminal** The command line is installed with DevThrottle - there is nothing extra to fetch. Start with the one that just reads: **What is running right now** ``` cc-devthrottle session list ``` That is the same fleet the Director shows you, as text. If this works, everything else in this tutorial will. 2. **Check your own setup** **Is everything wired up** ``` cc-devthrottle setup status ``` Useful as the first line of any script you write, and the first thing to run when a script that used to work stops working. 3. **Send a message to a session** An agent can be told something without you opening its window: **Say something to a running session** ``` cc-devthrottle message send "the build is red, look at that first" ``` > **Warning:** This interrupts the agent you send it to, exactly as if you had typed it. That is fine when you mean it and disruptive when you did not - be careful sending to more than one at a time. 4. **Let a program ask** The fleet commands above work unchanged inside a script, because of how they are wired: a fleet call goes to your Gateway, carrying the calling session's own key. Not every command needs that - `setup status` and the catalog below are local and run in any terminal - but everything that reads or drives the fleet does. There is no local address to discover and no port on the Director - it does not have one, by design. A program that should not guess what it may run can ask for the whole catalog in JSON: **Every action, machine-readable** ``` cc-devthrottle actions --json ``` Each entry names the command, its arguments, and whether it changes anything (`mutatesState`), so a script can stick to the reads. How calls are authorized - the session key, and what it may and may not do - is on [the Control API reference](https://devthrottle.com/docs/gateway/control-api), which stays the single source of truth for that. 5. **Put it on a schedule** Once a script does something useful, the thing you usually want is for it to happen without you. That is the Gateway's job rather than your operating system's, and creating a schedule is one command - name it, say which machine and folder the session runs in, when, and what it should do: **Every weekday at 06:00, run the tests** ``` cc-devthrottle schedule create --name "nightly tests" --machine YOUR-PC --repo D:/repos/my-project --cron "0 6 * * 1-5" --tz "Europe/Copenhagen" --seed "Run the test suite and fix what is red." ``` **What is scheduled now** ``` cc-devthrottle schedule list ``` Use your own machine name (`cc-devthrottle session whoami` prints it) and your own time zone. For a one-off instead of a recurring job, swap `--cron` for `--at` with a local timestamp. For doing the same from a screen, and what every field means, see [Work that runs without you](https://devthrottle.com/docs/tutorials/scheduled-work). > **Note:** There is a separate, larger API for talking to models rather than to your fleet - that is [the DevThrottle API](https://devthrottle.com/docs/api/overview), and it is a different thing from the fleet commands used above. Fleet control goes through your Gateway and is about your sessions; the model API is a hosted service and is billed. ## Next For every shipped command and what each one does, see [the command reference](https://devthrottle.com/docs/cli/reference). For how fleet calls are authorized, [the Control API](https://devthrottle.com/docs/gateway/control-api). For the model API, [the API overview](https://devthrottle.com/docs/api/overview). --- # The Director > The desktop app that puts every coding agent in one place and tells you which one needs you - a tour of the window. Part of the DevThrottle documentation, section "The Director". Canonical HTML version: https://devthrottle.com/docs/director/overview Last updated: 2026-09-06 The Director is the DevThrottle desktop app - the Director you keep open while your coding agents work. Every agent session is a card in the left sidebar; the selected session fills the rest of the window with a full terminal, so you are never more than one click from the raw agent. This page is a tour of the window; the rest of the section goes deeper on [cards and states](https://devthrottle.com/docs/director/sessions), [steering](https://devthrottle.com/docs/director/steering), [source control](https://devthrottle.com/docs/director/source-control), and [settings](https://devthrottle.com/docs/director/settings). ## The layout The window has three working areas: - **The session sidebar** on the left. One card per agent session, each with a colored status square that tells you at a glance whether that agent is working or waiting on you. A counter at the top of the rail shows how many sessions need you right now. Cards can be dragged into your own order and collapsed to a slim strip of status dots when you want the space. - **The session pane** in the center. The selected session's terminal, exactly as the agent sees it, with two tabs above it: **Terminal** and **Source Control**. Source Control appears only when the session's folder is a git repository. A right panel holds **Screenshots** (images you send from your phone) and the **Queue** of prompts waiting their turn. - **The prompt bar** at the bottom. Type a message and send it into the terminal, queue it for later, or dictate it with the Speak button. The [steering page](https://devthrottle.com/docs/director/steering) covers every control. ## The toolbar Across the top: **New Session** (Ctrl+N) starts an agent; **Cockpit** opens the same fleet in your browser; **Settings** opens the [Director settings](https://devthrottle.com/docs/director/settings). The status rail at the bottom of the sidebar shows the health of the Gateway connection - one chip that also tells you whether you are signed in - the bundled tools, and auto-update. ## A view, backed by a service The Director runs your agent sessions, and the [Gateway](https://devthrottle.com/docs/gateway/overview) keeps the whole setup reachable. By default that is DevThrottle's hosted Gateway - your account joins it, and there is nothing to run yourself - though you can run your own instead. Either way it serves the Cockpit to your browser and phone, runs [scheduled agent runs](https://devthrottle.com/docs/gateway/cron), and can have a Director started on your machine when a schedule fires. You watch the Director; the plumbing stays out of sight. > **Note:** Closing your browser or putting your phone in your pocket never stops an agent - those are just views. The agents themselves run inside the Director on your machine. See [keeping agents running](https://devthrottle.com/docs/gateway/lifecycle) for exactly what keeps going when. ## Where to go next - [Session cards and states](https://devthrottle.com/docs/director/sessions) - read the Director at a glance. - [Starting and steering agents](https://devthrottle.com/docs/director/steering) - the New Session dialog, the prompt bar, and the queue. - [Start your first session](https://devthrottle.com/docs/start/first-session) - if you have not started one yet. --- # Session cards and states > How agents appear in the Director and how to read a card at a glance - the status square colors, activity labels, timers, and badges. Part of the DevThrottle documentation, section "The Director". Canonical HTML version: https://devthrottle.com/docs/director/sessions Last updated: 2026-09-16 Every session is a card in the Director sidebar, and the card is designed to answer one question without a click: does this session need me right now? Two signals do the work - a colored **status square** on the left edge of the card, and an **activity label** in plain words underneath the name. ## What is on a card - **Status square** - the at-a-glance color (below). It is also the drag handle for reordering cards. - **Session number** - a three-digit badge, handy when you drive sessions by voice or from the phone ("answer 214"). - **Name** - the custom name you gave the session, or the repository folder name. - **Agent badge** - a colored pill naming the agent (for example Claude Code). - **Activity label** - what the session is doing, in words. The full set is listed below. - **Waiting timer** - when a session needs you, the card shows how long it has been waiting. This is the number that used to be invisible - the forty minutes an agent sat blocked while you were in another window. - **Changes badge** - an amber "N chg" count of uncommitted file changes in the session's repository. See [source control](https://devthrottle.com/docs/director/source-control). - **Queue badge** - how many prompts are queued for this session; click it to preview them. ## The status square colors The square uses one color scale everywhere - the Director, the browser Cockpit, and your phone all show the same color for the same session. In the Cockpit and on the phone, a **What do the colours mean?** link on the session list opens the same meanings as a short legend, read from the Gateway. - **Blue - working.** The agent is busy (or still starting). Leave it alone. Nothing outranks working: a session that is working is blue, whatever else is going on. - **Red - needs you.** The agent stopped and is waiting for an answer, a permission decision, or its next task. These are the cards to click. When the Wingman has read the stop, the label is its own one-line summary of what is being asked. - **Green - ready.** A brand-new session at its prompt that has not taken a turn yet, nothing asked of you. - **Cyan - done.** The session stopped and the Wingman judged that it finished: the work is done, or it is only reporting something and asks you nothing. The label leads with **Done** or **Report**. The card stays in view but is not counted as needing you. A snooze that ends with nothing new also comes back cyan, labelled **Snooze ended, nothing new**. - **Yellow - being read for you.** The Wingman or the Director is reading the finished turn, or a voice-mode session's spoken summary is not ready yet. The card turns red once there is something for you to act on - including when voice mode gives up on the summary. - **Purple - carrying on.** The session stopped, but the Wingman judged it will continue on its own - it is waiting on a build, a timer, or sessions it started. If it has not continued by the time it said it would, it turns red and says so. - **Orange - transcribing.** A dictated message is being turned into text and sent in. - **Slate - answering to somebody else.** A session that another live session is driving recedes to slate when it stops. Its "needs you" is muted so it never nags you - the session driving it deals with it. If that session exits, the muting ends and the stopped session asks for you again. (The Cockpit's fleet map still labels this dot **Sub-agent** in its legend.) - **Dark red - crashed.** The agent process ended unexpectedly. - **Gray - snoozed, exited, or indeterminate.** One gray, deliberately, for all three: read the label under the name to tell a session you snoozed (Snoozed) from one whose agent process has ended (Exited) from one whose state cannot be determined (Idle). > **Note:** Cyan, purple, and the yellow for the Wingman reading a stop appear only when the Wingman's verdicts are switched on for your account, which they are not by default. With them off, those sessions show red instead. Hover the square for the reason behind the color - the tooltip spells out why the session is in the state it is in. ## The activity labels The label under the name is the session's state in words: - **Working** - mid-task, producing output (also while the agent process is still starting). - **Needs you** - stopped and waiting for your answer, a permission decision, or its next task. When the Wingman has read the stop, its own words for what is being asked take this label's place. - **Ready** - a fresh session that has not taken a turn yet. - **Snoozed** - either you set the session aside (see below), or another live session is driving it and it has stopped. The role badge on the card says which. A session that has ended still reads **Exited** or **Crashed** - a dead session never hides behind Snoozed. - **Done** and **Report** - the Wingman judged the stop finished; the rest of the label is its one-line summary. - **Carrying on** - the Wingman judged the session will continue by itself. When the Wingman wrote a line of its own, that line is shown instead. - **Snooze ended, nothing new** - a snooze ran out and nothing happened while it ran. - **Transcribing** - a dictated message is being turned into text. A dictation sent from the phone first reads **Uploading from phone**. - **Wingman reading** - the Wingman is reading the finished turn for you. - **Preparing voice** - a voice-mode session's spoken summary is being generated. Once the wait passes a minute the card carries its age, as **Preparing voice (4m)**. - **Exited** - the agent process has ended. - **Crashed** - the agent process ended unexpectedly. - **Idle** - the fallback when the session's state cannot be determined. ### When the voice does not come A voice-mode session that is waiting on you holds yellow while its narration is on the way, and the label says what is actually happening rather than promising forever: - **Voice did not arrive** - three minutes passed with no narration, so the card stops saying it is on the way and says so, with the wait beside it (**Voice did not arrive after 5m**). Once voice mode has given up, the card stops holding yellow and turns red with those words, so the session asks for you instead of waiting on audio that is not coming. You can read the turn instead. - **Nothing to read aloud** - the session is waiting for you on a prompt or a menu rather than on a text answer, so there is genuinely nothing to narrate. - **No narration yet** - no spoken summary for this turn has been made yet. - **Voice service down** - the speech service is unavailable. Nothing is wrong with your session. - **Voice needs credit** and **Monthly limit reached** - the account condition behind the missing audio, so you can fix it instead of waiting. - **Update DevThrottle** - the machine that owns the session is running a build too old to send its conversation up, so there is nothing stored to read aloud. > **Note:** These words are decided once, by the Gateway, and every screen renders them verbatim - the Director, the Cockpit and your phone always say the same thing about the same session. See [voice on the phone](https://devthrottle.com/docs/mobile/voice). ## Order and snooze Cards stay in the order you put them - drag the status square to rearrange. And when a session should stop competing for your attention without being closed, **snooze** it from the card's menu: **Snooze** uses your default length, **Snooze for** picks a length on the spot, and **Unsnooze** brings it back. A snoozed session shows the gray square and the **Snoozed** label, with the time remaining beside it, and the Director stops counting it as needing you. When a snooze runs out on its own, the card carries a **Snooze ended** badge if the session is still waiting. > **Tip:** Treat red as an inbox: the header counts the sessions that need you, and working that number down answers everything that is asking for an answer. > **Warning:** Clearing the count is not a health check. A crashed session folds to dark red rather than red, so it counts as active and never enters that number, and a session the Gateway has not yet reported on is deliberately treated as not needing you. An empty header therefore means no session is currently reported as needing you - not that every agent is busy or done. Scan the squares before you read the Director as quiet. ## Where to go next - [Starting and steering agents](https://devthrottle.com/docs/director/steering) - act on the card that needs you. - [Source control and history](https://devthrottle.com/docs/director/source-control) - what the changes badge is counting. --- # Session roles and missions > Every session carries a role - Standalone by default, plus Architect, Manager, and Worker - and related sessions attach to a named mission, so a busy fleet reads at a glance: who is solo, who plans, who supervises, and who does the work. Part of the DevThrottle documentation, section "The Director". Canonical HTML version: https://devthrottle.com/docs/director/roles Last updated: 2026-09-06 Once you have more than a handful of agents in the Director, the hard question stops being "what is each one doing" and becomes "who is in charge of what." Session roles answer that at a glance. Every session on [the Director](https://devthrottle.com/docs/director/overview) carries a role - **Standalone**, **Architect**, **Manager**, or **Worker** - and related sessions can be attached to a named **mission**. You can read a busy fleet in one sweep: which sessions are solo, which one plans, which supervise, and which are heads-down doing the work. ## The five roles A role describes a session's place in a piece of work, not a different kind of agent. The same coding agent can be a Worker on one task and a Manager on another. The method has five roles; the first four are what DevThrottle records today, and they are the values the role flag accepts. - **Standalone.** The default. A solo session that is not wired to any other - it is just working on its own, facing you. Every undeclared session starts here, and most of a casual fleet stays this way; a session spawned with a declared role - an Architect, or an explicit Worker - wears that role from birth instead. - **Architect.** The session that settles the design and directs the rest. This is the one role DevThrottle can never work out for you - nothing in how sessions are wired says which one is the planner - so an Architect only exists because you declared one. - **Manager.** The badge an undeclared session earns by supervising: it shows as a Manager while any live supervised session sits under it - whatever role that session itself wears - and loses the badge when the last one ends. A session that itself answers to a live Supervisor resolves as a Worker first, so in a chain the middle session wears the W, not the M. - **Worker.** A session running work under a live supervisor. If a session is doing a job that a different session set up and is still watching, it shows as a Worker. That is the derived case; a declared Worker needs no Supervisor at all and stays a Worker until the declaration is cleared. - **Reviewer.** A different session from the one that wrote the work, checking it before it lands. The role is agreed but not yet recordable: the role flag does not accept it, and no badge shows for it - today a Reviewer is staffed by a workflow, such as the one shipped in the catalog as standalone-with-review. ## Roles are worked out for you You do not tag every session by hand. An undeclared session starts as Standalone, and its role changes as the work connects up: one running work under a live Supervisor shows as a Worker, and an undeclared session with a live supervised session under it shows as a Manager, for as long as that is true. You can also declare any of the four recordable roles explicitly - at spawn with `cc-devthrottle session spawn --role`, or later with `cc-devthrottle session role` - and a declared role wins from birth, before any wiring is read: a declared Architect wears its badge without supervising anyone, and a declared Worker is a Worker with no live Supervisor, or none at all. The declaration sticks until you clear it by declaring `none`. That is why an Architect that hands work down stays an Architect rather than turning into a Manager. Architect is the one role that must be declared, because it can never be derived. Two different edges connect sessions, and only one of them drives any of this. The **Supervisor** is the live relationship - it is what roles and colours are computed from, and it changes how the supervised session is displayed. The **Parent** is the historical fact of who started a session, and it changes nothing on screen. The two usually coincide, and they diverge when a session deliberately starts a human-facing peer: the peer has a Parent but no Supervisor. ## A Worker never nags you The role changes what the colours mean. A **Standalone** or a **Manager** that needs input turns red - those are the two seats that face you, so their red is your business. A Worker's red is its Supervisor's business - and the Supervisor need not be a Manager; a Worker can answer directly to an Architect. While the Supervisor is alive, a waiting Worker recedes to a quiet slate instead of red (the Cockpit's fleet-map legend calls this colour **Sub-agent**), reads **Snoozed**, and drops out of the "needs you" count. Its Supervisor deals with it. A declared **Architect** is quiet the same way, by design. An Architect that stops is not a session shouting for attention - you pull an Architect into a conversation when you want its judgement, rather than being pushed at by it. So an Architect recedes to slate and reads Snoozed exactly as a Worker does. The third quiet kind is a session a [schedule](https://devthrottle.com/docs/gateway/cron) started: no person made that call, so there is nobody on the rail for it to be waiting on. It recedes to slate and reads Snoozed the same way. If you run scheduled work, this is why those sessions never turn red at you. There is an escape hatch, and one deliberate exception to it. A Worker whose role was worked out from the wiring stops being a Worker when its supervising session dies, so anything it needs from a human turns red again rather than waiting silently on a Supervisor that will never answer. A Worker you declared explicitly is different: the declaration is sticky, so it keeps the role - and the quiet slate - even after its Supervisor exits, until you clear the role. On the Director's session rail, the role shows as a single-letter badge - M for Manager, W for Worker, A for Architect, with the full name in the tooltip. Standalone shows no badge, so the common case stays quiet. > **Note:** Roles are about how sessions relate to each other, not about which coding agent or model a session uses. DevThrottle never changes the agents themselves - see [supported coding agents](https://devthrottle.com/docs/agents/supported). ## Missions: a name for related work When several sessions serve one effort, create a mission. A mission is the undertaking itself - why the work exists, who is on it, and the tasks it breaks into - not a box that holds sessions. Sessions are attached to it separately: at spawn with `--mission`, or by inheritance, since a session spawned under a Supervisor joins that Supervisor's mission unless told otherwise. With the attachment in place, a whole line of work reads as one thing on the fleet map instead of a scatter of unrelated cards. ## Why this matters The point of DevThrottle is to run many agents without losing the thread. Roles and missions make the fleet legible: instead of a wall of identical sessions, you see a structure - the Architect that is steering, the Managers watching their Workers, and the missions that work belongs to. That is what lets you scale from one agent to a whole fleet and still know, at a glance, who needs you. ## Where to go next Roles sit on top of the session basics. If you have not yet, read [session cards and states](https://devthrottle.com/docs/director/sessions) for how to read a single card, and [starting and steering agents](https://devthrottle.com/docs/director/steering) for how work gets going in the first place. To put roles to work on a real job, follow the [roles tutorial](https://devthrottle.com/docs/tutorials/roles). --- # Starting and steering agents > Start new agent sessions and steer the ones that need you - the New Session dialog, the prompt bar, the queue, and Stop, Interrupt, Compact, and Clear context. Part of the DevThrottle documentation, section "The Director". Canonical HTML version: https://devthrottle.com/docs/director/steering Last updated: 2026-09-06 This page covers the two verbs of the Director: starting an agent session and steering it while it runs - answering questions, queueing the next task, and stopping it when it goes down the wrong path. ## Start a new session 1. **Open the New Session dialog** Click **New Session** in the toolbar (or press Ctrl+N). The dialog also has tabs for **Named Sessions** and **Resume Session** - more on those below. 2. **Pick the agent** The agents you have configured appear as a row of choices, with the first one preselected. Claude Code and Pi ship with verified drivers and are always available; you manage the list under [Settings - Agents](https://devthrottle.com/docs/director/settings). Choosing **Custom CLI** lets you point the session at any command-line tool by giving its command and arguments. 3. **Pick the repository** Choose the folder the agent will work in - the dialog lists the repositories you have used, sortable by name, path, or last used, and a **Browse** button picks any folder. The agent edits real files in that folder, so for a first run start somewhere low-stakes. 4. **Decide about permission prompts** **Run without approval prompts** is checked by default: the agent works without stopping to ask before each tool action. Uncheck it if you want to approve actions as they happen - the session's card turns red and reads **Needs you** each time the agent wants a decision. The checkbox names the exact flag it will pass, in brackets after the label, so it never promises something the launch will not do - it reads **Run without approval prompts (--permission-mode auto)** for Claude Code, and a different flag for each other agent that has one. Agents with no such option - pi, OpenCode, and a Custom CLI entry - get the checkbox disabled, labelled **(this agent has no such option)** rather than a promise it cannot keep. 5. **Start** A new card appears in the Director and the agent launches in its terminal. Give it the first task from the prompt bar - or set the task up front with a named session. ## Named sessions and resuming **Named Sessions** are saved presets - a repository plus an agent under a name you choose, launched with one click. Save any running session as a named session from its card menu. **Resume Session** lists your past Claude Code conversations with a summary, message count, and how long ago they ran. ## The prompt bar ![The prompt bar below the terminal: the message box with the Expand button in its corner, and Send, Speak and Queue stacked down its right-hand side, the Queue button red and reading Queue (3)](https://devthrottle.com/docs/screenshots/director/prompt-bar.png) - **Send** (Ctrl+Enter) - type a message and send it into the terminal. - **Queue** (Ctrl+Shift+Enter) - add the message to the session's queue instead of interrupting; it waits there until you send it. - **Speak** (Ctrl+H) - dictate instead of typing. See [voice](https://devthrottle.com/docs/voice/overview). - **Expand** - open a large editor for long prompts, with image preview for screenshots you attach. > **Tip:** Queueing is the habit that makes multiple agents work. While an agent is busy, line up its next two or three tasks with Ctrl+Shift+Enter - the **Queue** panel on the right shows the line, and you can reorder, edit, or delete items before you send them. Nothing leaves the queue on its own, so when you come back to an agent that has stopped, the next instruction is already written and waiting. ## Stop, interrupt, compact, and clear The action bar - the row of buttons at the top of the prompt bar, under the terminal - gives you graduated brakes: - **Stop** - the agent's own soft cancel (Esc). Ends the current turn; the conversation continues. - **Interrupt** - a hard interrupt (Ctrl+C), stronger than Stop, for when the agent will not let go. - **Compact** - summarize the conversation so far, freeing room in the context window. The session keeps what it has learned. Asks for confirmation first, and can take a minute or two. - **Clear context** - reset the conversation in place while the process keeps running - a fresh start without a new session. Asks for confirmation first; it cannot be undone. - **History** - open the agent's in-terminal history picker to jump back to an earlier point. The buttons are drawn from what each session's agent can actually do, so the bar differs by agent: a verb the agent's CLI does not support is simply absent. Claude Code shows all five; pi has Stop but no Interrupt, because Ctrl+C means something else entirely in pi; Cursor and Copilot have only Interrupt; History is Claude Code's alone. For agents that can report their context usage - Claude Code, Codex and pi - the action bar also shows a context-window gauge - how full the agent's working memory is - which is your cue to compact, clear context, or wrap up the task. ## Answering an agent When a card turns red, click it, read the question in the terminal, and answer in the prompt bar. A card waiting on a permission decision reads **Needs you** too - the Director deliberately uses one word for both, because from where you are sitting they are the same job: a session has stopped and only you can restart it. Read the terminal to see which it is, then approve, deny, or answer right there. Then get out of the way; the card goes blue and you go back to whatever you were doing. > **Note:** You do not have to be at the desktop to answer. The same sessions can be driven from the [Cockpit](https://devthrottle.com/docs/cockpit/overview) in a browser and from your [phone](https://devthrottle.com/docs/mobile/overview) - including by voice. ## The card menu The "..." menu on each card: **Rename**; **Snooze** (or **Unsnooze**), with a **Snooze for** submenu offering other lengths once this desktop has learned them; **Open in Explorer** and **Open in VS Code**; **Copy Handover Info**, **Save as named session**, and **Relink Session**; and **Close Session**. > **Warning:** Closing a session ends the agent process. Your files keep every change the agent made, but anything the agent was mid-way through stops where it stands. --- # The embedded terminal > Every session carries a real live terminal - watch the agent work, use the prompt bar with Send, Queue, and Speak, and know the two buttons that fix a confused display. Part of the DevThrottle documentation, section "The Director". Canonical HTML version: https://devthrottle.com/docs/director/terminal Last updated: 2026-07-13 Every session in the Director carries a real terminal - the same one the coding agent is running in. The **Terminal** tab shows it live: you watch the agent work, scroll back through what it did, and, when you want to, type straight into it. Next to it sits the [Source Control](https://devthrottle.com/docs/director/source-control) tab. ## The prompt bar Below the terminal is the prompt bar - a separate box that lives outside the terminal, so you can compose slowly (or dictate) without your keystrokes going anywhere until you decide: - **Send** (Ctrl+Enter) - send the message into the terminal. - **Queue** (Ctrl+Shift+Enter) - park it in the [queue](https://devthrottle.com/docs/director/steering) instead of sending it now; it waits there until you send it. - **Speak** (Ctrl+H) - dictate instead of typing; see [Voice](https://devthrottle.com/docs/voice/overview). - An **Expand** button opens a larger editor - handy for long prompts, with image previews for anything you dragged in. - Typing `/` pops up slash-command autocomplete with descriptions. Because the prompt bar is its own surface, it can also be driven remotely - the same box answers from your [browser](https://devthrottle.com/docs/cockpit/overview) and [phone](https://devthrottle.com/docs/mobile/overview). ## Working inside the terminal - Select text by dragging; **Ctrl+C** copies when text is selected (and sends the usual interrupt when nothing is). **Ctrl+Shift+C** copies the selection and never interrupts - with nothing selected it does nothing. **Ctrl+V** pastes, and right-click offers Paste. - Links the agent prints are detected - click one and a small menu offers open or copy. - Arrows, function keys, and the control strokes a CLI leans on - **Ctrl+C**, **Ctrl+D**, **Ctrl+Z** and **Ctrl+L** - pass straight through. ## When the display needs a nudge Terminals are stateful, and after a lot of fast output the picture can occasionally drift from reality. **Reset View** above the terminal (**Reset Terminal View** in the View menu) rebuilds the display from the underlying buffer. **Capture** (Ctrl+Shift+F12) writes a diagnostic snapshot to a file - useful when reporting a display problem. > **Tip:** You rarely need to type in the terminal itself. The prompt bar is the intended way to talk to an agent - the terminal is primarily your window into what it is doing. > **Note:** Sessions live inside the Director, so closing the window ends them - and do not count on a warning. The confirmation dialog appears only for sessions that are actively working or waiting for your answer; one that is starting up, idle, or waiting on a permission closes without it. Minimise the window instead; see [keeping agents running](https://devthrottle.com/docs/gateway/lifecycle). --- # Source control and history > Review what your agents changed and read back the conversation that produced it - the changes badge, the Source Control tab, and conversation history. Part of the DevThrottle documentation, section "The Director". Canonical HTML version: https://devthrottle.com/docs/director/source-control Last updated: 2026-09-06 Agents edit real files in a real repository, so the Director keeps the answer to "what did it actually change?" one tab away. The **Source Control** tab shows the state of the session's git repository - it has two pages, **Changes** and **Worktrees**; for the conversation that produced it, the **History** button and the Cockpit's Chat tab are covered below. ## The changes badge A session card can carry an amber **"N chg"** badge - a count of uncommitted changes in that session's working tree, staged and unstaged together, so a file staged and then edited again is counted in both. The badge is absent, never "0 chg", when the tree is clean or the count is unknown - absence is not proof of a clean tree. And the number is the last count a probe produced: when a later probe fails or the folder goes missing, the Director keeps that number rather than reporting zero, so it can be stale. It is still the earliest honest signal of progress: an agent that claims to be done with no changes reported, or one that has quietly touched forty files, both deserve a look before you move on. ## The Source Control tab Select a session and open **Source Control**. A rail down the left side holds the tab's two pages - **Changes**, which opens first, and **Worktrees**, which carries a red count when a repository has worktrees you can clear away. ### Changes At the top, the branch bar shows the current branch and how it relates to the rest of the world: a green **^N** badge counting commits not yet pushed, an orange **vN** for commits not yet pulled, a blue badge naming the main branch when yours has fallen behind the main line, and a small "no upstream" note when the branch has no upstream yet. Below it, the **Changes** file tree lists what the agent has modified, with a count in its header; a second tree, **Staged Changes**, appears above it only while something is staged. When the working tree is clean it says so: "No changes detected". Every file in either tree carries one letter for what happened to it: **M** modified, **A** added, **D** deleted, **R** renamed, **C** copied, and **U** untracked - a new file git is not following yet. R and C are drawn in the same blue, so read the letter rather than the colour when it matters which of the two it is. Right-click a file for **View File**, **Copy Path**, **Copy Relative Path** and **Add to .gitignore**. The last one is the polite way to silence a generated file that keeps turning up in reviews where it does not belong. ### Worktrees Running several agents at once tends to leave a trail of git worktrees behind, and after a week nobody can remember which ones are finished. The **Worktrees** page scans the session's repository and sorts every linked worktree into three groups, each with its own count and a plain sentence saying what the group means: - **Safe to reap** - the work is already on origin/main and the tree is clean, so nothing is lost by removing it. - **In use by an open session** - the work has landed, but a session is still open in the folder. These are held back until you close it and are never removed while in use. - **Needs attention** - the worktree carries unmerged commits or uncommitted content, so a person has to decide. Never removed for you. **Remove orphaned worktrees** appears only when there is at least one in the safe group, and it shows you exactly what it is about to remove before it acts. **Refresh** re-scans (it runs a fetch with prune first, so the merged-or-not verdict is current), and **Copy report** puts the whole listing on your clipboard as text - handy for pasting into an agent and asking it to deal with what needs attention. A repository with no linked worktrees says so. > **Note:** The repository screen has a worktrees tab of its own, covered on [repositories and worktrees](https://devthrottle.com/docs/director/repositories). That one is about a repository you are managing; this one is about the repository the selected session is working in. > **Note:** Line-by-line differences are not on this tab - they are on the repository screen's **Changes** tab, in [repositories and worktrees](https://devthrottle.com/docs/director/repositories) - and two things behave differently there for an untracked file, both because git has no earlier version of it to compare against. Its difference is its whole content, every line rendered as added under a hunk header ending *(new file)*, which is the reading it deserves: all of it is new, so none of it has been reviewed. And **Discard changes** does not appear on it at all - that button shows only on a tracked file with unstaged edits, because those are the only changes git can put back. If an untracked file is noise, gitignore it; if it is wrong, delete the file itself. > **Note:** The Source Control tab is a review surface, not a git client. When you are happy with the changes, commit them the way you always do - ask the agent to commit, or use your own git tools. **Open in VS Code** and **Open in Explorer** on the card menu drop you into the repository directly. ## Conversation history The **History** button on the action bar above the prompt bar opens the agent's own in-terminal history picker - for Claude Code, the same picker its double-Escape opens - so you can jump back through the live conversation right in the terminal. Esc closes it. For a readable transcript - every message between you and the agent, with **Show** filters for **Tool calls**, **Results**, and **Thinking** so you can read just the conversation or audit exactly which actions the agent took and what came back - open the session in your browser: that is the Cockpit's Chat tab, on [Working in a session](https://devthrottle.com/docs/cockpit/session-view). > **Tip:** When a diff surprises you, read the Cockpit's Chat tab with only Tool calls turned on. The list of file edits and commands, in order, is usually the fastest way to see where the agent went off the path you intended. ## Past sessions The **Resume Session** tab in the New Session dialog lists past Claude Code conversations - each with a summary, its message count, and how long ago it ran. See [starting and steering agents](https://devthrottle.com/docs/director/steering). --- # Repositories and GitHub > The Repositories view: the root folders the Director scans, the ordered list of what it found, and each repository's own screen with its changes, worktrees, branches, pull requests and history. Part of the DevThrottle documentation, section "The Director". Canonical HTML version: https://devthrottle.com/docs/director/repositories Last updated: 2026-09-06 Agents work in repositories, so the Director keeps a catalog of yours. Click the pinned **Repositories** entry at the bottom of the Director's sidebar to open the Repositories view over the session area - every repository under your root folders, with worktrees, branches and changes, in one place instead of a folder hunt every time. The view has a left rail with three entries: **Local repositories**, which opens first, **Recommendations**, and **Root folders**. ## Root folders A **root folder** is a directory you keep repos under (for example `D:\Repos`), and it is what the Director scans to find them. Pick **Root folders** in the view's left rail to see yours; **+ Add root folder** opens a small dialog with a label, the folder path, and a provider - **GitHub**, **Azure DevOps** (with organization and project), or **Local Only**. The provider is recorded and shown on the root folder; repository rows show a provider inferred from each repository's own origin. Finding them is the folder scan itself - the Director lists the repositories already on disk under each root. ## Working with the list The list itself is a reading surface with two buttons above it - **Copy report**, which puts this machine's repository state and what to do about it on the clipboard ready to paste into an agent, and **Refresh**, which rescans your root folders. There is no filter box. The list is one flat list, ordered for you rather than searched by you: repositories with worktrees safe to clear up come first, then those with the most uncommitted changes, then the rest by name - so whatever wants attention is at the top. Click a repository row and it opens that repository's own screen. A row that is still being checked does not open - its *verifying* chip says so, and it becomes clickable when the check finishes. ## One repository's screen The header carries a back arrow to the list, the repository's name and address, **Open in VS Code**, and a **Copy report** for this repository alone. Under it are five tabs: - **Changes** - the default. Every changed line, stage and unstage per file, and a commit box. - **Worktrees** - the worktrees cut from this repository. - **Branches** - the branches it holds. - **Pull requests** - its open pull requests. - **History** - its commits. ## Recommendations The background scan does not only count things - it says what it would do about them. Pick **Recommendations** in the rail and you get that list in plain language, with an amber count on the rail entry when there is anything in it. Each recommendation is a card: what it is, what it means, and a quieter line saying why the scan raised it. Two buttons sit on each card. **Show me** opens the repository the recommendation is about, so you can look before you decide - or the list itself, when the recommendation spans several repositories. **Copy** puts that one recommendation on the clipboard as text, and **Copy all** at the top does the whole list - both written to be pasted straight into an agent as its next task. When there is nothing to say, the page says so: "Nothing to recommend - your repositories look tidy." > **Note:** Nothing on this page happens on its own. The scan reads, sorts and suggests; every change is still yours to make, or your agent's. > **Note:** This screen reads and edits a repository; it does not start sessions, and it does not clone. Starting an agent is the [New Session window](https://devthrottle.com/docs/start/first-session), which is also where you browse to a repository the Director has not seen before. > **Note:** Prefer the phone? The mobile app starts sessions from the same recent-repo list - see [working with sessions from your phone](https://devthrottle.com/docs/mobile/sessions). --- # Agents and models > Tell the Director about the coding agents you run: the agent editor with its live preview of the command that entry will launch with, model detection and the model picker, plus the /memory and /output-style commands. Part of the DevThrottle documentation, section "The Director". Canonical HTML version: https://devthrottle.com/docs/director/agents Last updated: 2026-08-07 DevThrottle runs the coding agents you already use - Claude Code by default, plus Codex, Cursor, GitHub Copilot CLI, Gemini, OpenCode, Grok, Pi, or any command-line agent you bring yourself. This page covers how you tell the Director about an agent and shape how it launches. (Which agent should you use? That is the [supported agents](https://devthrottle.com/docs/agents/supported) page.) ## The agent editor Open **Settings -> Agents** and hit **+ Add Agent**. The editor is one form with a live preview: - **Agent type** and **Display name** - pick the backend and what to call it. **Custom** covers any CLI agent not on the list. - **Executable** - where the agent's command lives, with **Detect this tool** to find it for you and **Quick check** to prove it runs. - **Advanced launch** - stay **Guided** (a preset plus a **Choose model...** picker listing the models the agent actually reports) or switch to a **full custom command line** when you know exactly what you want. - The right side always shows **the command this entry will launch with** and the effective permissions. Read it as the entry's own command line rather than a receipt for every launch: the New Session window's **Run without approval prompts** checkbox is a per-session choice applied on top afterwards, and it can append an unattended option this preview does not show. **Launch preview** opens a throwaway terminal to try it without saving anything. > **Tip:** The same Settings tab is where you enable, disable, and reorder agents - the order controls how they appear in the [New Session dialog](https://devthrottle.com/docs/director/steering). ## Memory and output style (slash commands) Two agent-shaping tools live behind slash commands in the prompt bar rather than menus: - `/memory` - edit the CLAUDE.md memory files (your user-level file, the current project's file, and auto-memory) in place. - `/output-style` - choose how the agent formats its responses. > **Note:** Deeper launch tooling - reusable agent templates and an MCP server manager - is in alpha and not part of the standard app yet. This page will grow when those ship. --- # Workspaces > Save a named set of sessions - repos, names, colors, launch configs - and bring the whole Director back in one step with File > Load Workspace. Part of the DevThrottle documentation, section "The Director". Canonical HTML version: https://devthrottle.com/docs/director/workspaces Last updated: 2026-09-06 A workspace is a saved layout: a named set of sessions - which repos, what they are called, their colors, how they launch - that you can bring back in one step. If you run the same crew every morning, save it once and stop rebuilding it. ## Saving one **File -> Save Workspace** opens a dialog with a name, an optional description, and a checkbox list of your current sessions - include the whole Director or just the sessions that belong together. Saving under an existing name warns before overwriting. What is stored per session: its display name, repository path, custom color, sort order, which coding agent it ran, and its launch arguments - the recipe for recreating it, not the conversation itself. ## Loading one **File -> Load Workspace** lists your saved workspaces with a preview of the sessions inside. **Load** closes the sessions currently in the Director, then restores each saved session while a progress window keeps score. **Delete** removes a saved workspace; **File -> Clear Workspace** just clears the Director. > **Warning:** Loading replaces the current Director - the Director closes your current sessions first. Save the current Director as its own workspace if you will want it back. > **Note:** A workspace saves a set of sessions, not a formation. Roles and missions are not part of what it stores, so a loaded workspace comes back as ordinary standalone sessions in the right repositories with the right names - you declare the roles and attach the mission again afterwards. --- # Renaming and resuming sessions > The moves that manage a session after it starts: the rename dialog, /resume to continue an old conversation, and what happens when you close with sessions running. Part of the DevThrottle documentation, section "The Director". Canonical HTML version: https://devthrottle.com/docs/director/session-lifecycle Last updated: 2026-08-04 Sessions have a life after you start them: they get named, and eventually they get closed. This page covers the small set of moves that manage that life. ## Naming When you create a new session from the Director's New Session dialog, the rename dialog opens - name it while you still remember why it exists. Sessions that already have a name skip the dialog: resuming a previous conversation brings its saved name back, and a named session launches under the name it was saved with. A session started by another session, or created remotely, appears in the list without any dialog. Rename any time later from the session's right-click menu. Good names carry the fleet: they are what you see on [the Director](https://devthrottle.com/docs/director/sessions), on your phone, and what [Voice Mode](https://devthrottle.com/docs/mobile/voice) speaks out loud. ## Resuming an old conversation Type `/resume` (or `/continue`) in the prompt bar to pick a previous **Claude Code** conversation in this repository and continue it. ## Closing Close a session from its right-click menu when its work is merged and done. Closing the whole Director window ends the sessions inside it. Minimise it instead when you want the work to carry on - see [keeping agents running](https://devthrottle.com/docs/gateway/lifecycle). > **Tip:** From the phone, **Back to Sessions** sits at the top left of every session screen, and the rest lives in the session menu behind the three dots at the top right: **Remove session** (behind a confirmation), and **Snooze** on the Chat and Terminal screens. Voice mode puts Respond and Snooze on the screen itself, as the big buttons at the top, instead - see [working with sessions from your phone](https://devthrottle.com/docs/mobile/sessions). --- # Director settings > Every tab of the Director Settings dialog - Account, Gateway, Agents, Browser profiles, Directories, Advanced, and Tools - and where the settings that are not in it live. Part of the DevThrottle documentation, section "The Director". Canonical HTML version: https://devthrottle.com/docs/director/settings Last updated: 2026-09-06 Open settings with the **Settings** toolbar button, or File - Settings (Ctrl+comma). The dialog is organized into seven tabs: **Account**, **Gateway**, **Agents**, **Browser profiles**, **Directories**, **Advanced**, and **Tools**. ## Account A read-only view of your DevThrottle account: the Gateway this Director connects through, and who is signed in. There are deliberately no sign-in controls here - when a [Gateway](https://devthrottle.com/docs/gateway/overview) is connected, your account is managed there, sign-in and identity included, and every Director on the machine inherits it. One button, **Manage connection...**, jumps you to the Gateway tab at whatever step the connection is currently on. ## Gateway This tab is a single guided connection panel rather than a form of addresses and tokens. It scans for Gateways - on this computer and over Tailscale - and lists what it found, with one marked **Recommended**. Picking one connects immediately and checks the connection in both directions, so there is no separate Test step: you watch it reach the Gateway, then watch the Gateway reach this Director back. Then it asks you to **Sign in with DevThrottle**, which is what puts this device's own token on it - there is no pairing code to type. When it is done the tab shows the two green ticks - connected, signed in - and an **Advanced** disclosure holding the things you rarely need: the Gateway address and this device's token, masked. Back on the scan step, the same disclosure holds a box for typing an address by hand when the scan cannot find yours. **Change gateway** disconnects and starts the scan over, for moving between a local Gateway and the hosted one. ## Agents The list of coding agents that appear in the New Session dialog, in the order they appear there. Each row has a display name, a type, an **Enabled** checkbox, and a status pill saying whether the agent's command checked out; the arrows on the left reorder the list, **Edit** opens that entry in its own dialog, and the trash removes it. **+ Add Agent** creates an entry by hand. You can have several entries of the same type - two Claude entries with different presets, say. **Setup wizard...** re-runs the whole first-run setup - agents, tools, where your code lives, screenshots, and the Gateway - and leaves anything already set up alone. It is the way back to the guided path, not an agent scanner. > **Note:** Eight agents ship with a built-in driver - Claude Code, Pi, Codex, Gemini, OpenCode, Cursor, Grok and GitHub Copilot - and any command line of your own runs as a custom agent. What you find in this list the first time is not all eight, though: DevThrottle looks for each of them on the machine and seeds a row only for the ones it finds, so an agent you have not installed is simply absent rather than listed and broken. Install it and re-run the setup wizard, or add the entry by hand. What each entry holds is covered on [coding agents in the Director](https://devthrottle.com/docs/director/agents). ## Browser profiles Real, signed-in browser profiles your agents can drive, each with its own logins and kept apart from the browser you use yourself. **+ New browser profile** asks what the profile will be signed in as and which installed browser to use, then opens an empty window for you to sign in by hand - DevThrottle never types your credentials and never sees them. Tell it you are done and the profile is listed as ready for any agent on the machine to drive. Profiles can be renamed and removed, and removing one takes its own folder with it. Driving them needs Browser Harness, which this tab installs for you into its own environment; until it is there the profiles stay listed but cannot be driven. The full walkthrough is on [giving an agent its own browser](https://devthrottle.com/docs/tutorials/agent-browser). ## Directories Where screenshots land. Images you send from your phone are saved to this folder and appear in the session's **Screenshots** panel; **Detect** finds the default location and **Browse** picks another. On a Mac this one has to be set explicitly. ## Advanced Two cards. **Network and Firewall** turns off the Windows pop-up that asks whether to allow the app on your networks - Windows asks for administrator approval once, and then it stops appearing. **Alpha Features** is a single checkbox, off by default, that reveals experimental features still being verified. This documentation covers the product with the checkbox off. ## Tools DevThrottle ships a set of command-line helper tools (the cc-* tools) that agents can use. This tab shows their status, offers **Download and repair tools**, and has an **Automatically keep cc-* tools up to date** checkbox - on by default, so the tools stay current without you thinking about them. > **Tip:** The footer of the dialog has an **Open config.json** link - the file behind every setting, for when you want to see or script the raw configuration. ## Settings that are not in this dialog Settings that belong to your account rather than to one Director window are on the Cockpit's Settings page (open **Cockpit** from the toolbar). That is where choices such as voice transcription live - dictation comes with your plan and needs no key of its own. See [the Cockpit](https://devthrottle.com/docs/cockpit/overview). Two things people go looking for there are somewhere else entirely. Whether the Gateway starts when you log in is set by the installer and changed with the `cc-devthrottle autostart` command (`on`, `off`, `status`) - see [keeping agents running](https://devthrottle.com/docs/gateway/lifecycle). And there is no longer any setting for how devices address each other on your network; the Gateway tab's own scan works that out. --- # What the Gateway does > The always-on hub that keeps your sessions reachable from your browser and phone. Your agents run in Directors on your own machines and dial out to it; here is how the architecture fits together and why. Part of the DevThrottle documentation, section "Gateway". Canonical HTML version: https://devthrottle.com/docs/gateway/overview Last updated: 2026-09-06 The Gateway is the always-on hub of DevThrottle. Your coding agents do not run on it - they run in Directors on your own machines. What the Gateway does is hold the whole fleet's picture and keep it reachable: every Director dials out to it and keeps that connection open, and everything you do from anywhere else goes through it. ## The gateway is the always-on hub Think of the gateway as the meeting point. Your phone, a browser on another laptop, the Cockpit - they do not run agents themselves, and they never talk to your computers directly. They connect to the gateway, and the gateway reaches each session's Director over the connection that Director already opened outward. On a normal install nothing on your machine listens - the Director and the Launcher only dial out. A port (7878) is listened on only if you install the Gateway yourself on your own machine; the hosted Gateway involves no listener of yours at all. The gateway is the always-on hub your devices meet through. Your coding agents run in Directors on your own computers, which dial out to the gateway; your phone and any browser connect to the same gateway. The gateway also calls AI models, for the AI features DevThrottle itself provides: transcription, spoken narration, and the assistant. ## Where the gateway can run The gateway is a headless background service - there is no window to keep open - and the service itself is cross-platform. What differs is how you get it and run it: - **Windows.** The download on this site. This is the path to take if you are hosting the gateway yourself on a machine you already leave on. - **Hosted by us.** We run the gateway for you on Linux, so no machine of yours has to stay on at all. See [pricing](https://devthrottle.com/pricing) for the plans that include it. - **Linux, self-hosted.** The gateway ships as a headless container image in the open source repository, so you can run your own on a Linux box or a server. There is no one-click installer for this yet - you build and run the image yourself. A Mac is supported as a *workstation*: install the app on a Mac, run agents there, and connect to a gateway hosted elsewhere. A Mac cannot host the gateway today. ## What lives on the gateway - **The fleet's picture.** Session state and conversation history from every machine, so remote viewing and supervision work. The sessions themselves run in Directors on your computers. - **The source of truth.** The gateway computes each session's state and the words for it - **Working**, **Needs you**, **Ready**, **Background**, **Snoozed**, **Exited**, **Crashed** - in one place for every client, which is why your phone, the Cockpit, and the desktop all agree on what a session is doing. - **Scheduled runs.** A built-in scheduler can launch unattended sessions on a [cron schedule](https://devthrottle.com/docs/gateway/cron). - **The agent surface.** The `cc-devthrottle` command line drives the fleet by talking to the gateway with the calling session's own key; the gateway reaches the owning Director down its outbound connection. The Director itself has no local listener, and no gateway connection means no agent tooling. ## How your other devices connect Because the gateway stays on, you do not have to be at any particular keyboard. Open the same sessions in a [browser](https://devthrottle.com/cockpit) on any machine, or in your pocket on [mobile](https://devthrottle.com/mobile). A session gets blocked while you are away - you answer it from your phone and keep the work moving. All of it goes through the one gateway that every Director reports to. ## Where to go next Ready to connect? [Install DevThrottle and connect a gateway](https://devthrottle.com/docs/start/install) walks the whole path, including the wizard screen where you choose hosted, self-hosted, or not now. To see how the gateway fits with the rest of the pieces, read [what DevThrottle is](https://devthrottle.com/docs/overview). --- # Keeping agents running > What keeps running when you close a window - viewers vs the Director vs the Gateway. Part of the DevThrottle documentation, section "Gateway". Canonical HTML version: https://devthrottle.com/docs/gateway/lifecycle Last updated: 2026-09-06 DevThrottle's promise is that you can look away without your agents stopping. This page is the honest map of how that works: which piece runs what, what keeps going when you close something, and what comes back after a reboot. ## Three layers, three lifetimes - **Viewers** - the Cockpit in a browser, and your phone. Pure views. Open and close them as often as you like; nothing about your agents changes. - **The Director** - the desktop app that owns the agent sessions. The agent processes are its children: as long as the Director runs, your agents run, whether or not you are looking at any of it. - **The Gateway** - the always-on service that keeps everything reachable: by default DevThrottle's hosted Gateway, or one you run yourself. It does not run the agents itself; it serves the Cockpit and your phone, tracks the Directors on your machines, and sends the command that starts one when a [scheduled run](https://devthrottle.com/docs/gateway/cron) fires. On each machine a small **Launcher** - a tray app registered to start at login - holds the connection to the Gateway and starts and stops Directors when asked. > **Note:** The practical rule: walk away from the desk, close the browser, pocket the phone - agents keep working, and you can answer them from anywhere the Gateway is reachable. The Director window itself is the one thing to leave running. ## Closing the Director Because sessions live inside the Director, closing it ends them. Minimise the window rather than closing it. > **Warning:** Closing the Director ends the agent processes. Every change the agents made to your files stays - but in-flight work stops where it stands. ## Starting and stopping the Gateway itself If DevThrottle hosts your Gateway, none of this is yours to run - it is already on, and it stays on. What follows is for a Gateway you run yourself. The Gateway is a headless background service. It has no window and it draws no screens: every screen it used to own lives in the [Cockpit](https://devthrottle.com/docs/cockpit/overview), which you reach by browsing to the Gateway's own address. So the only two controls it offers a person are **Start** and **Stop** - the two verbs a service has. To have it come up on its own when you log in, use the command line: **Start the Gateway at login** ``` cc-devthrottle autostart on # start the Gateway when you log in cc-devthrottle autostart off # do not cc-devthrottle autostart status # whether it does, and the mechanism on this OS ``` It registers per user, using whatever the operating system already provides - the Run key on Windows, a launch agent on macOS, a `systemd --user` unit on Linux, which is what a headless server needs where no tray or window exists. `status` prints which one is in force on the machine you run it on. The Gateway's own settings are not in a window either - they live in the Cockpit's Settings page. What the Gateway holds falls into two halves, and a restart treats them differently: - **Kept in its database, so a stop and a start changes nothing.** Schedules and their run history, session history, paired devices, skills and workflows, keys and settings. These are simply there again when it comes back. - **Held in memory, and rebuilt after the restart.** The live picture - which Directors are up right now, and the session state each of them is pushing - is a cache, not a record. A restarted Gateway starts with none of it and fills it from the machines themselves: each Director re-registers and pushes a fresh full snapshot of its sessions over its own outbound connection. In practice that gap is short - a Director that is up re-registers and heartbeats on a fifteen-second cycle - and it needs nothing from you. But it is a real gap, and it is the one thing to plan around: for the moments right after a restart the Cockpit and your phone can show a thinner fleet than you have, and a machine that is off or offline stays absent until it comes back and reports in. Nothing is lost by this - the history of those sessions is in the first half above - but the live roster is reassembled rather than reloaded. ## After a reboot The Launcher registers itself to start at login (you can toggle that from its tray icon), so the machine comes back connected to the Gateway without any ritual. The recorded half above comes through a reboot untouched: [scheduled jobs](https://devthrottle.com/docs/gateway/cron) and their run history, paired devices, and machine settings. The live roster is reassembled as each machine comes back and reports in, the same way it is after a Gateway restart. Scheduled jobs recompute their next run time, and if a job fires when no Director is open, the Gateway has the Launcher start one - so unattended runs do not depend on you remembering to open anything. ## Where to go next - [Scheduled runs (cron)](https://devthrottle.com/docs/gateway/cron) - unattended agent runs on a schedule. - [Control API](https://devthrottle.com/docs/gateway/control-api) - drive sessions programmatically. --- # Connecting machines without opening a port > Your machines connect to the Gateway without opening or forwarding a network port - each one dials out, nothing listens. Not a setting: it is how DevThrottle connects. Part of the DevThrottle documentation, section "Gateway". Canonical HTML version: https://devthrottle.com/docs/gateway/portless Last updated: 2026-08-07 Your other computers - a laptop, a Mac, a second desktop - connect to your [Gateway](https://devthrottle.com/docs/gateway/overview) so they can share the same sessions, and they do it **without opening or forwarding a network port**. This is not a setting you enable; it is how DevThrottle connects. Every machine reaches out on its own, and nothing on it sits listening. ## How it works The direction is always outward. The Director on each of your machines dials out to the Gateway and keeps that connection open; everything that reaches the machine - your phone answering a session, the Cockpit, another agent's command - comes back down the connection the machine itself opened. The Gateway never contacts your machines; it does not need to know how to. ## Why it is better - **Simpler to set up.** There is no port to open and no router forwarding rule to configure on any machine you connect. It reaches out on its own. - **Safer.** A machine that never opens a port for an inbound connection has nothing extra exposed for someone else to find. The connection is started from the inside out. The one listener in the whole system is a *self-hosted* Gateway's own port (7878), on the single machine you chose to run it on. With the hosted Gateway, no machine of yours listens on anything at all. (One brief exception, stated for honesty: during an interactive sign-in the Director opens a loopback listener to receive your browser's callback - it lasts as long as the sign-in and carries nothing an agent can call.) > **Note:** This is about how machines connect - not where your work runs. Your coding agents still run in Directors on your own computers. See [what the Gateway does](https://devthrottle.com/docs/gateway/overview) for the bigger picture. ## A short history Machines have connected across the network this way - outward, with no port to open - since the connection shipped in v1.1.0. What remained after that was local: the Director and the launcher each listened on a local network port of their own machine, and agents could reach the fleet two ways. v1.9.9 deleted both listeners - DevThrottle no longer opens a network port on your machine, and everything an agent does goes through the Gateway, one door, always. Leftovers from the listener era are cleaned up automatically the next time a Director starts. ## Where to go next For how the Gateway and your other devices fit together, read [what the Gateway does](https://devthrottle.com/docs/gateway/overview). To connect and answer agents from a browser on one of those machines, see the [Cockpit](https://devthrottle.com/docs/cockpit/overview). --- # Why the app feels slow at home (and how to make it fast) > The Tailscale warm-up explained: connections start on a relay and silently switch to a direct home path. How to check direct vs relayed, let your agent diagnose it with cc-devthrottle diag network, and the five-step fix checklist. Part of the DevThrottle documentation, section "Gateway". Canonical HTML version: https://devthrottle.com/docs/gateway/network Last updated: 2026-09-06 This page is about a **self-hosted** [Gateway](https://devthrottle.com/docs/gateway/overview) - one running on a machine of your own, which you reach from your phone or a browser over Tailscale. If DevThrottle hosts your Gateway, which is what the install wizard recommends, none of this applies to you: you reach it at a public address and there is no relay warm-up to wait out. On a self-hosted Gateway the app sometimes feels slow - even at home, on the same Wi-Fi as the Gateway. The short version: that slowness is almost always a brief warm-up, not a broken setup. Give it a few seconds, or keep the app open, and it speeds up on its own. This page explains why, how to check, and how to fix the rare case that stays slow. ## How your phone reaches the Gateway Your phone and the Cockpit reach your Gateway through Tailscale, at a secure address like `https://your-machine.your-tailnet.ts.net`. Tailscale is required today because it is the one thing that gives your Gateway a web address browsers trust as secure - and your phone needs a secure connection before it allows the microphone, background updates, and notifications. Everything travels over a private, encrypted connection to your own machine. ## Why the first few seconds can feel slow Every Tailscale connection **starts** by routing through a relay server somewhere on the internet - on purpose, because a relay works the instant you open the app. While you use that relay, Tailscale quietly hunts for a **direct** path between your phone and your Gateway across your home network, and the moment it finds one it silently switches you over. No button, no setting - it just happens. - **Warming up (relayed):** the first moments after opening the app, your data may take a long trip to a distant relay and back - even though the Gateway is a few feet away. - **Fast (direct):** seconds later, your data goes straight across your own Wi-Fi. > **Note:** **"Connected through Tailscale" does not mean slow.** At home you are always connected through Tailscale - that is normal. What decides fast or slow is the path underneath: direct across your Wi-Fi, or bounced through the relay. A phone can show a Tailscale address and still be on a fast, direct home path - we have measured exactly that (a home phone on the Tailscale route with a direct LAN connection at 44 ms). The real question is direct vs relayed. ## How to see which state you are in There are two places to look, and they read the same signal. **On your phone:** open **Menu -> Diagnostics** in the mobile app. It shows how the Gateway sees you (route), your latency, download and upload speed, and a plain-English verdict. Run it, wait a few seconds, run it again - if the second run is much faster, you just watched the warm-up finish. **In a browser:** open **Network** in the Cockpit. Its centrepiece is the Gateway's own check of every connected device - *Direct vs relayed*, with each device's latency - which is read from the Tailscale layer on the Gateway machine and needs no phone at all. Beneath it you can test the browser you are sitting at, see the recent results other devices reported, and read the trend of how much of your traffic has been direct over the last day or week. A single speed test cannot tell "warming up" apart from "genuinely stuck on the relay" - a slow first reading right after opening the app is usually just the warm-up. For the authoritative answer, ask your agent (below), or run Tailscale directly on the Gateway machine: **From the Gateway machine** ``` tailscale ping tailscale status ``` A reply `via 192.168.x.x` (a home address) means direct and fast; a reply `via DERP` means you are still on the relay. As a yardstick: direct on a home network is single-digit to low-tens of milliseconds; stuck on a relay is 100+ ms. ## Let your agent diagnose it You should not have to work through a checklist by hand - you have a coding agent connected to your Gateway. Ask it "is my connection direct or relayed, and why is it slow?" It runs: **What the agent runs (you can too)** ``` cc-devthrottle diag network cc-devthrottle diag results ``` The Gateway checks every connected device - direct or relayed, latency, and whether UDP and your network look healthy - by reading the Tailscale layer directly, no phone involved. That is the one check that can tell warming-up apart from genuinely-relaying, and it points at the specific thing to fix. ## The Gateway tells you without being asked You do not have to go looking. When a device stays on the relay at home for several minutes, the Gateway raises it two ways: an ambient indicator in the app and the Cockpit, and an email to the account owner naming the device and listing the same fixes as the checklist below. When that device is back on a direct path, you get a short note saying so. It is deliberately quiet. The alert fires only when the slowness *persists* - the brief warm-up when you open the app is normal and is never reported - and emails are capped per day, so a network that is bad for hours cannot fill your inbox. The "recovered" note goes only to a device you were actually warned about. If nobody is signed in on the Gateway there is no account to email, so you get the indicator and nothing else. ## If it stays slow: the checklist 1. **Re-test after a few seconds** The warm-up usually finishes on its own. This alone explains most "it felt slow" moments. 2. **Keep the app open and use it** Real activity pushes Tailscale to complete the direct connection faster; open-and-immediately-measure is the worst case. 3. **Grant Tailscale local-network access on your phone** Tailscale needs permission to see devices on your home Wi-Fi to build the direct path. If it is off, you can get stuck on the relay. Check the Tailscale app's settings. 4. **Turn off exit nodes at home** If your phone routes all traffic through a Tailscale exit node, your data leaves the house and comes back - defeating the direct home path. 5. **Fix router settings that block direct paths** Turn OFF wireless client isolation (also called AP or guest isolation), and allow UDP with UPnP or NAT-PMP enabled - Tailscale uses these to punch a direct path through your router. > **Tip:** Worked through all five and still relayed? That is worth reporting - it usually points to a router or network policy that needs a closer look. --- # Scheduled runs with the Gateway cron > Schedule unattended agent runs with the Gateway built-in cron scheduler - the Cockpit Schedule page and the Gateway's own REST API behind it. Part of the DevThrottle documentation, section "Gateway". Canonical HTML version: https://devthrottle.com/docs/gateway/cron Last updated: 2026-09-06 The Gateway has a built-in scheduler: define a job once and it starts an agent session on a schedule - every morning, every hour, or once at a specific time - with nobody at the keyboard. It is the DevThrottle-native alternative to wiring up an external task scheduler. ## The Schedule page The friendly way to manage jobs is the **Schedule** page in the Cockpit (open **Cockpit** from the Director toolbar, then Schedule in the left navigation). Create, edit, enable or disable, and run jobs there, and see each job's run history. ## From the command line The same schedules are on the `cc-devthrottle` command line, which is the surface an agent or a script reaches for. These talk to your Gateway wherever it is - hosted or your own - so there is no address to configure. **Reading** ``` cc-devthrottle schedule list # every schedule on the Gateway cc-devthrottle schedule get # one schedule in full cc-devthrottle schedule runs # its run history cc-devthrottle schedule endpoint # which Gateway these commands are talking to ``` **Changing** ``` cc-devthrottle schedule run # fire it now, whatever its schedule says cc-devthrottle schedule disable # stop it firing, keep the definition cc-devthrottle schedule enable cc-devthrottle schedule delete ``` Creating one takes the four things a schedule cannot be without - `--name`, `--machine`, `--repo` and `--tz` - plus either `--cron` for a recurring five-field expression or `--at` for a one-off local timestamp, and either `--seed` for the prompt the session starts with or `--worklist` to drain a named work list instead: **Creating one (bash; PowerShell continues a line with a backtick)** ``` cc-devthrottle schedule create \ --name "Morning triage" --machine MY-PC --repo D:/repos/my-project \ --tz America/New_York --cron "0 7 * * 1-5" \ --seed "Review open issues in this repo and post a triage summary." ``` The reading commands all take `--json`, so an agent can act on the answer rather than parse a table. ## The REST API Underneath both of those is the Gateway's own REST surface. Reach for it when you are writing something that is not a DevThrottle session - a build step, a webhook, another service. On a self-hosted Gateway, the scheduler lives on the Gateway's local API at `http://127.0.0.1:7878`. Requests need the machine's shared Gateway token as a bearer token; it is in `%LOCALAPPDATA%\cc-director\config\director\gateway-token.txt`. On the hosted Gateway the same `/cron` surface rides your Gateway's hosted address instead, behind your account's sign-in and device authentication - there is no local port and no shared token file. The Schedule page in the Cockpit uses exactly this surface, so anything it can do, a script signed in the same way can do. `POST /cron/jobs` Create a job. Returns 201 with the stored job (including its server-assigned `id` and computed `nextRunUtc`), or 400 if the schedule is invalid. `GET /cron/jobs` List all jobs, wrapped as `{ "jobs": [...] }`. `GET /cron/jobs/{id}` Fetch one job. `PUT` to the same path updates it; `DELETE` removes it. `POST /cron/jobs/{id}/run` Run the job now, regardless of its schedule. Returns 409 if another fire attempt for this job is in flight at that moment and the job prevents overlap. `GET /cron/jobs/{id}/runs` The job's run history, newest first, capped at 50 records per job - when each run was scheduled and fired, which machine and Director handled it, and whether a session started. ## Job fields | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | Required | Display name for the job. | | `enabled` | boolean | Optional | Whether the job fires. Defaults to true. One-off jobs disable themselves after firing. | | `scheduleKind` | string | Required | "recurring" (uses cronExpression) or "oneOff" (uses runAt). | | `cronExpression` | string | Optional | Standard 5-field cron expression, e.g. "0 7 * * 1-5" for 7:00 on weekdays. Required when scheduleKind is "recurring". | | `runAt` | string | Optional | Local wall-clock timestamp, e.g. "2026-07-10T18:00:00", interpreted in timeZoneId. Required when scheduleKind is "oneOff". | | `timeZoneId` | string | Required | Time zone the schedule is evaluated in, e.g. "America/New_York". | | `target.machine` | string | Required | The machine the session runs on. Machine names come from GET /directors. | | `action.repoPath` | string | Required | Working folder for the session. Use forward slashes, e.g. "D:/repos/my-project". | | `action.seed` | string | Optional | The prompt the new session starts with. Either seed or workListName must be set. | | `action.workListName` | string | Optional | Instead of a seed prompt, drain a named work list. Takes precedence over seed. | | `action.autoDismiss` | boolean | Optional | When true (the default for seed actions), the session closes itself once it finishes with nothing needing a human, instead of lingering in the rail. Set false to keep the session open like an interactive one. | | `preventOverlap` | boolean | Optional | Reject a fire attempt while another fire attempt for the same job is mid-start. Defaults to true. Does not guard against the session a previous run started - see below. | | `notifyOn` | string | Optional | "none" (default), "always", or "failure" - when to notify. The notification reports whether the run started; "failure" means it failed to start. | | `notifyWebhookUrl` | string | Optional | Webhook URL for run notifications. | The Gateway fills in the rest: `id`, `createdUtc`, `lastFiredUtc`, `lastStatus`, and `nextRunUtc` - the next due time in UTC, computed from your schedule and time zone, and recomputed whenever the Gateway restarts. ## Example: a weekday morning run **create-job.json** ``` { "name": "Morning triage", "scheduleKind": "recurring", "cronExpression": "0 7 * * 1-5", "timeZoneId": "America/New_York", "target": { "machine": "MY-PC" }, "action": { "repoPath": "D:/repos/my-project", "seed": "Review open issues in this repo and post a triage summary." }, "preventOverlap": true } ``` **PowerShell (self-hosted)** ``` $token = Get-Content "$env:LOCALAPPDATA\cc-director\config\director\gateway-token.txt" curl.exe -s -X POST http://127.0.0.1:7878/cron/jobs ` -H "Authorization: Bearer $token" ` -H "Content-Type: application/json" ` --data-binary "@create-job.json" ``` For a one-off, set `"scheduleKind": "oneOff"` and `"runAt": "2026-07-10T18:00:00"` instead of the cron expression - the job fires once at that local time and disables itself. ## How firing works The Gateway sweeps the job list about once a minute. When a job is due, it looks for a running Director on the target machine. If none is running, it asks that machine's connected Launcher to start one and waits briefly for it to register. If the machine is off - or nothing registers in time - the launch fails and the run is recorded as `not-started`. Either way, a recurring job then advances to its next future occurrence: a missed fire is a single skipped beat, never a replay of every missed interval, and never a run that triggers later when the machine wakes up. The run record keeps the start outcome - did a session start, on which machine and Director, with which session id. It does not track what the agent went on to do: the run's task status is recorded as unknown and stays that way. To see what a scheduled run actually did, open the session it started. > **Warning:** Seed prompts run in a brand-new session with zero context. Write them self-contained: name the repo, the goal, and where to put the result. "Continue yesterday's work" means nothing to a fresh session. > **Tip:** `preventOverlap` guards the fire attempt, not the session. It rejects a second fire while the first is still mid-start, and is released as soon as the start attempt finishes - so tonight's run will still fire even if last night's session is working to this moment. If two of the same job must never run at once, make the prompt itself tolerant of a sibling session, or space the schedule wider than the work. ## Where jobs live Job definitions and run history live in the Gateway's database - the `cron_jobs` and `cron_runs` tables, in the local SQLite file on a self-hosted Gateway and in PostgreSQL on the hosted one - so schedules survive restarts and reboots. (The old `cronjobs.json` and `cronruns.json` files were a previous format; on first run after an upgrade they are imported once and renamed aside as backups.) See [keeping agents running](https://devthrottle.com/docs/gateway/lifecycle) for the full restart story. --- # Workflows: the rules your fleet works by > A workflow is a named way of working, stored on your Gateway; every session sees its catalog entry in the briefing at launch. The built-in workflows, how publishing reaches your fleet, and the command surface for reading and authoring them. Part of the DevThrottle documentation, section "Gateway". Canonical HTML version: https://devthrottle.com/docs/gateway/workflows Last updated: 2026-08-07 A workflow is a **named way of working** that your whole fleet shares. Not a script and not automation - it is written guidance about how a kind of job should be run, stored on your Gateway. Every session on every machine starts with the catalog in its briefing - each workflow's name and a one-line summary - and a session that takes on matching work fetches the full conduct from there. A session spawned into a run is pointed at the conduct directly, at the run's pinned version. It exists because the alternative is retyping the same expectations into every session and getting slightly different behaviour each time. ## The catalog Open **Workflows** in the Cockpit. Each row is one workflow: its name, whether it is currently in force, which version is live, and when it last changed. ![The Cockpit Workflows page listing three built-in workflows - mission, standalone, and standalone-with-review - each marked In force with its live version, last updated date, recent activity, and Preview and Clone actions](https://devthrottle.com/docs/screenshots/cockpit/workflows.png) DevThrottle ships with three built-in workflows: - **Mission** - the Team way of working, shipped in the catalog under the name mission: an Architect settles the design, a Manager drives the phases, and Workers build. You are bothered once, at the report. - **Standalone** - one agent picks up the work and finishes it. No manager, no reviewer. - **Standalone with review** - one agent does the work, and a second, separate agent reviews it before it is called done. ## How a change reaches your fleet Any session can author a workflow. It is pushed as a **draft**, and publishing makes it the live version at once - there is nothing to deploy and nothing to restart. The one delay is at the edge: each Director re-reads the catalog on a poll about every minute, so a session started in the first moments after a publish can still be briefed with the old catalog. Reading the catalog directly with the commands below is never behind - they ask the Gateway live. > **Note:** Publishing does not disturb work already underway. A run that is in progress keeps the version it was pinned to when it started, so changing a workflow never rewrites the rules out from under a job that is halfway done. ## Reading and authoring from the command line The Cockpit is one window onto the catalog; the command line is the other, and it is the one your sessions use. **Reading** ``` cc-devthrottle workflow list # every workflow the fleet can run cc-devthrottle workflow show # metadata, steps, outcome criteria cc-devthrottle workflow instructions # the raw conduct, to be followed cc-devthrottle workflow versions # version history, newest first ``` `instructions` is the one a session actually calls: it prints the workflow's guidance so the session can follow it as its conduct for that job. **Authoring** ``` cc-devthrottle workflow pull --dir # workflow.json + instructions.md + helpers/ cc-devthrottle workflow push --dir # upload as a draft (creates it if new) cc-devthrottle workflow publish # the draft becomes the live version cc-devthrottle workflow clone # copy one into a new workflow you own ``` The id on `push` is the workflow being written, and it must agree with the `id` declared inside the directory's `workflow.json` - a push whose two ids disagree is refused. So to make your own version of an existing workflow, pull it, change the id in `workflow.json`, and push to the new id - or `clone` it, which does that in one command and publishes the copy immediately, with no draft stage. ## Built-ins are read-only The three built-in workflows cannot be edited: a push aimed at a built-in id is refused, so they never diverge from what DevThrottle ships, and they update with the Gateway itself. They can never be deleted either - deleting only archives a custom workflow, and its version history stays. To customize a built-in, clone it (or pull it into a new id) and change your copy. ## Turning one off A workflow can be switched off without being deleted. `disable` hides it from every session's briefing, stops new runs, and stops sessions from joining runs already underway; nothing is removed, and `enable` puts it back. ## Runs Each execution of a workflow is a **run**. `runs` lists them newest first, and `run` shows one in detail: the version it was pinned to, its lifecycle, its acceptance criteria, who took part, and the proof it produced. > **Tip:** Workflows are fleet-wide, so they are also how you make an improvement stick. Rather than telling one session to work differently, change the workflow: from each Director's next poll, newly started sessions see the new catalog entry, and every run that starts afterwards follows the new conduct. Nothing is retroactive - sessions already running keep the briefing they started with. ## Where to go next For a walk-through of writing your first one, see [Workflows: your named ways of working](https://devthrottle.com/docs/tutorials/workflows). For the roles a mission workflow staffs, see [Session roles and missions](https://devthrottle.com/docs/director/roles). For the rest of the command line, see [the command reference](https://devthrottle.com/docs/cli/reference). --- # Skills: the capabilities your agents reach for > A skill is a folder of instructions held on your Gateway, named in a session briefing and fetched only when an agent uses it. What a skill is, how it reaches the eight agents with first-class drivers, what the briefing does and does not carry, the Cockpit register, and the command surface for reading and authoring one. Part of the DevThrottle documentation, section "Gateway". Canonical HTML version: https://devthrottle.com/docs/gateway/skills Last updated: 2026-09-06 A skill is a **capability your agents reach for** - a folder of instructions telling an agent how to do one kind of job, held on your Gateway rather than copied onto each machine. A session starts with a short index of the library - a line per skill, its name and what it does - so it knows what the fleet can do without carrying any of it. An agent reads a skill's actual instructions only when it decides that skill is relevant to what you asked. It exists because the alternative is a file copied onto every machine by an installer, where fixing one word means a release - and where a withdrawn instruction keeps working from a leftover copy nobody remembered. > **Note:** Skills and [workflows](https://devthrottle.com/docs/gateway/workflows) are two lists on one shelf, and they answer different questions. A workflow governs how a whole job is run and who staffs it. A skill is one capability an agent picks up in the middle of a job - how to deploy this service, how to talk to that tool, the words this team uses. ## What a skill actually is A directory with a `SKILL.md` file at its root, plus whatever else it needs: reference notes, scripts, images, data files, whole subdirectories. That shape is not ours - it is the Agent Skills open standard, and every agent DevThrottle has a first-class driver for reads that same directory, byte for byte. The consequence is the single most useful fact about skills: **there is no per-agent format**. One skill works across all eight of the [first-class agents](https://devthrottle.com/docs/agents/supported) without being converted, adapted or kept in duplicate. The only thing that differs between them is which folder the directory has to appear in, and DevThrottle handles that. > **Note:** The custom agent is the exception, and it is a plain one. That ninth driver points DevThrottle at any command line of your own, and a raw command line has no skills mechanism - no folder it reads, no convention for finding one. So there is nowhere to put a skill for such a session and DevThrottle puts none there. The library is still on that machine and still readable from the command line below; it is the automatic placement that does not apply. A skill can carry real programs, not only prose. Files may be binary, and a file can be marked executable so a script inside a skill actually runs. ## The catalog Open **Skills** in the Cockpit, beside Workflows. Each row is one skill: its id and name, the one line agents see in the briefing, whether it is on, which version is live, whether it is a built-in or one of yours, its first few triggers, and how many supporting files it carries. **Read** shows you exactly what the skill tells an agent. The page also holds the two controls that matter. The switch turns a skill **off** - left out of every briefing and its fetch refused, with nothing deleted and the flip instant both ways. And **Clone** copies a skill into one of your own, which is the way to customize a built-in. ## Drafts are private; publishing is the deployment Anyone - and any agent - can author a skill. It is written as a **draft**, which no agent sees and no briefing names. Publishing makes it the live version at once: there is nothing to deploy, nothing to install, and nothing to restart on any machine. A typo fixed here reaches every connected machine at its next refresh, about a minute later. The one delay is at the edge. Each connected Director re-reads the catalog on a poll about every minute, so a session started in the first moments after a publish can still be briefed with the previous catalog. Reading the library directly with the commands below is never behind - those ask the Gateway live. Two people editing the same skill do not overwrite each other: an edit carries the hash of the version it was made against, and the Gateway refuses a write that is no longer current rather than losing the other author's work. ## How a skill reaches an agent Two separate things happen, and they are kept apart deliberately so that nothing to do with the network can delay a session starting. - **The session is told what exists.** The briefing carries one line per skill - the id and its one-line summary - and the instruction to fetch a skill in full only when about to use it. That block is all a session pays for, and because it is discoverability rather than the library itself, it is bounded: at most **forty** skills are listed, and beyond that the block says how many more there are and which command lists them all. A long summary is cut to keep every entry to one line. - **The skills themselves are put where the agent looks.** While DevThrottle runs it downloads every skill you have switched on and stores it on the machine; when a session starts, the stored skills are written into the folder that session's agent already reads. That second step never touches the network, so it cannot delay a launch - and if the Gateway is unreachable the session still starts, with whatever the last download brought down. On a machine where DevThrottle is running and reaching the Gateway, the practical result is that a session opens with skills at most about a minute old, and finds them the same way it finds any other skill. **What happens when it is not reaching the Gateway** is worth knowing, because it is not one behaviour but two. The skills on disk and the briefing index are refreshed separately and each keeps its own last successful download, so a machine that loses the Gateway goes on starting sessions with what it already has rather than with nothing. The index, though, is not kept indefinitely: once the copy on a machine is more than **twenty-four hours** old, no index is injected at all and sessions started there are told nothing about the library until a refresh succeeds. That is deliberate - the briefing is authored text reaching every session, and a skill you switched off a week ago must not keep being announced by a machine that has not heard since. Losing the index costs only discoverability: the commands below ask the Gateway live, so an agent that can reach it can always ask what the library holds. ## Where they land on your machine Each skill is written exactly **once**, into `~/.agents/skills` - the shared folder the agent ecosystem standardised on. Six of the eight first-class agents scan that path natively and need no configuration whatsoever. Claude Code does not read it, and Cursor documents only its own folder, so each of those two gets one shortcut per skill inside its own directory pointing at that same single copy. On Windows the shortcut is a directory junction and elsewhere an ordinary symbolic link; neither needs administrator rights. One real copy is the point: there is nothing that can quietly drift out of step with itself. Skills are written under your home folder and never into the repository you are working in, so they never show up as untracked files in your working trees - which also means a downloaded skill is visible to every session on that machine, including sessions DevThrottle did not start. ## Your own skills are never touched The library is an *additional* source of skills, not a replacement. A skill of your own on a machine, or in a repository, keeps working exactly as it did - and if one of yours has the same name as one from the library, **yours wins**. DevThrottle leaves it alone and records that it did. Everything DevThrottle writes is marked as its own, and it only ever changes or removes its own entries. > **Note:** Switching a skill off actually removes it. Each launch reconciles what is on the machine against what the Gateway is currently serving, rather than adding to what is already there - so a skill you switch off, archive or delete is gone from disk the next time a session starts. A withdrawn instruction that keeps working from a leftover file on one machine is precisely the failure a central library exists to prevent. ## Reading and authoring from the command line The Cockpit is one window onto the library; the command line is the other, and it is the one your sessions use. **Reading** ``` cc-devthrottle skill list # every skill the fleet holds, one line each cc-devthrottle skill show # one skill's details, without its body cc-devthrottle skill get # its full instructions - read this to USE it cc-devthrottle skill versions # version history, newest first ``` `get` is the one an agent actually calls, at the moment it is about to use the skill. It prints the instructions to follow, writes any supporting files onto the machine and prints their paths, and fails loudly if the Gateway cannot be reached rather than letting an agent proceed from memory. **Authoring** ``` cc-devthrottle skill pull --dir # skill.json + SKILL.md + its files cc-devthrottle skill push --dir # upload as a DRAFT; no agent sees it yet cc-devthrottle skill publish # the draft becomes live, fleet-wide cc-devthrottle skill clone # copy one into a skill of your own ``` `--dir` is required on both `pull` and `push`. `push` takes `--note` for a line on what changed. There are two more verbs for the owner's switch, `disable` and `enable`, and `delete`, which archives a skill of your own - its versions stay readable by explicit version, and a built-in can never be deleted at all. ## Built-ins are read-only The skills DevThrottle ships are marked built-in and cannot be edited, so they never diverge from what we shipped and they update with the Gateway itself. The Cockpit does not even offer you a Files button on one, because the write would be refused and a control that cannot work reads as broken. To make a built-in yours, clone it - the copy is published immediately, fully editable, and independent of the original. ## Adding one In the Cockpit, **Add skill** asks for two things: a name, and one line saying what it does. That line matters more than its length suggests - it is the only part of the skill a session pays for, and the only thing an agent has to go on when deciding whether to fetch the rest. Adding it creates a draft and hands you the exact prompt to give an agent, which is the intended way to write one: your agents do the authoring, pulling the draft into a working directory, writing its `SKILL.md` and its triggers, adding any supporting files, then pushing and publishing. > **Tip:** Skills are fleet-wide, so they are also how you make a fix stick. When an agent gets something wrong in a way that will recur, do not correct that one session - put the correction in the skill. From each connected Director's next poll, every session it starts has it. ## If a skill does not appear - **Is DevThrottle running and connected to the Gateway?** The download happens in DevThrottle, so a machine where it is not running gets nothing new. - **Is the skill switched on?** Only enabled skills are downloaded. - **Did the session start before the skill was published?** Skills are placed at session start, out of what that machine has already downloaded. Give that machine its next refresh - about a minute - then start a new session. - **Has the machine been cut off from the Gateway for a day?** Past twenty-four hours it stops injecting an index at all, so sessions there are briefed with no skills until it reconnects and a refresh succeeds. `cc-devthrottle skill list` reads the Gateway directly and is never the thing that is behind. - **Are there more than forty skills switched on?** The briefing lists forty and counts the rest. A skill past that line is in the library and fetchable by id - it simply is not named in the block. - **Is it a custom-agent session?** A user-supplied command line has no skills folder, so nothing is placed for it. Use the commands below. - **Do you already have a skill of that name?** Yours wins, deliberately. Rename one of them if you want both. ## Where to go next For the ways of working a whole job follows, see [Workflows](https://devthrottle.com/docs/gateway/workflows). For which agents DevThrottle runs, see [supported coding agents](https://devthrottle.com/docs/agents/supported). For the rest of the command line, see [the command reference](https://devthrottle.com/docs/cli/reference). --- # Running agents on more than one machine > One Gateway, many Directors: add a second computer to your fleet, watch it on the Directors page and Fleet Map, and start sessions on it from your phone or with cc-devthrottle session spawn. Part of the DevThrottle documentation, section "Gateway". Canonical HTML version: https://devthrottle.com/docs/gateway/machines Last updated: 2026-08-07 A fleet is one [Gateway](https://devthrottle.com/docs/gateway/overview) plus every Director that reports to it - and Directors can live on different computers. The recommended default is the hosted Gateway, run for you; a self-hosted Gateway plays the same role. Every machine's Director dials out to that one Gateway, the [Fleet Map](https://devthrottle.com/docs/cockpit/fleet-map) shows it all as one place, and your phone reaches everything through it. ## Adding another machine 1. **Install DevThrottle on it** The second machine runs the same app - [install](https://devthrottle.com/docs/install) as usual. 2. **Enroll it with your Gateway** The setup wizard's gateway step does the joining. On the hosted gateway, keep the **Hosted gateway** card and sign in with the same account - the machine is enrolled the moment the wizard shows Connected. If you run your own gateway, pick **Self-hosted gateway**: it scans for gateways it can reach, and takes a typed address when the scan cannot see yours. Either way, the new machine's Director dials out to the Gateway and keeps that connection open. Directors never accept an inbound connection and never talk to each other - on a normal install [nothing on your machine listens](https://devthrottle.com/docs/gateway/portless). The one exception is a self-hosted Gateway: the machine you install it on listens on a port (7878) and must be reachable at its address. The hosted Gateway involves no listener of yours at all. 3. **Watch it appear** The new machine's Director registers with the Gateway and shows up on the Cockpit's **Directors** page and the Fleet Map, with its sessions in the shared roster. Health is shown per Director, not per machine: a healthy Director wears no badge, one answering late shows **Wobbly**, an unreachable one shows **Offline**, and one shut down on purpose reads **Not running**. An offline Director dims in place and never disappears - its last-known sessions stay listed, dated - and the fleet calls a whole machine unreachable only when every Director on it is. ## Starting work on the other machine From anywhere in the fleet, a session can be started on a specific machine: - From the phone: the [New session](https://devthrottle.com/docs/mobile/sessions) screen lists every machine - pick one, pick a repo. - From a terminal or an agent: `cc-devthrottle session spawn --machine `. If no Director is running there, the Gateway asks that machine's launcher to start one - and if the machine is unreachable you get a clear error, never a silent local fallback. > **Tip:** Nothing needs starting by hand before you can aim work at a machine. Each machine's launcher starts when you log in - a per-user entry, never a machine-wide service - so a logged-in machine can take a session even when its Director is not yet running. > **Note:** Advanced: a small helper (cc-launcher) can register with the Gateway so it can start, stop, or restart that machine's Director remotely over the Gateway's API - with the main build and protected slots guarded behind an explicit human confirmation. There is no button for this yet; it is an API-level capability for people scripting their fleet. --- # Sessions talking to sessions > Agents message, ask, and spawn each other - with unforgeable sender stamps, team-only broadcasts by default, human-granted fleet-wide sends, and rate limits. Part of the DevThrottle documentation, section "Gateway". Canonical HTML version: https://devthrottle.com/docs/gateway/fleet-messaging Last updated: 2026-09-06 Agents in a DevThrottle fleet can talk to each other: hand work sideways, ask a teammate a question and wait for the answer, or spin up a new session - on this machine or another one. That is what makes [missions](https://devthrottle.com/docs/director/roles) work: an architect that plans, a manager that supervises, workers that build, all coordinating themselves. ## The verbs **From inside any session** ``` cc-devthrottle message send "message" cc-devthrottle message ask "question" cc-devthrottle session spawn --machine ``` - **send** - deliver a one-way message. Target one session by name or a short id, or your whole team with `all`. - **ask** - ask ONE session a question and wait for its answer (up to two minutes by default). - **spawn** - open a new session, locally or on another machine. A session spawned by another session defaults to a [Worker](https://devthrottle.com/docs/director/roles) supervised by its spawner. Every delivered message arrives stamped with who sent it - the session's name, machine, and id - so a receiving agent always knows who is talking, and the stamp cannot be forged by the sender. ## Between a session and the one driving it The three verbs above are how any session reaches any other. Supervision is a narrower relationship and it has two verbs of its own: a spawned session is a Worker, and the session that spawned it is the one driving it. **From inside any session** ``` cc-devthrottle session raise "what you are blocked on" cc-devthrottle session raise --clear cc-devthrottle session workers ``` - **raise** - a supervised session puts its hand up to the session driving it. It is quiet toward you by construction, so this is the channel it has instead. Raise it only while you are *still working* and have hit something you cannot decide inside your mandate: an ambiguous requirement, an irreversible step, a real design fork, an authorisation you do not hold. Not for progress, and not for "I finished" - stopping already says that. A raised hand lowers itself when that session's turn ends, and `--clear` takes it down once the decision is answered. - **workers** - the other side of it: one line listing the sessions you are driving, what state each is in, and what any of them is blocked on. A manager learns what its workers are doing by reading them, not by being messaged "notice me". With nobody under you it simply says so. ## The safety rails A message interrupts the receiving agent, so messaging is deliberately fenced: - **Your team by default.** `send all` reaches only your own team - your mission's sessions, or for a solo session, the sessions in the same repository on the same machine. - **The whole fleet needs a human.** A genuine fleet-wide broadcast requires `--everyone` plus a human-issued grant and a written `--reason`. Grants expire after ten minutes and are logged. An agent cannot mint its own grant. - **Rate limits and dedupe.** Each sender is throttled (a handful of broadcasts per minute) and duplicate messages are refused - a runaway agent cannot storm the fleet, even inside its own team. - **Nothing drops silently.** An unknown target, an unreachable machine, or a refused broadcast comes back as a clear error to the sender. > **Warning:** If an agent asks you for a fleet-wide broadcast, treat it like a production action: issue the grant only when interrupting every agent on every machine is genuinely warranted, and say why - the reason is logged. > **Note:** Under the hood these verbs go through the Gateway, carrying the calling session's own key: the Gateway stamps the sender, resolves the team, and reaches the owning Director down that Director's outbound connection. It is the same surface your own scripts use - see [the Control API](https://devthrottle.com/docs/gateway/control-api). --- # Control API > Drive the fleet from code through the Gateway - cc-devthrottle with the session's own key. There is no local port on the Director, by design. Part of the DevThrottle documentation, section "Gateway". Canonical HTML version: https://devthrottle.com/docs/gateway/control-api Last updated: 2026-08-07 Everything the Director does, a script can still do - but the door is the [Gateway](https://devthrottle.com/docs/gateway/overview), not the Director. The Director has no local HTTP interface at all: nothing on your machine listens, and there is no port to find or firewall to configure. The supported way to drive the fleet from code is the `cc-devthrottle` command line, which talks to the Gateway using the calling session's own key. ## There is no local port, on purpose Earlier releases ran a REST listener inside each Director on a loopback port. That listener is deleted - not moved, not hidden behind a setting. A Director dials *out* to the Gateway and keeps that connection open; everything that drives it, from your phone to another agent's command line, arrives down that outbound connection. A machine that listens on nothing has nothing exposed for anyone else to find, which is the same reasoning behind [connecting machines without opening a port](https://devthrottle.com/docs/gateway/portless). The one listener in the system is a *self-hosted* Gateway's own port (7878) on the machine you chose to run it on; with the hosted Gateway there is no listener of yours at all. ## The way in: the session's own key Every session launched by a Director attached to a Gateway is stamped with two environment variables, as a pair: `CC_GATEWAY_URL`, the Gateway this account is attached to, and `CC_GATEWAY_SESSION_KEY`, that session's own credential for it. The `cc-devthrottle` commands read the pair and just work - there is nothing to configure and no token of yours to paste into a script. A Director running local-only, with no Gateway configured, stamps no credential, and the fleet commands say so rather than guessing. **The reads, from inside any session** ``` cc-devthrottle session list # every session in the fleet, as text cc-devthrottle session whoami # who am I - id, name, machine, repository cc-devthrottle setup status # is this machine wired up correctly cc-devthrottle schedule list # what the Gateway will run without you ``` The key is scoped, not account-wide: it is bound to the one session it was minted for and to your account, and the Gateway allow-lists what it may call. An agent may do fleet work - read the roster, message and spawn sessions, take missions, read and publish skills and workflows, change settings. It may not touch admission or identity: no sign-in, no device enrollment, no billing. The line the product draws is that an agent may change how the product behaves, not who is allowed in. ## Discover what a script may call The command line describes itself in JSON, so a program - or an agent - does not have to parse help text: **Machine-readable catalog of every action** ``` cc-devthrottle actions --json ``` Each entry carries the command, its arguments, and a `mutatesState` flag, so a cautious script can stick to the reads. For the human-readable version of the same surface, see [the tool reference](https://devthrottle.com/docs/cli/reference). > **Note:** No Gateway connection means no fleet tooling - that is the designed trade, not a gap. The commands never fall back to a local path, because there is no local path to fall back to. A machine with no Gateway attached gets a clear failure naming the fix: attach the machine to a Gateway, hosted or [self-hosted](https://devthrottle.com/docs/gateway/overview). ## If you remember the local Control API For readers of earlier versions of this page, what each piece became: - **Ports 7879-7898 on 127.0.0.1, and `GET /healthz` discovery.** Gone. Nothing in the Director listens, so there is nothing to scan for. - **Session listing, creating, prompting, queueing, interrupting, closing.** The Gateway's agent surface, via `cc-devthrottle` - `session list`, `session spawn`, `message send`, and the rest of [fleet messaging](https://devthrottle.com/docs/gateway/fleet-messaging). - **The `CC_DIRECTOR_API` and `CC_DIRECTOR_TOKEN` variables.** Gone. A session's environment carries `CC_SESSION_ID`, `CC_DIRECTOR_ID`, and the Gateway pair described above. - **Scheduling against the local API.** The Gateway's [built-in scheduler](https://devthrottle.com/docs/gateway/cron), which starts sessions on your machines through the same outbound connections. > **Tip:** If an old script of yours probes `127.0.0.1:7879`, it is not misconfigured - it is calling a surface that no longer exists. Port it to the commands above; the reads take one line each. ## Next To see this used end to end, follow [Driving DevThrottle from a script](https://devthrottle.com/docs/tutorials/scripting). For sessions driving each other, [fleet messaging](https://devthrottle.com/docs/gateway/fleet-messaging). For the hosted model API - a different thing from fleet control - [the DevThrottle API](https://devthrottle.com/docs/api/overview). --- # The Cockpit > The same fleet in any browser - watch and answer agents away from the desktop app, with the full controls, served by your own Gateway. Part of the DevThrottle documentation, section "Cockpit (browser)". Canonical HTML version: https://devthrottle.com/docs/cockpit/overview Last updated: 2026-09-06 The Cockpit is your [Gateway](https://devthrottle.com/docs/gateway/overview)'s fleet interface: the same sessions the [Director](https://devthrottle.com/docs/director/overview) drives on each of your machines - every session card, every terminal, every control - in a browser tab you can open from any machine. There is nothing to install: it is a web address, you sign in, and you are looking at your control room. ## The same fleet, not a status page The Cockpit is not a stripped-down dashboard. You can start new sessions, answer an agent that is waiting on you, redirect one that wandered, and stop one that should not be running - the controls you have at your desk, in a tab. If you can do it on the Director, the Cockpit is meant to let you do it from anywhere. ## One place for every machine If you run agents on more than one computer, the Cockpit is where they meet: every session on every machine you own shows up in one place, so you stop remoting into each box to check on it. ## Signing in Signing in does more than unlock the page: it **enrols this browser as a device** on your account. Every real screen needs that enrolment, and a browser that does not have it is sent to the sign-in screen and then back to whatever it was trying to open. A device you no longer use can be revoked later - see [your devices](https://devthrottle.com/docs/account/devices). ## How the Cockpit is laid out Down the left is a **rail** of destinations, and it is the whole product: everything the Cockpit can do is one click down that list. The Cockpit opens on the **Fleet Map**, so the first thing you see is the whole fleet rather than an empty prompt. Three of them are where the work happens, and they have pages of their own here: - [Sessions](https://devthrottle.com/docs/cockpit/sessions) - the rail of every session in the fleet, each with a short session number, and the page for the one you pick. See also [working in a session](https://devthrottle.com/docs/cockpit/session-view). - [Fleet Map](https://devthrottle.com/docs/cockpit/fleet-map) - the whole fleet drawn as a map, with eight ways to group it. - [Assistant](https://devthrottle.com/docs/cockpit/assistant) - a conversation with the whole fleet, tied to no session. The rest of the rail is one entry per capability, and each is documented where that capability lives rather than twice: - **History** - what was worked on over a range you pick, grouped by repository and day. The walkthrough is [what did I get done this week](https://devthrottle.com/docs/tutorials/weekly-review). - **Directors** - the registry of the Directors in the fleet, and one Director in detail. See [machines and Directors](https://devthrottle.com/docs/gateway/machines). - **Schedule** - work that runs on a timetable. See [scheduled work](https://devthrottle.com/docs/gateway/cron). - **Workflows** - the shapes of work your fleet knows how to run. See [workflows](https://devthrottle.com/docs/gateway/workflows). - **Skills** - the capabilities your agents reach for, held on the Gateway. See [skills](https://devthrottle.com/docs/gateway/skills). - **Dictionary** - the words you want heard your way. See [your dictionary](https://devthrottle.com/docs/voice/dictionary). - **Voice Recorder** and **Transcription** - recording and transcribing, and the health of it over time. See [Voice](https://devthrottle.com/docs/voice/overview). - **Network** - how well this Gateway and its machines are reaching each other. See [network and diagnostics](https://devthrottle.com/docs/gateway/network). Pinned to the bottom are the entries about you and this app rather than about the fleet: [Account](https://devthrottle.com/docs/account/overview), **Phone** (the code and address for [pairing a phone](https://devthrottle.com/docs/mobile/pairing)), [Your Throttle](https://devthrottle.com/docs/account/usage), **Settings**, **About**, and **Help** - which is the one item that leaves the app, and lands here. ## Where things actually run The Cockpit is served by your Gateway - the hosted Gateway at its public web address, or a self-hosted one on your own machine. The sessions themselves run in the Director on each of your machines; the Gateway brings them together, and views - browser and phone - connect through it. Start a session from the Cockpit and it runs on whichever machine you picked, not in the browser and not on the Gateway. > **Note:** Closing the Cockpit tab never stops an agent. Views come and go; the agents run in the Director on your machine. See [keeping agents running](https://devthrottle.com/docs/gateway/lifecycle). ## Where to go next - [Answering agents remotely](https://devthrottle.com/docs/cockpit/remote) - the away-from-your-desk flow, step by step. - [DevThrottle on mobile](https://devthrottle.com/docs/mobile/overview) - the same idea, in your pocket, with a silent dot on the app icon when a session needs you once you have turned notifications on. --- # The session rail > The list down the left of the Cockpit - every session in the fleet with a short session number, at-a-glance attention coloring, the My order and Attention first ordering, the New session picker, and the session menu. Part of the DevThrottle documentation, section "Cockpit (browser)". Canonical HTML version: https://devthrottle.com/docs/cockpit/sessions Last updated: 2026-09-16 The left side of the [Cockpit](https://devthrottle.com/docs/cockpit/overview) is the session rail: a single scrollable list of the sessions your [Gateway](https://devthrottle.com/docs/gateway/overview) holds - every session on every [Director](https://devthrottle.com/docs/director/overview) attached to it, whichever machine that Director runs on - in one column. It is how you find the session you want and see, at a glance, which one needs you. ![The Cockpit session rail listing three sessions on SOREN_NORTH, each showing Needs you, a started time, open and idle timers, a turn count, and a yellow uncommitted-changes badge reading 4 chg, 2 chg and 3 chg](https://devthrottle.com/docs/screenshots/cockpit/session-rail.png) ## Session numbers Every card carries a short **session number** - a small badge like `102` or `104`. That number is the name people actually use to refer to a session out loud: in a note, in a message to a teammate, or by voice. It is stable and short on purpose, so "take a look at 104" is unambiguous. The same number shows on the card in the rail and on the card in the [Fleet Map](https://devthrottle.com/docs/cockpit/fleet-map), so a session reads the same everywhere you meet it. ## Reading a card Cards are built to be scanned. The session name wraps and reads in full rather than being clipped, and the card grows as the session has more to report - every line under the name appears only when there is something to put in it, so a quiet session stays short and a busy one is taller. Under the name is the status line, and under that the supervision timers. Two visual states matter most: - **Selected.** The session you are currently looking at is clearly marked so you never lose your place as the list updates. - **Needs you.** A session waiting on an answer is colored red, and that attention color is kept deliberately distinct from the selected state - a card can be selected, or waiting, or both, and you can always tell which. A short timer ("just now", "waiting 8m") tells you how long it has been stuck. The status line is not the Cockpit's own reading of the session. The Gateway decides the state, its colour and its words, and every surface renders that one verdict - which is why the rail, your phone and the Director never disagree about a session. For the vocabulary itself, see [session cards and states](https://devthrottle.com/docs/director/sessions), or click **What do the colours mean?** under the ordering toggle for a short legend of every colour, read from the Gateway. ![The Cockpit's What the colours mean panel: eleven rows, each a coloured dot, a name, whether it asks for you and one sentence - Needs you, Working, Done, Carrying on, Being read, Ready, Transcribing, Supervised, Snoozed or exited, Crashed and Magenta - with a note that Done and Carrying on need the Wingman's verdicts switched on](https://devthrottle.com/docs/screenshots/cockpit/colour-legend.png) ### The supervision line Under the status line, a card carries the facts you would otherwise have to open the session to learn: when it **started**, how long it has been **open**, how long it has been **idle**, and how many **turns** it has taken. They tick live. A figure the session's Director does not report is left out rather than shown as zero, so a missing number never reads as "nothing happened". ### The badges Along the bottom of a card sits a row of small tags, each present only when it has something to say: - **not delivered** - in red, and always first. It means a message you sent did not reach the agent. Every other tag describes what the session is doing; this is the only one that says something was lost, so it leads. Hover it for the Gateway's own account of what happened. - **N chg** - uncommitted changes in the session's working tree. It is the same number the Director's own rail shows - measured once, on the Director - and the badge is absent, never "0 chg", when the tree is clean or the count is unknown. See [source control and history](https://devthrottle.com/docs/director/source-control) for what the count means and its limits. - **The model** the session is running. It is the fact your fleet's cost and quality turn on, and until it appeared here it was visible nowhere while a session was alive. The chip is muted when there is no model to name - and the words say which kind of absence it is, because "this session has not finished a turn yet" and "this agent never reports a model" are different answers. - **voice** when the session is narrating (see [Wingman](https://devthrottle.com/docs/cockpit/session-view)), **winding down** when it is on its way out, a **wakes in** countdown while it is snoozed, and **Snooze ended** when that timer has fired. ## Turning voice on for the whole fleet Directly under the ordering toggle is one button for the whole roster: **Turn on voice for all N sessions** - and, once any session is narrating, **Turn voice off for all**. It is the control for walking away from your desk and taking the fleet with you, without opening each session. It reports what it did: how many sessions changed, and how many were skipped because the computer they run on is offline. A machine being unreachable never fails the rest of the batch. ## Ordering: My order vs Attention first A toggle at the top of the rail decides how the list is sorted: - **My order** is the default - a stable, manual order that does not rearrange itself while you work. The list is grouped under a heading per Director, written as the computer and the port, so several Directors on one machine are told apart. - **Attention first** regroups the whole rail into headed groups - **Needs you**, **Working** and **Snoozed** - with the longest-waiting session at the top of the first, so when several are waiting you can work straight down the list. Under the sessions that need you, a **Done or carrying on** band lists the ones the Wingman judged finished or carrying on by themselves: they stay in view, and they are not counted as needing you. A group with nothing in it is not shown. > **Tip:** Leave the rail on **My order** for day-to-day work so the list stays predictable, and flip to **Attention first** when you come back to a busy fleet and want to clear the waiting sessions in one pass. ## Starting a new session The **+ New session** button at the top of the rail opens a picker for starting a session anywhere in the fleet. It has three steps: 1. **Machine** - which computer runs it. The most recently seen is already chosen, so the rest of the dialog can load. 2. **Repository** - one of that machine's recent repositories, or a path you type. 3. **Launch options** - the **agent**, chosen from the agents that machine has configured and enabled, and the **permission mode**: **Skip permission prompts** or **Ask for permissions**. A line at the bottom reads back how the session will start: the agent, the model it will use, and the permission choice. Then **Create session**, and it starts on that machine. You do not have to be sitting at that computer. Your agent and permission choices are remembered for next time. > **Warning:** **Skip permission prompts** lets the agent act without stopping to ask you first. It is the quicker way to work and it is the default, but it is a real choice about how much rope the agent has in that repository - make it deliberately. > **Note:** There is no model picker, on purpose. The model comes from the chosen agent's own configured default - see [coding agents and models](https://devthrottle.com/docs/director/agents) - so the model is settled where the agent is configured rather than guessed at each launch. ## The session menu Every card has a three-dot **session menu** (the same menu also sits at the top of the open session page). It holds the actions that manage the session itself, rather than steer the agent: - **Rename** - give the session a clearer name. - **Snooze** / **Unsnooze** - quiet a session you are not working on right now, and bring it back when you are. **Snooze for** offers specific lengths when you want something other than your default. - **Handover info** - the session's identity block: its name, session id, repository, Director, machine, and version. It is what you copy when you hand a session off or ask for help with it. - **Close session** - end the session for good. This one asks you to confirm first, because it cannot be undone. > **Note:** Closing the Cockpit tab is not the same as closing a session. The tab is just a view; the agents keep running in the Director on their machine. See [keeping agents running](https://devthrottle.com/docs/gateway/lifecycle). ## Where to go next - [Working in a session](https://devthrottle.com/docs/cockpit/session-view) - the terminal, chat, and voice views, and the controls for steering an agent. - [The Fleet Map](https://devthrottle.com/docs/cockpit/fleet-map) - the same fleet seen as a map instead of a list. --- # Working in a session > The session page in the Cockpit: the Terminal, Chat, Voice, and Source Control tabs, the action bar, the message box with Send, Speak, Queue, and Attach, and the dock with the prompt queue and screenshots. Part of the DevThrottle documentation, section "Cockpit (browser)". Canonical HTML version: https://devthrottle.com/docs/cockpit/session-view Last updated: 2026-09-06 Select a session in the [rail](https://devthrottle.com/docs/cockpit/sessions) and its page opens on the right. This is where you watch what an agent is doing and steer it - the same controls you have on the desktop [Director](https://devthrottle.com/docs/director/overview), in a browser tab. The page has four tabs across the top, an action bar, and a message box at the bottom. ## Four views of one session The **Terminal**, **Chat**, **Voice**, and **Source Control** tabs are four views of the same live session. Switching tabs never disconnects the session: the live connection stays open in the background, so you can move between them without dropping a beat. ### Terminal The Terminal tab is the live terminal, mirrored exactly as it looks on the machine running the agent - the raw, plain terminal, character for character. It is the ground truth: whatever the agent's command-line tool prints, you see here. It takes input too: click into it and your keystrokes are forwarded to that same terminal, just as if you were typing at the desktop. ### Chat The Chat tab is the same conversation, cleaned up and made readable: the agent's replies and your prompts as chat bubbles, with Markdown rendered so lists, code, and emphasis look right. It updates live as the agent works. A **Show:** filter lets you reveal the parts that are hidden by default - **Tool calls**, **Results**, and **Thinking** - so you can read just the conversation, or open up every step the agent took. What you are reading is the copy the machine running the agent pushed up to your Gateway as each turn finished - which is why a conversation you have already had stays readable when that computer is briefly unreachable. Two things follow, and you will see both on screen. A conversation that has stopped being added to carries a line above it saying so, and why - so an hour-old conversation never looks live. And when there is nothing to show, the Gateway writes the reason rather than always telling you to wait: a session that has not spoken yet, an agent that keeps no history at all, and a computer that is offline are different answers, and only one of them means something is coming. ### Voice The Voice tab is **Wingman** - a hands-free way to keep up with a session without watching the screen. While voice is off for this session the tab offers one button, **Switch to voice mode**. Turn it on and every completed turn with a written answer in it is sent for narration - Wingman summarizes what the agent decided and did in plain language, so you can step away and still follow along. A clip is not guaranteed: when one cannot be made, the tab says which reason it was rather than going quiet, and [Voice on your phone](https://devthrottle.com/docs/mobile/voice) lists those answers in full. When a turn is ready, a small player lets you play and pause, restart, or seek through it, and a **Respond** button lets you answer back by voice instead of typing. While a narration is being made, the tab shows what the Gateway says about it and how long it has been waiting - and it stops promising. After three minutes with nothing produced it says so plainly, with the elapsed time, instead of leaving a spinner up forever. The Gateway keeps trying; what ends is the promise, not the effort. When voice cannot happen, the tab names the reason instead of showing a symptom: **Nothing to read aloud** (the session is waiting on a prompt or a menu, not a text answer), **Voice service down**, **Voice needs credit**, and **Update DevThrottle** when the computer running the session is too old to send its conversation up. A **Generate narration now** button appears only when the Gateway says generating one could actually help - never beside a reason it would not. > **Note:** A clip occasionally arrives with a short notice that it was produced by a backup voice. It is a normal, playable narration; the notice is there so a voice that sounds different does not read as a fault. > **Tip:** Wingman pairs well with the [mobile app](https://devthrottle.com/docs/mobile/overview). Turn notifications on in the app and your phone shows a silent dot on the app icon when a session needs you - the Gateway checks every eight seconds. It is off until you turn it on, and on a phone it has to be the installed app rather than a browser window. Then listen to what the agent did and answer by voice from wherever you are. ### Source Control The Source Control tab is a read-only view of the session's repository. Click a file and its path is inserted into the message box, ready for your next instruction about it. For reviewing what an agent changed in depth, see [Source control and history](https://devthrottle.com/docs/director/source-control). ## The action bar Below the session sits a row of controls for the agent itself: - **Stop** - halt what the agent is doing now. - **Interrupt** - cut in while it is working to add or change direction. - **Compact** - summarize the conversation in place, freeing up the agent's context window while keeping what the session has learned. - **Clear context** - start the conversation fresh without closing the session. - **History** - read back the earlier conversation for this session. **Compact** and **Clear context** both ask before they act, and the two questions are worded unalike on purpose: compacting keeps what the session has learned, clearing destroys the conversation. Two confirmations that read the same would train one reflex for two opposite outcomes. Compacting can take a minute or two, and the button says so while it runs. These are the same steering controls documented for the Director under [starting and steering agents](https://devthrottle.com/docs/director/steering) - they behave the same way from the Cockpit. Each button appears only when the session's coding agent supports that action, so a session may not show all of them. ## The message box At the very bottom is the composer, where you talk to the agent. It has four actions: - **Send** - send your message to the agent now (Ctrl+Enter also sends). - **Speak** - open the dictation dialog and talk your message straight into the box instead of typing it. This is the same dictation used everywhere in DevThrottle, and it runs through your Gateway on one shared path - so it behaves the same on desktop, in the browser, and on your phone. See [Voice](https://devthrottle.com/docs/voice/overview). - **Queue** - add the message to the session's prompt queue instead of sending it right away (Ctrl+Shift+Enter queues). It waits there until you send it. - **Attach** - add an image. The Cockpit uploads it from the device you are on to the machine the session runs on, saves it there, and inserts the saved path into your message so the agent can open it. **Pasting** an image into the box and **dragging** one onto it do exactly the same thing. ## The dock On the right of the session page is a dock with two panels: - **Queue** - the session's prompt queue: the prompts you have queued, in order. Each waits there until you send it. - **Screenshots** - a gallery of the image files in the screenshots folder on the machine this session runs on. It lists six types - `.png`, `.jpg`, `.jpeg`, `.bmp`, `.gif` and `.webp` - so a file of any other type sits in that folder without appearing here. ## The session menu The three-dot menu at the top right of the session page is the same [session menu](https://devthrottle.com/docs/cockpit/sessions) that sits on each rail card: Rename, **Snooze** or **Unsnooze**, **Snooze for** (pick a length instead of your default), Handover info, and Close session. > **Warning:** The **Handover info** dialog is filled in live: the Gateway asks the Director that owns the session, and the Director answers from the running session itself. So the dialog depends on that Director being connected - if it is offline, or running a version too old to answer, the dialog reports an error instead of showing stale details. The dialog does not retry on its own: once the Director is back, close it and choose **Handover info** again. > **Note:** Everything you do here executes on the machine the session lives on, not on the device in your hand. The Cockpit is a view onto that machine, served by your own Gateway. ## Where to go next - [The Fleet Map](https://devthrottle.com/docs/cockpit/fleet-map) - step back and see the whole fleet as a map. - [Answering agents remotely](https://devthrottle.com/docs/cockpit/remote) - the practical away-from-your-desk flow. --- # The Fleet Map > The whole fleet drawn as a map: a Gateway node branching to panels of session cards, the eight groupings from By machine to By model to Missions, the title search, and the per-Director Wobbly, Offline, and Not running states. Part of the DevThrottle documentation, section "Cockpit (browser)". Canonical HTML version: https://devthrottle.com/docs/cockpit/fleet-map Last updated: 2026-09-06 The **Fleet Map** is the whole fleet seen at once. Where the [rail](https://devthrottle.com/docs/cockpit/sessions) is a list, the Fleet Map is a picture: a canvas with a root **Gateway** node that branches out to panels of session cards, joined by connectors, each card carrying a status dot. It answers "what is my whole fleet doing right now" in one look. Open it from **Fleet Map** in the left navigation. ## Eight ways to group the fleet A row of pivots at the top right re-groups the same sessions along different lines - pick the one that matches the question you are asking. The map remembers your choice, so it reopens on whatever grouping you used last. - **By machine** - sessions grouped under the computer they run on, then under each Director on it. Best for "what is running on that box". A Director with no sessions still shows: as a free slot when it is reachable, or labeled as one that is not running or cannot be reached when it is not. - **By director** - one panel per Director across the fleet, headed by the Director's name with its machine underneath. Best when one machine runs several Directors and you want them side by side. - **By repository** - sessions grouped by the repository they are working in, so every worktree and clone of one repository rolls up together. Best for "who is touching this project". - **By working tree** - sessions grouped by the on-disk checkout folder, so each worktree stands alone. The companion question to By repository: not "which project" but "which checkout". - **By agent** - sessions grouped by which coding agent is driving them. Best for "where am I running Claude Code versus another agent". - **By model** - sessions grouped by the model each one is actually running, one step below By agent: not "which tool" but "which brain in that tool". A session whose model is not known sits in its own named lane rather than disappearing into the others. - **Fleet list** - a flat grid of every session, with a legend of the status colors. Best for a plain, complete inventory. - **Missions** - the fleet grouped into missions, each card carrying the why of the work, with sessions that belong to no mission counted as standalone. It is a wall of mission cards rather than a lane layout, and while it is active the count line at the top reads missions and standalone sessions instead of machines and repositories. Missions with no sessions on them right now are hidden by default - a finished mission keeps its card until somebody ends it, and a few of those push the live work off the screen. The header says how many are hidden and offers them back: **N empty hidden** shows them, **hide N empty** puts them away again, and the choice is remembered in that browser. It is a view preference and nothing more - hiding a mission does not end it. A card shows the same **session number** as the rail - when the session has been assigned one - so a session you know by number is just as easy to spot on the map. Clicking a card opens that session. > **Note:** Two of the pivots absorbed what used to be separate pages: the Fleet list replaces the old "Fleet" page, and Missions replaces the old left-rail Missions page. Both old addresses now lead here, so there is one home for the fleet overview. ## The tally in the header Beside the title the header counts what you are looking at: how many **sessions**, how many **machines** and how many **repos**, then **N working** in blue and **N needs you** in red. The needs-you figure is the number most people open this screen for; a count that is zero is left out rather than shown. On the **Missions** pivot the first three are replaced by the count of missions and of standalone sessions, and the working and needs-you figures stay. ## Finding a session The **Search titles** box filters the map to the sessions whose titles match what you type. It is case-insensitive. The sessions that do not match drop away - along with any panel that goes empty - and the ones that remain keep their order, so the map never reshuffles, though gaps close up as cards drop out. Clear the box to bring the whole fleet back. The box is there on every grouping except **Missions** - the missions view is not searchable, so the box hides while that pivot is active rather than sitting there dead. ## When a Director goes quiet A fleet spread across several computers will sometimes have a Director go quiet - a laptop that sleeps, a Wi-Fi blip. These states belong to the *Director*, not the machine: one machine can run several Directors, and one of them going quiet says nothing about the others. The Fleet Map is built so that a momentary miss does not make sessions blink out and the whole map reflow. Instead, a card changes appearance in place: - **Wobbly** - the Director's connection is up, but nothing recent has arrived, so what you are looking at is going stale. Its cards dim and read *last seen 20s ago*, but they hold their place, and the Director can still take a new session. Most of the time fresh data arrives and the cards return to normal on their own. - **Offline** - the Director's connection is down. It cannot be reached or acted on; its cards stay dimmed and read *last seen* with the age, so you can tell a real outage from a hiccup. - **Not running** - a Director that was shut down rather than lost. Its sessions are shown the same dimmed, dated way - they are the last thing it said - but the label says it is not running, so a deliberate shutdown never reads as an outage. A normal, reachable Director is simply undimmed cards - there is no "online" label to read. Because entries change in place rather than disappearing, the map stays steady and you never lose track of where a session was. > **Tip:** The literal **Wobbly**, **Offline**, and **Not running** words appear on the Fleet Map cards. On the [rail](https://devthrottle.com/docs/cockpit/sessions), the same states show more quietly - the row dims and shows the last-seen age, without the words. ## Where to go next - [Working in a session](https://devthrottle.com/docs/cockpit/session-view) - open a card and steer the agent. - [Answering agents remotely](https://devthrottle.com/docs/cockpit/remote) - the away-from-your- desk flow, and what reachability needs on your network. --- # The Assistant > A conversation with your whole fleet, tied to no session - in the Cockpit and on your phone. Ask what is open, what is stuck, which machines are on and what runs tonight; message, approve, snooze, start or close a session by asking. Part of the DevThrottle documentation, section "Cockpit (browser)". Canonical HTML version: https://devthrottle.com/docs/cockpit/assistant Last updated: 2026-09-06 The **Assistant** is a conversation with your whole fleet. Every other screen in DevThrottle is about one session or one list; this one is not tied to any session at all. You ask it questions - how many sessions are open, which ones are stuck, which machines are on, what runs tonight - and it answers from what your [Gateway](https://devthrottle.com/docs/gateway/overview) can actually see. It can act, too: message a session, approve one, snooze one, start one, or close one. ## Opening it - **In the [Cockpit](https://devthrottle.com/docs/cockpit/overview)** - **Assistant** in the left rail, third down, under the Fleet Map. - **On your [phone](https://devthrottle.com/docs/mobile/overview)** - **Assistant** in the menu, under New session. It is the same screen and the same conversation machine on both. What differs is the shape of the window, not what it can do. ## Chat or Voice One toggle decides how the screen behaves, and it sits big in the middle until you have asked something: - **Chat** - type your question and press Send (Enter sends; Shift+Enter starts a new line). Replies stay quiet on the screen. - **Voice** - press the microphone, speak, and press Send. Replies are read aloud, and a **Stop reading** button appears while one is playing. Speaking uses the same dictation dialog as everywhere else in DevThrottle - level bars, an elapsed timer, a Pause checkpoint, the transcript in a box you can edit, and Cancel or Send. In Chat mode it also offers **Insert**, which drops the dictated words into the message box so you can edit them before asking. See [Voice](https://devthrottle.com/docs/voice/overview). > **Note:** Turn-taking is a button on purpose. You press to speak and press Send when you are done - the Assistant never decides for itself that you have stopped talking, and there is no spoken keyword that ends your turn. ## What it can tell you The Assistant does not guess about your fleet. Ask it something about your sessions, your machines or your schedules and the answer is built from a live read rather than from memory, with the screen listing the steps it took above the reply: - **Your sessions** - the whole roster, with how many need you, what each one is doing, how long it has been waiting, how old it is, and how long it has been idle. - **One session in particular** - name it, or say its repository or its [session number](https://devthrottle.com/docs/cockpit/sessions), and it reads back what that session is doing. Whichever session you asked about becomes the one it assumes you mean next, so "snooze it" needs no second name. - **The next one that needs you** - it picks the session that has been waiting longest and focuses on that. - **What a session's voice would say** - the real narration for that session's last completed turn, read aloud rather than a summary of a summary. - **Your machines** - the computers running [Directors](https://devthrottle.com/docs/director/overview) right now, how recently the Gateway heard from each, and how many sessions each carries. - **What is scheduled** - the [scheduled jobs](https://devthrottle.com/docs/gateway/cron): what each one does, whether it is on, when it is next due, and how the last run went. ## What it can do - **Send a message** into a session, the way the Send button does. - **Approve** a session that is waiting - the equivalent of pressing Enter on the choice it has highlighted. - **Snooze** a session, with your usual snooze length. - **Switch a session to voice mode**, so it starts narrating its turns. - **Start a session** in a repository you name. If no machine in the fleet has a repository by that name, it says so rather than picking something close. - **Close a session** - and this one always stops and asks first. > **Warning:** Closing a session is permanent, so the Assistant never does it in the turn you asked. It names the session and the repository out loud, and the screen offers **Yes, do it** and **Cancel**. The confirmation always names what it is about to close, even when you did not name it yourself - so you hear the target before anything happens. ## What it will not do - **Money.** The Assistant does not read balances, costs, or spend totals. For what your fleet has been doing, see [Your Throttle](https://devthrottle.com/docs/account/usage). - **Type into a terminal.** It sends prompts and presses Enter; it does not drive a session's terminal. That is the [session page](https://devthrottle.com/docs/cockpit/session-view). - **Reach anything outside your fleet.** What it tells you about your fleet comes from your own sessions, machines and schedules and from nothing else. ## The conversation is per device The Assistant remembers the conversation on the Gateway, keyed to the device you are signed in on - so a follow-up question works, and your desk browser and your phone each keep their own thread. One question is answered at a time on a device, so two tabs cannot both act on the same pending confirmation. ## Choosing the model it thinks with **Settings** has an **Assistant** tab holding one choice: the model the Assistant thinks with. It is a setting for the account, not for a device, so the desk and your phone use the same one, and it applies from the next question. On the hosted Gateway the model catalog is not browsable, and the tab shows the model that is saved. > **Tip:** The Assistant has to call tools reliably to be useful - a question about your fleet is answered from a real read, not a guess - so pick for tool-calling and speed rather than for depth of reasoning. ## When something goes wrong Failures are shown, not swallowed. If the fleet cannot be read, the reason appears in the conversation. If an answer arrives but cannot be read aloud, you get the answer on screen and a separate line saying the reading failed - the reply is never lost to a voice problem. ## Where to go next - [The session rail](https://devthrottle.com/docs/cockpit/sessions) - the same fleet as a list, when you would rather look than ask. - [DevThrottle on mobile](https://devthrottle.com/docs/mobile/overview) - the surface this screen is most useful on. - [Voice](https://devthrottle.com/docs/voice/overview) - dictation, and how speaking works everywhere else in the product. --- # Answering agents remotely > Open the Cockpit from another machine, find the agent that is waiting, and answer it - plus what reachability needs on your network. Part of the DevThrottle documentation, section "Cockpit (browser)". Canonical HTML version: https://devthrottle.com/docs/cockpit/remote Last updated: 2026-09-06 The point of the [Cockpit](https://devthrottle.com/docs/cockpit/overview) is the moment you are not at your desk and an agent stops to ask a question. Instead of the work sitting idle until you get back, you open the Cockpit in whatever browser is in front of you, answer, and the agent keeps going. This page is that flow. ## Answering from another machine 1. **Open the Cockpit** From the Director, the Cockpit button in the toolbar asks your Gateway for the address and opens it in your default browser - use that the first time so you know the address. The address is your Gateway's: the hosted Gateway's public web address, or, if you self-host, your own machine on your own network. If it cannot open, it says so rather than opening the wrong thing: a **Cannot Open Cockpit** dialog appears when there is no address to open, or when the Gateway cannot be reached - that one offers **Retry**. 2. **Sign in** The Cockpit is yours, so it asks you to prove it. Sign in with your DevThrottle account; the browser stays signed in afterwards. Signing in also enrols this browser as a device on your account, and a device can be revoked later - see [your devices](https://devthrottle.com/docs/account/devices). 3. **Find the card that needs you** The Cockpit reads exactly like the desktop: session cards with status colors. Switch the ordering to Attention first and the sessions waiting on you come to the top, under a Needs you heading with its own count. Click the waiting card. 4. **Answer in the message box** Type the answer (or a course correction) into the message box at the bottom of the session page, exactly as you would at your desk, and press Send (Ctrl+Enter sends too). The agent picks it up and keeps working. ## Reachability: it depends on your Gateway Your browser has to be able to reach your Gateway. With the hosted Gateway that is already true from everywhere: it is a public web address, and any browser on any network can open it. There is nothing to set up. A self-hosted Gateway runs on your own machine, so reachability is your network's job. On the same network - home office laptop to the desktop upstairs - that just works. From further away, the supported route today is making your machine reachable yourself, for example with a VPN or an overlay network like Tailscale; the Gateway still handles who is allowed in. Which Gateway you run is a choice made at setup; see [the Gateway](https://devthrottle.com/docs/gateway/overview). > **Tip:** You do not have to keep the tab in front of you. The Cockpit can raise browser notifications on the machine you are on - turn them on under **Settings**, on the **Notifications** tab. When you are away from any computer, the better answer is the [mobile app](https://devthrottle.com/docs/mobile/overview): it pairs your phone to the Gateway once and then tells you there. > **Note:** A session you start from the Cockpit runs in the Director on the machine you pick when you start it - the Cockpit is a view, not the place the work runs. The same [steering controls](https://devthrottle.com/docs/director/steering) - Stop, Interrupt, and the queue - are available remotely. --- # DevThrottle on mobile > Your fleet in your pocket: a quiet dot on the app icon when a session needs you, answers by voice or thumb, and screenshots straight to the machine an agent is working on. Part of the DevThrottle documentation, section "Mobile". Canonical HTML version: https://devthrottle.com/docs/mobile/overview Last updated: 2026-09-06 Mobile is your fleet in your pocket. Your agents keep working after you stand up - the phone's job is to make sure you are never the bottleneck just because you walked away. It shows you which sessions are waiting, and you answer them from wherever you are. ## What it does - **It tells you quietly.** Once you have added the app to your phone's home screen and tapped **Enable notifications**, the app icon carries a dot while a session needs you, and the dot clears when nothing does. The Gateway checks your fleet every eight seconds and sends the dot when it changes - so it is a glance at your home screen, not a buzz in your pocket. The one thing allowed to make a sound is a snooze that has just run out. Setting it up is the last step of [pairing your phone](https://devthrottle.com/docs/mobile/pairing). - **Answer from anywhere.** On a walk, in line, on the train. Reply by voice or thumb and the agent keeps going; no laptop required. Voice replies use the same [dictation](https://devthrottle.com/docs/voice/overview) as the desktop, including your custom dictionary. - **Read what happened.** Chat shows the session's conversation - what you asked, what the agent did, what it answered - and you reply in the same place. Decisions stop waiting for your desk. - **Ask about the whole fleet.** [The Assistant](https://devthrottle.com/docs/cockpit/assistant), in the phone's menu, is a conversation with your fleet rather than with one session - how many sessions are open, which are stuck, what runs tonight - and it can act on them for you. It is the same screen the Cockpit has. - **Send screenshots.** A photo or screenshot you attach from the phone is saved into the screenshots folder on the machine that session runs on, and its path is dropped into the message box at your cursor. You add a sentence and send, so "make it look like this" works from the couch. ## Your phone connects to your Gateway The mobile app is served by the [Gateway](https://devthrottle.com/docs/gateway/overview) - by default DevThrottle's hosted Gateway, or one you run yourself. When you answer an agent from the phone, the Gateway relays your answer to the session, which runs in a Director on the machine you chose. The phone itself holds only a per-device key - not your account - so a lost phone is one revoked device, not a compromised account. The details are on the [pairing page](https://devthrottle.com/docs/mobile/pairing). The Gateway also decides what each session *looks* like. It folds every session's raw activity into one colour and one short label - the dot and the line of words on each roster row - and stamps them onto the row it sends. The phone paints exactly what it is given and never invents a colour of its own, which is why a session reads the same on the phone, in the [Cockpit](https://devthrottle.com/docs/cockpit/overview) and on the desktop. > **Note:** The phone is a view. Putting it in your pocket, losing signal, or letting the battery die never stops an agent - sessions run in Directors on your machines. See [keeping agents running](https://devthrottle.com/docs/gateway/lifecycle). ## Where to go next - [Pairing your phone](https://devthrottle.com/docs/mobile/pairing) - the one-time connect flow. - [Working with sessions](https://devthrottle.com/docs/mobile/sessions) - the roster, Chat, the terminal and files. - [Voice Mode](https://devthrottle.com/docs/mobile/voice) - listening to a session and answering out loud. - [Voice](https://devthrottle.com/docs/voice/overview) - dictation and your custom dictionary, across the whole product. --- # Pairing your phone > Connect your phone to your Gateway once and your fleet follows you - the approval flow, why what the phone keeps is a revocable per-device key, and how to sign out or run two accounts. Part of the DevThrottle documentation, section "Mobile". Canonical HTML version: https://devthrottle.com/docs/mobile/pairing Last updated: 2026-09-06 Pairing connects your phone to your [Gateway](https://devthrottle.com/docs/gateway/overview) once; after that your fleet follows you. The flow is built so the phone ends up holding as little as possible: a key for itself, not your account. ## Before you start - You have a Gateway - the hosted one your machine enrolled with in the setup wizard, or one you run yourself. - Your phone can reach it at its secure (https) address. The hosted Gateway is reachable from anywhere by nature. A self-hosted Gateway's address is its Tailscale front door, reachable once the phone has joined your tailnet - the approval step will not hand a key back to a plain http address, so a bare same-Wi-Fi IP address does not work. - A self-hosted Gateway must itself be signed in to your DevThrottle account - it verifies the phone's key against that account before accepting it. If it is not, the connecting screen says so and offers the sign-in that fixes it. ## The pairing flow 1. **Open your Gateway's address on the phone** On the phone, browse to your Gateway's address - the one the setup wizard showed on its "This machine is enrolled with" line, kept in the Director's Settings under Gateway. The Gateway recognises a phone and serves it the phone app (it lives under the Gateway's /mobile path), which opens on its Sign in screen. 2. **Approve the phone on devthrottle.com** The phone is sent to the approval page, where you sign in with your DevThrottle account and see exactly what is asking, by its device name, and which account it would join. Two buttons: connect this phone, or deny it. 3. **The phone gets its own key** What approval hands over depends on your gateway. Pairing with a self-hosted Gateway, the phone is handed a per-device key, which your Gateway checks against its own signed-in account before accepting. Pairing with the hosted gateway, the phone is handed a short-lived sign-in token instead; the gateway validates it once, mints the per-device key itself, and discards the token. Either way, what the phone stores is one per-device key, scoped to your account, identifying this one phone. 4. **Done - your fleet is in your pocket** The phone shows your sessions. Add the app to your phone's home screen and open it from there - on some phones, iPhones in particular, notifications only exist for an app installed on the home screen - then tap Enable notifications and allow the permission: from then on the app icon carries a dot while a session needs you, and the dot clears when nothing does. If the Enable notifications banner is missing, that browser cannot show notifications - open the app from its home-screen icon instead of a tab. If notifications are blocked, the banner says so; the block is lifted in the browser's site settings. ## Why the phone does not keep your account What the phone stores is a device key, never your account session. On the self-hosted path nothing else is ever handed over; on the hosted path a short-lived sign-in token makes the one trip needed to mint that key and is then discarded, not stored. The difference matters exactly once - the day the phone is lost. Be clear about what that key does reach, because it is the credential behind every screen in this app. Anyone holding it can do what the app can do: read and answer your live sessions, open a session's terminal, search and read files on the machines the fleet is paired to, and send an agent new instructions - which is to say it can reach your code. What it does *not* give is your account: it is not your sign-in, it does not open the account dashboard, and it does not carry any other device's key. So treat a lost phone as a key to revoke, not a device to write off, and revoke it the same day. A self-hosted pairing is revoked from [Devices](https://devthrottle.com/docs/account/devices) in your dashboard; a phone paired to the hosted gateway is revoked by the hosted gateway that minted its key. A phone paired to a *self-hosted* Gateway is registered on your account: it shows up as its own row in [Devices](https://devthrottle.com/docs/account/devices) in your dashboard, so a family tablet and your phone are separately revocable there. A phone paired to the *hosted* gateway does not appear on that page - its key is minted and held by the hosted gateway itself. ## Signing out, and running two accounts Pairing has an inverse, and it lives on the phone. The menu's **Sign out** row does not sign you out where it stands - it opens the phone's **Account** screen, one tap further, because a mis-tap that ended the session would cost you another trip through devthrottle.com. The Account screen lists the accounts signed in on this phone and holds three buttons: - **Add account** - run a second pairing on the same phone. Once a second account is signed in, an account switcher appears in the top bar of the roster, so you always know whose sessions you are looking at. Switching reloads the app as that account; both stay signed in, so it needs no password and works with no connection. - **Sign out** (or **Sign out of this account** when there are two) - signs out the account you are using now. The confirmation names it, and says whether the app will switch to your other account or ask you to sign in through devthrottle.com again. - **Sign out of all** - offered only when more than one account is signed in. Every account leaves this browser, and each one signs back in through devthrottle.com. Signing out makes *this browser* forget its key. It is not the same as removing the device: a phone paired to a self-hosted Gateway stays on your account at devthrottle.com until you remove it in [Devices](https://devthrottle.com/docs/account/devices). That is the difference that matters when the phone is in your hand versus when it is gone. > **Warning:** If a phone paired to a self-hosted Gateway is lost or stolen, revoke it in [your devices](https://devthrottle.com/docs/account/devices) right away. Revocation is the kill switch for that device's access. --- # Working with sessions from your phone > The home roster, starting a session, chatting with an agent, the live terminal mirror, attaching photos, and opening files - everyday session work from the phone app. Part of the DevThrottle documentation, section "Mobile". Canonical HTML version: https://devthrottle.com/docs/mobile/sessions Last updated: 2026-09-16 Once your phone is [paired](https://devthrottle.com/docs/mobile/pairing), the whole fleet travels with you. This page covers everyday session work from the phone: reading the roster, starting a session, chatting with an agent, watching its terminal, and opening the files it produces. ## The home roster The home screen is your session list, refreshed every few seconds. It has two lenses, side by side at the top: **All**, and **Voice sessions**. On the All tab the list opens in attention order: sessions **waiting on you** under **Needs you**, longest-waiting first, then a **Done or carrying on** band for the sessions the Wingman judged finished or carrying on by themselves, then **Working** and **Snoozed**. The **Order** switch changes to **My order**, which groups sessions by machine in the same order as in your Director. Below it, **What do the colours mean?** opens a short legend of every status colour. ![The same What the colours mean panel on the phone: the eleven colours with their names, whether each asks for you and what it means, in a single narrow column](https://devthrottle.com/docs/screenshots/mobile/colour-legend.png) Each row tells you a lot at a glance: - A colored **status dot** and a line describing what the session is doing right now - with a live **waiting** timer on anything that needs you. Both the colour and the words are decided by the Gateway and painted by the phone, so a session reads the same here, in the Cockpit and on the desktop. - The session's short **number** in muted type before its name - the same three digits the desktop rail shows, so you can say "look at 102" and both screens agree. Sessions without a number simply show none. - A line of **supervision facts**: when the session started, how long it has been open, how much of that it spent idle waiting on you, and how many turns the agent has finished. A fact the machine does not report is left out rather than shown as zero. - Small chips for the **machine** and **repo** the session runs in. - A **wakes in 3h 48m** countdown on a snoozed row, ticking down to the moment it comes back to you, and a **Snooze ended** badge once a snooze has expired on its own. - A red **not delivered** badge when a prompt never reached the agent. It is sticky on purpose - it clears when something actually lands, never on a tap and never on a timer - because a prompt that quietly went nowhere is the one failure you must not be able to wave away. - A neutral **winding down** badge on a session that has been flagged for deletion. It is a badge and never a colour: the dot keeps telling the truth about the work while this rides beside it. - A dictation badge while a spoken prompt is still uploading or transcribing, so a voice reply is never silently in limbo. - On voice-mode sessions, a play triangle appears when a spoken update is ready - tap it to listen without leaving the roster. Where the Gateway has said it cannot make audio for a session, the row reads **No voice** instead of offering a play button that leads nowhere. The **Voice sessions** tab is the other lens: the sessions that can speak to you right now, gathered under **Ready to play**. It carries two controls the All tab does not - a fleet-wide switch that turns voice mode on for every session at once, and off again, and an **Auto-speak** checkbox that plays each waiting session in turn without a tap. They are two different things: voice mode is about your whole fleet and lives on the Gateway, Auto-speak is about this phone. Both are covered on [Voice Mode](https://devthrottle.com/docs/mobile/voice). If more than one DevThrottle account is signed in on the phone, an **account switcher** appears in the top bar of the roster, so a list of the wrong account's sessions can never be mistaken for yours. Adding and removing accounts is on the [pairing page](https://devthrottle.com/docs/mobile/pairing). If a machine drops off the network its sessions are **kept and grayed**, never removed - the row says it is reconnecting and when the machine was last seen. The same idea applies app-wide: on a bad connection the app keeps showing the last known information and says so in a banner, rather than blanking the screen. > **Tip:** Running a big fleet? The funnel button opens **Filter sessions** - pick machines and repos, then **Apply filter**. The bar shows how many sessions the filter is hiding, and the choice sticks on this phone. ## Managing a session Chat, Terminal and Voice mode share one app bar, so the same verbs sit in the same places on every session screen. Navigation is on the left: **Sessions**, with a back arrow, takes you to the roster. Everything else is behind the three-dot menu on the right, which keeps the rare and destructive verbs away from your thumb: - **Switch to voice mode** - offered on Chat and Terminal; it opens the session's [Voice mode](https://devthrottle.com/docs/mobile/voice) and turns voice on. - **Snooze** and **Unsnooze** - quiet a session so it stops asking for you, and wake it again. They are in this menu on Chat and Terminal, whose bottom of the screen belongs to the message box; Voice mode has room for Snooze as one of its own big buttons instead, so the verb is never in two places at once. - **Remove session** - the destructive one, two taps away and never under your thumb. It asks first: *Remove this session? This will terminate it. This cannot be undone.* with Cancel and Remove. Under the session name, a pill shows a snooze that is in effect, with the time left beside it. Snooze a session while its agent is still working and the pill reads **Snoozing when it finishes** - the snooze arms when the work ends, so asking for it mid-turn tells you something happened instead of looking like nothing did. If a prompt to this session was never delivered, the red **not delivered** banner rides here too, on whichever screen you are on. ## Starting a session 1. **Pick the machine** Open **New session** from the roster or the menu. Every machine running a Director is listed with its uptime; the one you used most recently is pre-selected. 2. **Pick the repository** Tap one of the machine's recent repos, or type a full path under **Or enter a path** and tap **Create session**. 3. **Talk to it** The new session opens in Chat, ready for its first prompt. Session creation from the phone is deliberately simple - agent and model choices live in the desktop [New Session dialog](https://devthrottle.com/docs/director/steering). ## Chat Chat is the default view of a session: the live conversation, cleaned up into speaker-labeled bubbles. A **Show** filter lets you also reveal **Tool calls**, **Results**, and **Thinking** - hidden by default, remembered on this phone. The composer under every conversation has three verbs: - **Send** - type a prompt and submit it. - **Speak** - dictate instead. You talk, tap **Pause** to see the text (edit it if you like), then **Insert** it into the box or **Send** it straight to the agent. A spoken send keeps working in the background even if you leave the screen - the status strip and roster badge track it. - **Attach** - open the camera or photo library and attach an image. The photo is saved into the Director's screenshots folder on the machine the session runs on, and its path is inserted at your cursor, so you can add a sentence and send. This is how you show an agent a screenshot. - Quick keys - **Enter**, **Esc**, **Stop**, and arrows - for answering an agent's menu prompts without opening the terminal. Links in the conversation are live: URLs open in a new tab, and file paths open the built-in file viewer. Both carry a copy button. What Chat reads is the Gateway's own copy of the conversation, not your machine. Each computer sends its finished turns up as they happen and the phone polls that copy every couple of seconds - which is why a conversation you have already had stays readable when the machine that ran it is asleep, off the network, or simply shut. When the stored copy is real but no longer current, a notice sits above the bubbles and says which of those it is: the computer has not checked in recently, or it is running an older DevThrottle that does not send conversations and needs updating. You are never left waiting for messages that were never going to arrive. ## Terminal The **Terminal** tab is a live mirror of the session's real terminal, streaming as the agent works. Zoom with **A-** and **A+**. The button in the corner swaps between two ways of sizing the mirror and is labelled with the one it will switch to: **Fit** squeezes the terminal to the width of your phone, **1:1** shows it at its real size and lets you pan. If the stream drops, the last screen stays visible while it reconnects, with a small note saying so. The terminal fills the screen with nothing else on it until you tap **Keys**, which reveals the same control panel Chat has - the message box, Speak, Send, and the Enter, Esc, Stop and arrow keys - so you can answer a prompt without leaving the terminal. Tap **Hide keys** to get the room back. ## Files Tap any file path - in Chat or in the terminal - and the file opens in the app: images, PDFs, HTML, Markdown, and code all render in place, and anything without a preview offers a download. A **Download** button saves the file to your phone. > **Note:** Prefer talking to typing? [Voice Mode](https://devthrottle.com/docs/mobile/voice) narrates a session's turns out loud and lets you answer by talking. --- # Voice Mode on your phone > Turn a session into something you listen to: the Wingman narrates completed turns out loud, you answer by talking, and when a narration cannot be made the screen names the reason instead of going quiet. Part of the DevThrottle documentation, section "Mobile". Canonical HTML version: https://devthrottle.com/docs/mobile/voice Last updated: 2026-09-06 Voice Mode turns one session into something you listen to. When it is on, the Wingman narrates completed turns as spoken audio, and you answer by talking - the step up from reading the [Chat view](https://devthrottle.com/docs/mobile/sessions) yourself when your hands and eyes are busy. ## Turning it on There are three ways in, and they suit three different moments: - **One session, from the session.** Open it, pick the **Voice mode** tab, and tap **Switch to voice mode**. - **One session, from where you already are.** **Switch to voice mode** is in the three-dot menu on the Chat and Terminal screens, so you never have to go looking for the tab. - **The whole fleet, in one tap.** On the roster's **Voice sessions** tab, a button turns voice mode on for every session at once - and offers the opposite once it is on. This is the walking-out- of-the-house control: put the fleet on voice as you leave, take it off when you get home. A session in voice mode shows up on the roster with a voice indicator, and every completed turn with a written answer in it is sent for narration. A clip is not guaranteed. When one cannot be made - there is nothing to read aloud, an account condition is blocking it, the speech service is down, the session's computer is on a build too old to send its conversation, or three minutes pass with nothing produced - the screen tells you which of those it is rather than going quiet. The table below is the whole list of answers it can give. ## Listening When a narration is made, your phone downloads the whole clip before offering playback - so when it says ready, it plays instantly. A fresh clip plays automatically while you are on the screen, with a full player: play and pause, restart, and a seek bar. Leave halfway through and it resumes where you stopped. If the agent starts working again, the old narration is retired - you never act on stale news. - **Respond** and **Snooze** - the two big buttons at the top of the screen, in the same place in every state. Respond: speak, review the transcript at **Pause** if you want, then **Send** - the reply transcribes and submits in the background. Snooze silences the session for your default length and returns you to the list; once your snooze lengths have been read from your Gateway, a caret beside it opens a **Snooze for** sheet listing them. - **Regenerate response** and **Turn voice off** - in the session menu: rebuild the narration for the current turn, or go back to a normal session. - **Generate narration now** - offered on the status card when the Gateway says a narration can be made on the spot. > **Tip:** While the app is in the foreground the phone keeps the screen awake where the browser supports it. A narration that would start while the app is hidden or the phone is locked is skipped; whether audio already playing continues under lock is the phone's decision, not DevThrottle's. Back in the app, if the next narration does not start on its own, tap the session to start it. ## What the screen can tell you The one question voice mode has to answer is *why is it quiet*. So the screen never just goes silent: your Gateway decides what is true about this session's voice and the phone shows you that verdict word for word. These are the states you will meet - every one the screen can show. | What it says | What it means | | --- | --- | | **Voice off** | This session is not in voice mode. The screen offers the button that turns it on. | | **Agent is working** | Mid-turn. Nothing is offered on purpose: the last narration is stale, and the next completed turn will be narrated. | | **Voice ready** | There is audio to play. Occasionally it arrives with a note saying you were switched to a backup voice because the usual one was overloaded - no extra charge, and nothing else changes. | | **Voice on its way** | The narration is being made right now, a first attempt is being retried automatically, or your phone is pulling the finished audio down. From a minute in, the wait is shown beside it and climbs in whole minutes. | | **Voice did not arrive after 4m** | Three minutes have passed with nothing produced, so the screen stops promising. Your Gateway keeps trying underneath, and you can read the turn instead - but you are told plainly rather than left watching a spinner. | | **Voice service down** | The speech service itself is unavailable. Nothing on your side is wrong and nothing needs doing. | | **Voice needs credit**, **Monthly limit reached**, **Finish setup**, **Not included with this account** | An account condition, not a fault in this session. Each one carries the sentence that says what to do - the same sentence every other DevThrottle screen shows for the same condition. See [pricing](https://devthrottle.com/pricing) for what a plan includes. | | **Monthly fair-use limit reached**, **Voice unavailable** | Account conditions too, but the two with nothing to press. The fair-use allowance for included AI features resets at the start of next month. **Voice unavailable** is the deliberately neutral answer when your Gateway is refused for a reason this build does not recognise - it never guesses that you are out of credit. Both say so and offer no button. | | **Update DevThrottle** | The computer running this session is on an older DevThrottle that cannot send its conversation up, so there is nothing to read aloud. Updating that machine fixes it with no other action from you. | | **Nothing to read aloud** | The session does need you, but it is sitting on a prompt or a menu rather than a written answer - so there is genuinely nothing to narrate. Not a failure. | | **No narration yet** | Voice is on and this turn has not been narrated yet. This is the one state where **Generate narration now** can help, so it is the one state that offers it. | You will never be shown a button that cannot work: where the answer is "there is nothing to make" or "it has already failed", the screen says so instead of offering to try again. ## The language and the voice What the narration sounds like is set once for your whole account, not per phone: open the menu, pick **Settings**, then the **Language** tab. Each language lists the voices it offers, and **Play sample** speaks a sample sentence using the account's real setup - what you audition is what every narration will sound like, on every phone and browser you use. The models behind narration run through your DevThrottle account - see [pricing](https://devthrottle.com/pricing) for what a subscription includes. > **Note:** Voice mode and the spoken language are fleet-wide - they live on your Gateway, so they follow you to every phone and browser. The few things that belong to *this* phone: notification permission, chat filters, playback positions, and **Auto-speak**, the checkbox on the roster's **Voice sessions** tab that opens each waiting voice session in turn and plays it without a tap. Its own hint on the screen says so: this phone only. --- # Voice > Answer and steer agents by talking instead of typing - dictation on desktop, browser, and phone, made accurate by a custom dictionary that reaches every one of those surfaces. Part of the DevThrottle documentation, section "Voice". Canonical HTML version: https://devthrottle.com/docs/voice/overview Last updated: 2026-09-06 Voice lets you answer and steer agents by talking instead of typing. The long instruction you would never bother typing takes about ten seconds to say. It works in the [Director](https://devthrottle.com/docs/director/overview) (the Speak button on the prompt bar), in the [Cockpit](https://devthrottle.com/docs/cockpit/overview), and on [your phone](https://devthrottle.com/docs/mobile/overview). ## The trick is the dictionary Generic dictation mangles technical speech - repo names, library names, your project's jargon. DevThrottle gives you one custom dictionary: teach it your words once, and a cleanup pass corrects the transcriptions it covers after the text comes back. The dictionary is shared everywhere you dictate - desktop, browser, and phone - so "Supabase", "devcontainer", or your product's codename comes out right on all of them, on DevThrottle's hosted Gateway and on a Gateway you host yourself alike. > **Tip:** Seed the dictionary with the ten words you say most - project names, tool names, teammates - and the transcriptions it covers get dramatically better in the first minute. ## What you said is what the agent gets Nothing rewrites, tidies, translates or answers your words on the way through. The transcript never round-trips through a model that writes text, so there is nothing in the path that could reword a sentence, shorten it, or reply to it instead of handing it on. The one change made to what you said is a find-and-replace out of your own dictionary: a wrong spelling you listed yourself, swapped for the term you paired it with. As DevThrottle ships that is the only edit - a word that merely resembles one of your terms is left exactly as you said it. A Gateway can be set to correct close misses of your terms as well; that is off unless it is turned on. [Your dictation dictionary](https://devthrottle.com/docs/voice/dictionary) is where those pairs live, and how the pass applies them. ## What it costs Dictation is part of [Pro](https://devthrottle.com/pricing). There is no key to supply, no per-minute charge, and nothing extra to buy before you can talk - it works on a Pro subscription. ## Hosted transcription and your voice > **Note:** Dictation works by sending the audio you speak to DevThrottle's transcription service, which returns the raw text. The request carries the audio clip, which transcription model to use, the format the text should come back in, and an optional hint about what language you were speaking. It never carries your dictionary, and never anything you have typed. Dictionary corrections happen on the text after it comes back, with your own dictionary, and as DevThrottle ships the only words replaced are the ones you listed. A Gateway can be set to correct close misses of your own terms as well; that is off unless it is turned on. What is kept afterwards, on the Gateway side. Cleanup runs only when new activity arrives - a later transcript write, a later clip save - so where activity stops, old rows and old audio simply stay until the next activity, indefinitely if none comes. With that understood: the text of each transcription is stored by your Gateway, trimmed to the last 90 days and the newest thirty thousand per account as new transcripts are written. On the hosted service that store is per account, and no account can read another's. A self-hosted Gateway also keeps the audio it transcribes on that machine's own disk, to diagnose a transcription that went wrong. That archive is a folder of clip files - `transcription-audio`, in the Gateway's own data directory beside the rest of its local files - with one file per turn, named for the turn so a suspect line in the local transcription history leads straight to the audio that produced it. It is trimmed to 24 hours and the newest 500 clips when a later clip is saved - the 500 cap can retire audio before its 24 hours are up - and the saving itself is best-effort and can fail: a diagnostic aid, not a promise. The hosted service keeps no such audio archive. Your own devices can hold copies of a recording too, in the ordinary course of delivering it: the browser and the phone keep a clip on the device until its delivery is confirmed, and the desktop app tries to keep a clip when a background Send fails before its words could become text - that saving is best-effort and can fail, and the failure message names the file only when the save succeeded. That desktop copy exists only on that Send path - a Pause or Insert that fails keeps no clip. ## Where to go next - [Voice Recorder](https://devthrottle.com/docs/voice/recordings) - record on your phone, read the transcript in the Cockpit. - [Pricing](https://devthrottle.com/pricing) - what a Pro subscription includes. - [Mobile](https://devthrottle.com/docs/mobile/overview) - voice answers from your pocket. --- # The Voice Recorder > Record something long on your phone and read the transcript in the Cockpit - recording, notes, automatic delivery, and what the two ticks on a row mean. Part of the DevThrottle documentation, section "Voice". Canonical HTML version: https://devthrottle.com/docs/voice/recordings Last updated: 2026-09-06 The **Voice Recorder** is for the long things - a meeting, a walk, a drive, ten minutes of thinking out loud. You record on your [phone](https://devthrottle.com/docs/mobile/overview), it goes up to your [Gateway](https://devthrottle.com/docs/gateway/overview) on its own, and the transcript comes back on the phone and in the [Cockpit](https://devthrottle.com/docs/cockpit/overview). It is not [dictation](https://devthrottle.com/docs/voice/overview): dictation is a sentence you speak into a prompt, this is a recording you keep. ## Opening it - **On your phone** - **Voice Recorder** in the menu, under Assistant. Older bookmarks to the retired native app's Notes and Record screens land here too. - **In the Cockpit** - **Voice Recorder** in the left rail. That side is for reading and keeping; the recording itself happens on the phone. ## Recording One card at the top holds everything about the recording in progress: a running clock, what it is doing (Idle, Opening microphone, Recording, Paused, Saving), how many segments it has captured, and a level meter so you can see it is hearing you. Beneath it is a title box you can edit at any point until you stop. **Record** starts it. While it runs you get **Pause** - which finishes the open segment and suspends capture - and **Stop**. There is no time limit, and recording continues while you use the rest of the app. > **Warning:** Keep the screen on. If the phone locks or the browser suspends the page, the microphone is cut: the recording then stops, saves everything it had captured, and says on its row that it was cut short. Nothing already recorded is lost, but nothing after that point was recorded. While you are recording there is a **Notes while recording** box. Type a line, press **Add**, and it is kept with the time it was added at, so "he says the deadline moved" is pinned to the minute it was said. The notes travel with the recording. ## Nothing waits on a good connection The recording is written to the phone in segments *as it is captured*, before any network work at all. Reload the page and it is still there. Close the app in the middle of recording and you are offered it back on your next visit, with the segments it had finished intact. Stopping both finishes the recording and queues its upload - there is no Send step. If the upload is interrupted, the row parks as saved on the phone with a plain reason and a **Retry**, and delivery resumes on its own the next time the app is open and the connection is back. A resumed upload picks up at the first segment the Gateway does not already hold, so nothing is sent twice. > **Note:** A browser that cannot store data durably cannot do any of this, so the recorder says so and disables recording rather than starting one it might lose. ## The list, and its two ticks Under the controls is every recording, newest first, with its date, length and segment count. Each row carries **two independent statuses** - **Uploaded** and **Transcribed** - and they never collapse into one, because a transcription that fails does not un-upload the audio. A row in flight says which segment it is sending; a row waiting says so; a row whose transcription failed says that the audio is safely uploaded. **Play** plays it back. **View transcript** opens the text on the phone once it has been transcribed. A recording that never got delivered can be discarded, which asks once before it does it. ## Reading it in the Cockpit The Cockpit's **Voice Recorder** page is the comfortable place to read one. Each recording is a card - title, subtitle, when, how long, how many segments, and a badge for its state. Click it to open the transcript, and from there: - **Play audio** - plays the segments in order. - **Copy path** - copies the transcript's path on the Gateway, available once the recording has been transcribed. - **Save to vault** - keeps this one permanently. Recordings are held locally and are temporary; this is what makes one stay. - **Delete** - removes it, after a confirmation. The **Title**, **Subtitle** and **Summary** are yours to edit on the card, so a recording that arrived with a placeholder name can become the thing it actually was. **Copy agent info** copies the endpoint and directory an agent needs in order to work through these transcripts itself. ## Your dictionary applies here too Each segment is transcribed on its own, and the assembled text is then run once through the same cleanup pass every other voice surface uses, against the same [dictionary](https://devthrottle.com/docs/voice/dictionary) you edit in the Cockpit. Teach it a term for dictation and your recordings get it right as well. > **Tip:** Say the names first. A recording that opens with the people, the repository and the project it is about gives you a transcript you can search later, and shows you within a minute which words your dictionary is still missing. ## What it costs Transcription is part of [Pro](https://devthrottle.com/pricing), the same as dictation - there is no key to supply and nothing extra to buy. If transcription cannot run, the recording is not lost: the audio stays uploaded and the row marks the transcription as failed. ## Where to go next - [Your dictation dictionary](https://devthrottle.com/docs/voice/dictionary) - teach it the words it keeps getting wrong. - [Voice](https://devthrottle.com/docs/voice/overview) - dictation, and what is kept afterwards. - [Mobile](https://devthrottle.com/docs/mobile/overview) - the rest of what the phone does. --- # Your dictation dictionary > One shared dictionary on your Gateway - vocabulary and correction pairs a cleanup pass applies to every voice surface after transcription, and the words it writes in come from your own two lists. Part of the DevThrottle documentation, section "Voice". Canonical HTML version: https://devthrottle.com/docs/voice/dictionary Last updated: 2026-09-06 Speech-to-text is only as good as its grasp of your vocabulary - project names, tool names, jargon. DevThrottle keeps **one shared dictionary on your Gateway**, and a cleanup pass applies it to transcriptions after the text comes back. That covers every voice surface - dictation and Speak on every Director, and voice-note transcription - on DevThrottle's hosted Gateway and on a Gateway you host yourself alike: teach it a term once and the next transcription is corrected, with no restarts and no copying files around. ## The Dictionary page Open **Dictionary** in the Cockpit's left rail. It has two lists: ![The Cockpit Dictionary page with seven vocabulary chips including DevThrottle and Kubernetes, and a correction row pairing DevThrottle with the wrong spellings dev throttle and def throttle](https://devthrottle.com/docs/screenshots/cockpit/dictionary.png) - **Vocabulary** - your canonical spellings: the way you want your terms written. The terms are not sent to the speech model itself - correction happens on the text, inside your Gateway, after it comes back. - **Common mistranscriptions** - the correct term paired with the wrong spellings you have actually seen. This is the list that does the work: a wrong spelling written here is corrected every time it appears, exactly. Edit, then **Save**. The dictionary is read fresh each time it is used, so a saved edit applies to the next transcription that reads it - the next voice note recording, and the next time you dictate. If you try to leave with unsaved changes, the page stops you and asks. ## What the cleanup pass will and will not do As DevThrottle ships, the cleanup pass never rewrites your text freely. Every change is a find-and-replace of a wrong spelling you wrote down, and the word put in its place is one of your own - a Vocabulary term, or the correct spelling from a Common mistranscriptions row. Nothing else in what you said is changed: a word that merely resembles one of your terms is left exactly as you said it, and a transcript with none of your listed spellings in it comes back untouched. If a correction pass fails part-way, the raw transcript is delivered instead. One setting widens that, and it is off unless somebody writes it into the dictionary your Gateway reads. Turned on, the pass may also correct a word that is close to one of your terms but that you never listed. It is not a control on the Dictionary page, so nothing you do there switches it on. A dictionary the Gateway cannot read does not fail the transcription: the raw text comes through with none of your corrections applied. So if your terms suddenly stop being fixed after a hand edit to the dictionary file, the dictionary is the first place to look. ## Suggestions from your own dictations You do not have to think of every term yourself. The Gateway scans your recent dictations for distinctive words the speech model keeps getting wrong, screens out ordinary English, and offers what is left at the top of the Dictionary page. The scan runs nightly; **Scan now** runs one on the spot, and the panel shows when the last one ran. While there are terms waiting, the Dictionary item in the left rail carries a red count, so you can see there is something to look at without opening the page. Each suggestion is a row: the term, the wrong spellings it was actually heard as, and a count of how many times out of how many it came out wrong. Rows arrive ticked. Untick the ones you do not want this round, press **Add**, and the term and its wrong spellings are written into your two lists. Nothing changes until you press Add. **Dismiss** on a row stops that term being suggested again; the dismissed ones sit in a collapsed **Dismissed suggestions** list and can be restored from there. If the screening step cannot be reached when a scan runs, the page says so and holds back the new candidates rather than showing unscreened guesses. > **Note:** Dictation is driven by buttons - **Pause** to review your transcript and **Send** to submit it. The phone's AI settings screen sets models and voices, not the dictionary; the dictionary lives in the Cockpit and on your Gateway. --- # AgentEyes: a screen and audio recorder for Windows > AgentEyes is a screen and audio recorder for Windows that turns a recording into a transcript and a shareable write-up. It is its own download and signs in with your DevThrottle account. Recording is local; transcription and translation use DevThrottle hosted AI. Part of the DevThrottle documentation, section "AgentEyes". Canonical HTML version: https://devthrottle.com/docs/agent-eyes/overview Last updated: 2026-09-06 AgentEyes is a screen and audio recorder for Windows that lives in your tray. It records your screen, your microphone and - if you want one - your webcam, and turns a recording into a searchable transcript and a shareable write-up. It is its own download, separate from [DevThrottle](https://devthrottle.com/docs/overview): you do not need an account to record, and the steps that use hosted AI work through your DevThrottle account, so one account covers both. ## How recording and transcription work It is worth being precise about where your recordings go, because AgentEyes uses both your machine and DevThrottle's hosted AI: - **On your machine.** Recording, the recording library, rendering the camera into the video, and burning subtitles into a video all run on your own PC, and you do not need a DevThrottle account to record. - **Sent to DevThrottle's hosted AI.** Turning a recording into a transcript, translating a transcript, and generating a recording's title and description use DevThrottle's hosted AI through your signed-in account. For those steps, the recording's audio (to transcribe) or text (to translate) is sent to DevThrottle. See [Import a video](https://devthrottle.com/docs/agent-eyes/import) and [Multilingual subtitles](https://devthrottle.com/docs/agent-eyes/subtitles) for exactly what is sent and when. ## Visible and controllable An always-on recorder only works if you stay in control of it, so two things are built in rather than buried in a settings page: - **Visible.** A recording indicator is on whenever it is capturing. There is no stealth mode, ever - you always know when it is running. - **Controllable.** One action stops everything, from the window, the recording indicator, or the tray. ## What it does today - **Records with a click.** OBS-style named presets pick a monitor or a region, choose the audio, and capture screen, audio, or a single screenshot. See [Recording](https://devthrottle.com/docs/agent-eyes/recording). - **Films you as well as the screen.** A preset can name a webcam and a frame rate, and you choose how the camera sits over the screen - shape, corner and size - before you record. See [Recording](https://devthrottle.com/docs/agent-eyes/recording). - **Turns a recording into an artifact.** The walkthrough builder takes a recording and produces a transcript plus a shareable HTML write-up you can drop into a ticket, a doc, or a message. - **Snips a screenshot from anywhere.** PrintScreen grabs a region and Ctrl+PrintScreen the whole screen, each one saved as a PNG and copied to the clipboard, with a Capture gallery listing them. Both shortcuts are rebindable. See [Recording](https://devthrottle.com/docs/agent-eyes/recording). - **Imports an outside video.** Bring a Teams meeting recording or any common video file into the library and get a transcript back. See [Import a video](https://devthrottle.com/docs/agent-eyes/import). - **Adds subtitles in another language.** Translate a transcript with the timing preserved and burn the captions into a new video. See [Multilingual subtitles](https://devthrottle.com/docs/agent-eyes/subtitles). - **Runs your own tools on a finished recording.** A post-recording plugin is a folder you drop in and switch on; enabled plugins run as their own process once a recording is finalized and transcribed, with the recording folder as the surface they read and write. - **Keeps itself current.** It checks for a new release, installs it in the background and restarts into it - waiting until a recording has finished. You can turn the check off in Settings. ## Two ways to run it AgentEyes is a tray app (`AgentEyesApp.exe`) and a command-line tool (`agenteyes.exe`) that share one engine. Beyond the tray window, a local REST Control API lets a script or an agent drive the recorder headlessly. - **From the window.** Pick a preset and record, then find, play and act on what you captured in the recording library. No DevThrottle account is needed to record. (Transcription, translation, and AI titles do use your DevThrottle account, since they run on the hosted AI.) - **From a script.** The [CLI](https://devthrottle.com/docs/agent-eyes/cli) and the [Control API](https://devthrottle.com/docs/agent-eyes/control-api) automate every part of it. ## Where recordings live Recordings land in `%USERPROFILE%\Videos\AgentEyes\`. Configuration, presets, the dictionary, plugins, and logs live in `%LOCALAPPDATA%\AgentEyes\`. Each recording is its own folder holding the video or audio, any screenshots, and the transcript. > **Tip:** You do not have to leave the tray to use most of this. If you would rather script it, start with the [CLI reference](https://devthrottle.com/docs/agent-eyes/cli). ## Where to go next Start with [Recording](https://devthrottle.com/docs/agent-eyes/recording) to make your first capture, or jump straight to [Import a video](https://devthrottle.com/docs/agent-eyes/import) and [Multilingual subtitles](https://devthrottle.com/docs/agent-eyes/subtitles). --- # Recording with AgentEyes > Record your screen, audio and webcam with named presets, snip screenshots from any app, and turn a recording into a transcript and a shareable write-up. Part of the DevThrottle documentation, section "AgentEyes". Canonical HTML version: https://devthrottle.com/docs/agent-eyes/recording Last updated: 2026-09-06 AgentEyes records your screen and audio from named presets, keeps the results in a recording library, and can turn any recording into a transcript and a shareable write-up. It also snips screenshots from any app, with or without a recording running. This page covers what you can do today from the tray app; to script the same things, see the [CLI reference](https://devthrottle.com/docs/agent-eyes/cli). ## Presets: pick one and record A preset is a named capture profile, in the spirit of OBS scenes. A preset decides which monitor or region to capture, whether it records video, audio, or a single screenshot, how the audio is handled, and whether a webcam is filmed alongside the screen. You set a preset up once, then choose it and hit record. - **Source.** A whole monitor, or a region you draw. - **Audio.** Your microphone, the system (loopback) audio, or the two mixed together. **Mic only is the default**, because it captures the room correctly timed; mixing in the system audio is a deliberate choice. Noise suppression and voice leveling are applied to the mic unless you turn them off, and a noise gate is on for system and mixed audio. - **Mode.** Video, audio, or a screenshot. - **Camera.** Optional - see below. ## Film your camera alongside the screen A preset can name a webcam and a frame rate, and AgentEyes records it to its own `camera.mp4` beside the screen video. How the camera is framed over the screen - a circle or a rectangle, which corner it sits in, how big it is, and which part of the camera frame the circle takes - is chosen in the preset editor *before* you record, against a live picture from the camera. > **Note:** The camera is always recorded whole, whatever framing you picked, so the framing is a decision you can change afterwards. Change it and run `agenteyes compose` on the recording folder to render the video again - see the [CLI reference](https://devthrottle.com/docs/agent-eyes/cli). A recording with no camera is unaffected. ## Snip a screenshot from any app Two global shortcuts take a screenshot without any recording running: **PrintScreen** lets you drag a rectangle, and **Ctrl+PrintScreen** takes a whole monitor. Each snip is saved as a PNG and copied to the clipboard, and the Capture view in the app lists them so you can find one again. - **Where they land.** The Windows Screenshots folder by default (including when OneDrive has redirected it), or any folder you set instead. - **Rebindable.** Both shortcuts are set in the Capture view and the new binding survives a restart - useful if Windows has claimed PrintScreen for its own tool. ## The recording library Recordings are saved under `%USERPROFILE%\Videos\AgentEyes\`, one folder per recording. The tray app lists your recent recordings so you can find, play, and act on them. Each recording folder holds the captured video or audio, the camera track if there was one, any screenshots you took mid-recording, and - once you build it - the transcript. > **Note:** AgentEyes today is a record-when-you-choose tool: you pick a preset and start. The always-on rolling buffer - a recorder that is always capturing so you can reach back and keep a moment after the fact - is the product's larger goal and is still on the roadmap, not something you can rely on yet. ## What happens after you stop Stopping is not the end of the work. Finishing the audio mix, rendering the camera into the video, making the thumbnail, transcribing and titling all run as one named sequence after the stop, so the app answers straight away and the recording keeps finishing behind it. Each step records what it did in the recording's own folder, so an interrupted sequence - you closed the app, the machine restarted - picks up at the step it reached the next time AgentEyes runs, instead of starting over or being abandoned. ## Turn a recording into a write-up The walkthrough builder takes a recording and produces two things: a **transcript** of what was said, and a shareable **HTML write-up** that pairs the transcript with screenshots from the recording. The raw capture becomes something you can drop into a ticket, a document, or a message without editing video. > **Note:** Building the transcript uses DevThrottle's hosted transcription through your signed-in account: the recording's audio is sent to DevThrottle to be transcribed, and the transcript comes back. The video file is not part of that request. > **Tip:** AgentEyes has its own **Dictionary** view for the terms transcription keeps getting wrong - your product names, your people, your jargon. Every term you list is applied to a recording's transcript by plain find and replace before the transcript is written and before the title is generated, so the transcript, the walkthrough and the title all get it right. It is AgentEyes' own list, kept on this machine; it is not the DevThrottle dictionary and the two are not shared. ## Where to go next To bring an existing video into the library, see [Import a video](https://devthrottle.com/docs/agent-eyes/import). To caption a recording in another language, see [Multilingual subtitles](https://devthrottle.com/docs/agent-eyes/subtitles). To do any of this from a script, see the [CLI reference](https://devthrottle.com/docs/agent-eyes/cli) and the [Control API](https://devthrottle.com/docs/agent-eyes/control-api). --- # Import an external video > Bring an existing video - a Teams meeting recording, a screen capture, any common video file - into your AgentEyes library and get a transcript, a title, and a description, so it becomes a normal library recording. Part of the DevThrottle documentation, section "AgentEyes". Canonical HTML version: https://devthrottle.com/docs/agent-eyes/import Last updated: 2026-07-10 You already have videos that are not AgentEyes recordings - a Teams meeting you recorded, a screen capture from another tool, a clip someone sent you. **Import** brings one of those into your AgentEyes library, transcribes it, and names it, so it becomes a normal library recording sitting next to the ones you made yourself. ## What import does Point AgentEyes at a video file and it: - Copies the video into a new recording folder in your library. Your original file is left exactly where it is - import copies, it does not move or delete. - Extracts the audio and transcribes it into a timestamped transcript. - Gives the recording a title and a short description generated from the transcript, the same way a native recording is named. - Writes the transcript as three files in the recording folder: `transcript.json` (timed segments), `transcript.txt` (plain text), and `transcript.en.vtt` (WebVTT captions, ready for [subtitles](https://devthrottle.com/docs/agent-eyes/subtitles)). > **Note:** Transcription and the generated title and description use DevThrottle's hosted AI (speech to text for the transcript, a chat model for the title). What import does, in order: it copies the video into your local library, extracts the audio to a WAV beside it, and sends that WAV to DevThrottle through your signed-in account to be transcribed. The transcript text then goes to the chat model for the title. You need to be signed in for import to transcribe. Nothing here uploads the video container itself - the audio is what travels. ## Supported files Import accepts the common video containers: `.mp4`, `.mkv`, `.mov`, `.avi`, `.webm`, `.m4v`, `.wmv`, `.flv`, `.ts`, `.m2ts`, `.mpg`, and `.mpeg`. The file must contain a video stream; an audio-only file or a file with an unrecognized extension is rejected with a clear message rather than half-imported. ## Import from the command line The [CLI](https://devthrottle.com/docs/agent-eyes/cli) command takes the path to the video: **Import a Teams recording** ``` agenteyes import "C:\Users\me\Videos\Weekly sync.mp4" ``` It prints progress as it copies, transcribes, and names the recording, then reports the new recording id and its folder: ``` [ok] importing 'Weekly sync.mp4' -> ...\Videos\AgentEyes\ copied video (12:04) transcribing (DevThrottle, whisper-large-v3) ... 42 transcript segment(s) naming the recording ... title: Weekly sync - roadmap and blockers [ok] imported recording [ok] folder: C:\Users\me\Videos\AgentEyes\ ``` > **Tip:** The recording **id** it prints is the name of the recording folder. You pass that id to [translate and subtitle](https://devthrottle.com/docs/agent-eyes/subtitles) to add captions in another language. ## Import over the Control API The same import runs over the local [Control API](https://devthrottle.com/docs/agent-eyes/control-api), so an agent can do it headlessly. The call is synchronous - it returns once the import (including transcription) has finished - and answers with the new recording id and folder. `POST /import` Body: `{ "path": "C:/Users/me/Videos/Weekly sync.mp4" }`. A bad or missing path returns 400. **POST http://127.0.0.1:7882/import** ``` // response { "id": "", "dir": "C:\\Users\\me\\Videos\\AgentEyes\\" } ``` ## Where to go next An imported recording is a normal library recording, so you can add captions in another language to it right away - see [Multilingual subtitles](https://devthrottle.com/docs/agent-eyes/subtitles). For the full command set, see the [CLI reference](https://devthrottle.com/docs/agent-eyes/cli). --- # Multilingual subtitles > Translate a recording transcript into another language with the timing preserved, and burn the captions into a new subtitled video. Transcripts are stored as standard WebVTT, one file per language. Part of the DevThrottle documentation, section "AgentEyes". Canonical HTML version: https://devthrottle.com/docs/agent-eyes/subtitles Last updated: 2026-09-06 Once a recording has a transcript, AgentEyes can put it into another language and write those captions onto the video. It is two steps: **translate** the transcript into the language you want, then **subtitle** - burn those captions into a new video file. You can stop after translate if all you need is the caption file. ## Transcripts are WebVTT, one file per language Every transcript is stored as standard **WebVTT** (a `.vtt` subtitle file), named per language: `transcript.en.vtt` for English, `transcript.tr.vtt` for Turkish, and so on. Translating adds another `.vtt` beside the original; the recording can carry several languages at once. WebVTT is the format browsers and tools like Teams understand, so the caption files are useful on their own. ## Translate a transcript Translate takes the recording **id** (from the library, or printed by [import](https://devthrottle.com/docs/agent-eyes/import)) and a target language code: **Translate a recording into Turkish** ``` agenteyes translate --to tr ``` The **timing is preserved exactly** - each caption keeps its original start and end, so the translated captions line up with the video cue for cue. Use a short language code such as `tr`, `es`, `fr`, `de`, `ja`, or a regional code like `pt-BR`. It writes `transcript..vtt` and reports the language and how many cues it wrote: ``` [ok] translating 84 cue(s) en -> tr ... [ok] wrote 84 cue(s) -> transcript.tr.vtt ``` > **Note:** Translation uses DevThrottle's hosted AI, so the transcript text is sent to DevThrottle through your signed-in account to be translated. You need to be signed in to DevThrottle to translate. (Burning the captions in the next step is fully local - see below.) > **Note:** Translate is a command-line and API step only - there is no translate button in the app. Burning, below, has both. > **Tip:** Translate reads whatever transcript the recording already has - English if present, otherwise another language it already carries. If a recording has no transcript at all yet, transcribe it first by [importing](https://devthrottle.com/docs/agent-eyes/import) it or building a walkthrough from it. ## Burn the captions into a video Burning renders a brand-new video with the captions written onto it. It needs the recording to have a video and to already carry the `.vtt` for that language, so translate first unless the language is already there. **From the app.** Right-click the recording in the library and choose **Export with subtitles...**. It offers the languages that recording actually carries, burns the one you pick, and opens the folder on the new file. If the recording has no transcript at all it says so rather than producing an empty video. **From the command line.** The same engine, one command: **Burn Turkish captions into a new video** ``` agenteyes subtitle --lang tr ``` It writes `recording..subtitled.mp4` (for example `recording.tr.subtitled.mp4`) in the recording folder. Your original video is never touched - the subtitled version is a separate file. Burning runs locally with the bundled ffmpeg; nothing is sent anywhere for this step. ``` [ok] burning tr captions into recording.tr.subtitled.mp4 [ok] wrote recording.tr.subtitled.mp4 ``` > **Note:** If the language has no `.vtt` yet, subtitle stops with a clear message telling you to translate that language first, rather than producing an empty file. ## Over the Control API Both steps run over the local [Control API](https://devthrottle.com/docs/agent-eyes/control-api). `POST /transcripts/{id}/translate` Translate the recording's transcript. Body: `{ "to": "tr" }`. Returns the language, the cue count, and the VTT file name. **POST http://127.0.0.1:7882/transcripts//translate** ``` // response { "id": "", "dir": "...\\AgentEyes\\", "language": "tr", "cues": 84, "vtt": "transcript.tr.vtt" } ``` `POST /recordings/{id}/subtitle` Burn a language's captions into a new video. Body: `{ "language": "tr" }`. Returns the output file name. **POST http://127.0.0.1:7882/recordings//subtitle** ``` // response { "id": "", "dir": "...\\AgentEyes\\", "language": "tr", "output": "recording.tr.subtitled.mp4" } ``` ## Where to go next To bring an outside video in first so you have something to caption, see [Import a video](https://devthrottle.com/docs/agent-eyes/import). For every command and its options, see the [CLI reference](https://devthrottle.com/docs/agent-eyes/cli). --- # The agenteyes CLI > The agenteyes command-line tool: list devices, take screenshots, record audio and video, build a walkthrough, and run import, translate, and subtitle from a script. Part of the DevThrottle documentation, section "AgentEyes". Canonical HTML version: https://devthrottle.com/docs/agent-eyes/cli Last updated: 2026-09-06 `agenteyes.exe` is the AgentEyes engine as a command-line tool - the same engine the tray app uses. Use it to list devices, take screenshots, record audio and video, build a walkthrough, and run import, translate, and subtitle from a script. If you opted `agenteyes` onto your PATH at install, run it by name from any terminal. ## Commands **agenteyes** ``` agenteyes screens agenteyes shot --screen N [--region] [--out DIR] [--label NAME] agenteyes audio --screen N (--mic "NAME" | --loopback | --mix --mic "NAME") [--seconds N] agenteyes video --screen N [--mic "NAME"] [--mix | --loopback] [--region] [--seconds N] mic options: --no-denoise --no-gate --no-level --mic-vol PCT --sys-vol PCT camera: --camera "NAME" [--camera-fps N] # webcam -> camera.mp4 (video only) agenteyes package [--interval N | --scene THRESHOLD] agenteyes compose # render the camera into recording.mp4 agenteyes import # import an external video into the library agenteyes translate --to LANG # translate a transcript into LANG (e.g. tr), timing preserved agenteyes subtitle --lang LANG # burn LANG captions into a new subtitled MP4 (ffmpeg) agenteyes selftest # headless end-to-end self-test ``` ## What each command does - **screens** - list the monitors and microphones AgentEyes can see, with the index numbers you pass to `--screen` and the names you pass to `--mic`. - **shot** - take an instant screenshot of a monitor, or a region with `--region`. - **audio** - record microphone audio, system (loopback) audio, or a mix of both, with on-demand screenshots. - **video** - record screen video with audio; add `--region` to capture part of a screen. The mic options tune the audio (turn off denoise, the noise gate, or leveling, and set mic and system volume). `--camera "NAME"` also films a webcam to `camera.mp4` beside the screen video, at `--camera-fps N` if you want a rate other than the default. Video only. - **package** - transcribe a recording and assemble the walkthrough write-up. Point it at a recording folder or a bare video file. - **compose** - render the camera track into `recording.mp4` at the framing the preset chose, keeping the screen-only cut as `recording.screen.mp4`. `camera.mp4` is never changed, so you can change the framing and run `compose` again. It is also how a recording made before the camera arrived gets a composed video without recording anything twice. A recording with no camera track is reported and skipped. - **import** - bring an outside video into the library and transcribe it. See [Import a video](https://devthrottle.com/docs/agent-eyes/import). - **translate** - translate a recording's transcript into another language, timing preserved. See [Multilingual subtitles](https://devthrottle.com/docs/agent-eyes/subtitles). - **subtitle** - burn a language's captions into a new subtitled video. - **selftest** - run the headless end-to-end self-test. ## Session hotkeys While an `audio` or `video` session is running, these keys control it: ``` S = screenshot Q = stop ``` > **Note:** `package`, `import` and `translate` transcribe, title and translate through DevThrottle's hosted AI, so they need you to be signed in to DevThrottle and they send audio or text to the hosted service. `shot`, `audio`, `video`, `compose` and `subtitle` run locally. ## Where to go next To drive an already-running recorder instead of running one-off commands, see the [Control API](https://devthrottle.com/docs/agent-eyes/control-api). --- # The AgentEyes Control API > Drive the running AgentEyes recorder from a local script through its loopback REST Control API on 127.0.0.1:7882 - read state, record, screenshot, import, translate, and subtitle. Localhost only. Part of the DevThrottle documentation, section "AgentEyes". Canonical HTML version: https://devthrottle.com/docs/agent-eyes/control-api Last updated: 2026-09-06 The running AgentEyes app serves a local REST Control API so a script or an agent can drive the recorder without touching the tray window - read what it is doing, start and stop recordings, take screenshots, and run import, translate, and subtitle. It is the same engine the app uses, exposed over plain JSON. ## Address and scope The API binds to the loopback address, `127.0.0.1:7882` by default (the port is configurable, and the API can be turned off entirely). That binding decides who can CALL it: the machine it runs on, and nowhere else. It does not decide what the calls then do - some of them send data outward, and which ones is the next paragraph. `GET /` returns a discovery document that lists every endpoint, and `GET /health` and `GET /version` confirm it is up. > **Note:** Two separate boundaries, and it is worth keeping them apart. **Who can reach the API** is loopback-only - which also means anything that can run code on your PC can drive the recorder, and that is the point for local automation. **What a call does** varies by endpoint: recording, screenshots and subtitle burning stay on the machine, while `/import` and the translate step send your audio and text to DevThrottle's hosted AI to be transcribed and translated - see [Import a video](https://devthrottle.com/docs/agent-eyes/import). A call arriving over loopback is not a promise that it stays there. ## Read state `GET /status` What the recorder is doing right now. `GET /devices` Available monitors, microphones, and the cameras a recording can film. A machine with no camera answers with an empty `cameras` array - that is a fact about the machine, not an error. `GET /presets` The saved capture presets. `GET /recordings` The recording library, newest first. Add `?limit=` and `?offset=` to page. `GET /recordings/{id}` fetches one (with the languages it carries), `GET /recordings/{id}/shots` lists its screenshots, and `GET /recordings/{id}/transcript` returns its transcript. `GET /captures` The screenshot gallery. `GET /capture-info` Where snips are saved: the Windows default folder, the override you configured (or `null`), and the folder actually in use. ## Record and capture `POST /record/start` Start a recording. A `preset` name supplies the defaults; explicit fields override them. Fields: `preset?`, `mode`, `screen`, `source`, `mic?`, `camera?`, `cameraFps?`, `region?`, `denoise?`, `gate?`, `level?`, `micVol?`, `sysVol?`, `fps?`. `POST /record/shot` Take a screenshot during the current recording. `POST /record/stop` Stop the recording; it is finalized and transcribed in the background. `POST /screenshot` Take a screenshot outside a recording. Body: `{ "screen": 1, "region": [x,y,w,h] }` (region optional). `POST /capture` Capture to the save folder and clipboard. Body: `{ "mode": "full" | "monitor" | "region", "screen"?, "region"? }`. ## Import, translate, subtitle `POST /import` Import an external video into the library. Body: `{ "path": "C:/.../video.mp4" }`. Synchronous; returns the new recording `id` and `dir`. `POST /transcripts/{id}/translate` Translate the recording's transcript. Body: `{ "to": "tr" }`. Returns `language`, `cues`, and the `vtt` file name. `POST /recordings/{id}/subtitle` Burn a language's captions into a new video. Body: `{ "language": "tr" }`. Returns the `output` file name. ## Example **Import a video, then caption it in Turkish** ``` # 1) import - returns { "id": "...", "dir": "..." } curl.exe -s -X POST http://127.0.0.1:7882/import \ -H "Content-Type: application/json" \ --data-binary "{ \"path\": \"C:/Users/me/Videos/Weekly sync.mp4\" }" # 2) translate the transcript into Turkish curl.exe -s -X POST http://127.0.0.1:7882/transcripts//translate \ -H "Content-Type: application/json" \ --data-binary "{ \"to\": \"tr\" }" # 3) burn the Turkish captions into a new video curl.exe -s -X POST http://127.0.0.1:7882/recordings//subtitle \ -H "Content-Type: application/json" \ --data-binary "{ \"language\": \"tr\" }" ``` > **Note:** Errors come back as a small JSON envelope - `{ "error": "...", "code": "..." }` - with a matching HTTP status: 400 for bad input, 404 for an unknown recording, 409 for a lifecycle conflict such as starting a recording while one is already running. ## Where to go next For one-off commands rather than driving a running app, see the [CLI reference](https://devthrottle.com/docs/agent-eyes/cli). For the features these endpoints expose, see [Import a video](https://devthrottle.com/docs/agent-eyes/import) and [Multilingual subtitles](https://devthrottle.com/docs/agent-eyes/subtitles). --- # Your account dashboard > The logged-in home on devthrottle.com: your plan, your devices with their live Active/Idle signal, your subscription, and where devices, keys, usage, billing and settings live. Part of the DevThrottle documentation, section "Account and billing". Canonical HTML version: https://devthrottle.com/docs/account/overview Last updated: 2026-09-06 Your account lives at devthrottle.com. The app runs on your machine; the account is what ties your devices together, carries your subscription, and gives you a place to see usage and manage access. Signing in on the website lands you on the **Dashboard**. ## The Dashboard The Dashboard is a read-only glance at your setup: your registered devices, each with an **Active**/**Idle** signal from its heartbeat. Active means the heartbeat landed in the last 15 minutes; anything older reads Idle. A chip beside the heading names your plan: the plan you subscribe to and whether it is active or ending, or **Free** with a link to the plans on Billing. If your account still has a Pro trial from before trials ended, a line above the heading says how many days are left. It answers "is my machine up" in one look; management actions live on the dedicated pages below. Before any device has signed in, the list is replaced by a **Get DevThrottle** panel with the download and three setup steps, so the dashboard is also where a new account starts. ## The pages - [Devices](https://devthrottle.com/docs/account/devices) - every machine and phone connected to your account: rename them, manage the addresses other machines use to reach them, and revoke the ones you no longer trust. - [API keys](https://devthrottle.com/docs/account/api-keys) - create and manage the keys your own tools use to call the [DevThrottle API](https://devthrottle.com/docs/api/overview). - [Usage](https://devthrottle.com/docs/account/usage) - what your account has done, by service, by model and by key, down to individual requests. - [Billing](https://devthrottle.com/docs/account/billing) - your plan: what it includes, its current state, and the Remote and Pro subscriptions. - [Settings](https://devthrottle.com/docs/account/settings) - your nickname, which emails DevThrottle sends you, and the product usage data switch. The sidebar also carries **Models** and **Download**. Until your first machine is connected it starts with **Get set up** instead of the Dashboard; once a machine is connected, Get set up gives way to the Dashboard. > **Note:** An account takes only an email and starts on Free, and running your own agents through DevThrottle costs nothing. The Cockpit and the phone app come with [Remote](https://devthrottle.com/pricing); dictation, spoken replies, and the wingman are included in [Pro](https://devthrottle.com/pricing). Prepaid credits are separate and apply only to direct catalog-model calls on the [DevThrottle API](https://devthrottle.com/docs/api/overview). --- # Devices > Every machine and phone connected to your account: how devices get approved, renaming them, managing the addresses other machines reach them on, and revoking the ones you no longer trust. Part of the DevThrottle documentation, section "Account and billing". Canonical HTML version: https://devthrottle.com/docs/account/devices Last updated: 2026-09-06 Devices is the list of every machine and phone connected to your account - and the place you cut one off. Each row is a device you approved: the workstation running the [Director](https://devthrottle.com/docs/director/overview), the machine hosting your [Gateway](https://devthrottle.com/docs/gateway/overview), the phone you [paired](https://devthrottle.com/docs/mobile/pairing). ## How devices get on the list You approve every one. When DevThrottle starts on a new machine, it opens your browser to an approval page that names the device and asks you to approve or deny it; phones go through the same idea via [pairing](https://devthrottle.com/docs/mobile/pairing). Nothing registers itself silently. ## What a row tells you Name, platform, type, app version, when it was last seen, and its addresses. The last-seen column carries the **Active**/**Idle** badge: Active means the device's heartbeat landed in the last 15 minutes, so an Idle row is a machine that is off or offline, not a broken one. ## What you can do here - **Rename** - click the name and type a new one. Give devices names you will recognize later ("desk-pc", "old laptop", "phone"), which matters on the day you need to revoke the right one. - **Manage addresses** - a device carries a list, not one address: the addresses other machines use to reach its gateway, in priority order, with the first one tried first. **Manage** in the Addresses column adds, removes and reorders them, and the primary one is also an **Open gateway** link. If a machine registered itself with the wrong address, this is where you fix it. - **Revoke** - cut a device's access. It asks you to confirm first. A revoked device's key stops working; the device can only come back by going through approval again. > **Warning:** Lost laptop, stolen phone, machine you sold: revoke it here first. Revocation is the kill switch - it invalidates that device's key without touching your account or your other devices. > **Note:** Revoking a device does not delete anything on it and does not stop programs running on it - it cuts the device's access to your DevThrottle account and its hosted features. --- # API keys > Create and manage the keys your own tools use to call the DevThrottle API - shown once at creation, revocable any time, with per-key usage attribution. Part of the DevThrottle documentation, section "Account and billing". Canonical HTML version: https://devthrottle.com/docs/account/api-keys Last updated: 2026-09-06 API keys let your own scripts and tools call the [DevThrottle API](https://devthrottle.com/docs/api/overview) under your account. The app itself does not need one - your devices authenticate as devices - so keys are for the things *you* build. ## Creating a key 1. **Open API Keys and create** Name the key for what will use it - "build server", "usage script" - because usage is reported per key and a good name is what makes that report readable. 2. **Copy it now** The full key is shown once, at creation. Copy it into your secret store; after you leave the page, only the key's name and prefix remain visible. 3. **Use it as a bearer token** Send it in the Authorization header on API calls - see [authentication](https://devthrottle.com/docs/api/authentication) for the exact shape. ## Managing keys - **Rename** - click a key's name and type a new one. The name is what makes the usage report readable, so it is worth correcting when an integration changes. - **Created and Last used** - two columns on the table. Last used is how you find the key nothing has touched for months before you revoke it. - **Per-key usage** - every key's activity shows separately in [Usage](https://devthrottle.com/docs/account/usage), so you can tell which integration is doing what. - **Revoke** - deleting a key stops it immediately, after a confirmation. If a key leaks, revoke it and create a fresh one; your other keys and devices are unaffected. > **Warning:** Treat keys like passwords: never commit one to a repository, and prefer one key per integration so a leak has a small blast radius and a clean revoke. > **Note:** Direct catalog-model calls made with a key are billed from prepaid credits - keys cannot spend money you have not loaded. Dictation, spoken replies, and the wingman are included in [Pro](https://devthrottle.com/pricing), key or no key. --- # Usage > What your account has done - activity by service, by model, and by API key, and the recent requests behind any one key. Part of the DevThrottle documentation, section "Account and billing". Canonical HTML version: https://devthrottle.com/docs/account/usage Last updated: 2026-09-06 Usage is the record of what your account has done - the requests your keys and devices made, stated in each service's own units - so the service never feels like a black box. You read it by service, by model, and by key, and a picker beside the heading moves you between the months your account has activity for; a day-by-day chart exists only for the service's administrators. ## The views - **By service** - one card per service: inference, transcription, text to speech, and the wingman, each stated in the service's own unit - tokens, audio duration, characters - with the request count under each. - **By model** - which models the requests went to. Model names are shown exactly as you request them through the [models list](https://devthrottle.com/docs/api/models). - **By key** - activity attributed to each [API key](https://devthrottle.com/docs/account/api-keys), with a drill-down per key. Name your keys well and this view tells you which integration is doing what. - **Recent activity** - on a key's own usage view (open it from the By key table), the individual recent requests and what each was (transcription duration, tokens, characters). > **Note:** Dictation, spoken replies, and the wingman are included in Pro with no usage charge. Direct catalog-model API calls are billed from prepaid credits. Agents running on your own subscriptions and keys never appear here - running them costs nothing. --- # Billing > Your plan - Free, Remote or Pro - subscribing, the 30-day money-back guarantee, and everything in a subscription included with no usage charge. Prepaid credits are separate and apply only to direct catalog-model API calls. Part of the DevThrottle documentation, section "Account and billing". Canonical HTML version: https://devthrottle.com/docs/account/billing Last updated: 2026-09-06 Billing is where your subscription lives. Everything in a subscription - dictation, spoken replies, and the wingman on Pro - is included with no usage charge, so this page is mostly a place to check your plan: which plan you are on, and when it renews. ## Your plan A new account is on **Free**: the Director on every machine you own, signed in to your account. Free does not include the Cockpit, the phone app, or any of the AI. From the Billing page you can subscribe to **Remote** - the gateway we run for you, the Cockpit in any browser and the phone app - or to **Pro**, which is Remote plus the AI: dictation, spoken replies, the wingman and the Mentor. What each costs is on [pricing](https://devthrottle.com/pricing). There is no trial: your card is charged when you subscribe. If you leave the checkout without paying, nothing is charged and your account stays on Free. If you hold an earlier plan that is no longer sold, Billing names it and you keep it for as long as you stay subscribed. Subscriptions are monthly, paid by card through Stripe checkout, and you can cancel any time; after cancellation the subscription stays active through the period already paid for. Cancelling, changing the card and downloading invoices all happen behind **Manage subscription**, which hands you to Stripe's own portal. ## 30-day money-back guarantee If you ask within 30 days of your first payment, we refund it in full - once per person. Ask by email at email@devthrottle.com. The refund ends the subscription and your account returns to Free. The full wording is in the [Terms of Service](https://devthrottle.com/terms). ## Credits Prepaid credits are separate from a subscription and apply to one thing: direct catalog-model calls on the [DevThrottle API](https://devthrottle.com/docs/api/overview). Dictation, spoken replies, and the wingman never draw on credits - they are included in Pro. Everything to do with credits - the balance, adding to it, and the record of payments - sits on the Billing page. If your Billing page shows no credit section, there is nothing there for you to do: nothing your subscription includes draws on credits. > **Note:** Nothing on this page is needed to run your agents or to use what your subscription includes. --- # Settings > The account console Settings page: your nickname, the three kinds of email DevThrottle sends and which two you can switch off, and the account-level product usage data control. Part of the DevThrottle documentation, section "Account and billing". Canonical HTML version: https://devthrottle.com/docs/account/settings Last updated: 2026-09-06 Settings is the small page that holds who you are to DevThrottle and what DevThrottle sends you: the email address you signed in with, the name it calls you, which emails leave, and whether you share product usage data. It is the page to open when the emails are not the ones you want. ## Your account Three facts sit at the top and are not editable here: the **email** you signed in with, your **role**, and your account's **status**. The email is your identity - devices, keys and your subscription all hang off it. ## Nickname Pick a nickname and DevThrottle calls you that instead of your real name - when the assistant talks to you, and anywhere you choose to be public. Leave it blank and it uses the name you signed up with; **Clear** puts you back there at any time. A nickname is 2 to 30 characters and may use letters, numbers, spaces, hyphens and underscores. It also has to be one nobody else has taken - if it is, saving tells you so and asks for another. ## Email Three kinds of email leave DevThrottle and they are separate on purpose. Turning off one does not turn off the others. - **Account and security** - password resets, sign-in alerts, receipts and failed payments. This one has no switch and is shown anyway, so you can see it is separate: switching it off is how people lose access to an account without being told. - **Product notifications** - your daily report and messages about your own sessions. Nothing promotional. - **News and tips** - what DevThrottle can do, what has shipped, and the occasional note while you are getting started. This is the same switch as the unsubscribe link at the bottom of those emails, so using either one is enough. Each switch saves as you flip it, and what the page shows afterwards is what was stored - if a change does not save, the switch goes back where it was rather than showing you something that is not true. > **Tip:** Getting mail you did not want is almost always **News and tips**. Turning it off leaves your daily report and your receipts alone. ## Product usage data One switch, on by default, that you can turn off at any time. What it does today is narrower than its name suggests, and it is worth saying plainly: **it records your preference, and nothing currently collects anything on the strength of it.** The usage-telemetry program it was built for was removed in July 2026 and nothing replaced it. Leave it on and no extra data is gathered; turn it off and none stops, because there is none. What IS recorded, with no switch over it, is your sign-in - see [what leaves your machine](https://devthrottle.com/docs/reference/telemetry), which also covers the session conversations your Director sends to your Gateway. Those are not governed by this control either. The switch is kept because the consent it expresses is real: if collection returns, this is what it will answer to. This is your account's switch, and it is the only one. DevThrottle used to have a second, fleet-wide switch in the Cockpit; that went with the usage-telemetry program it belonged to, and nothing replaced it. What is recorded either way, and what your Director sends to your Gateway, is on [what leaves your machine](https://devthrottle.com/docs/reference/telemetry). > **Note:** How your data is handled is set out in the Privacy Policy and the Terms of Service, both linked at the foot of the Settings page itself. --- # DevThrottle API > An OpenAI-compatible API behind one dt_ key: chat completions, transcription, speech, and models. Direct catalog-model calls are billed from prepaid credits; Pro-included services stay included. Part of the DevThrottle documentation, section "DevThrottle API". Canonical HTML version: https://devthrottle.com/docs/api/overview Last updated: 2026-09-06 The DevThrottle API is one key for the hosted AI your tools use - an OpenAI-compatible surface, so anything that speaks the OpenAI API shape can point at DevThrottle by changing the base URL and the key. The app does not need any of this to run your agents; the API exists for the things you build yourself. ## Base URL **Base URL** ``` https://devthrottle.com/api/v1 ``` Authentication is a DevThrottle API key (`dt_...`) sent as a bearer token - see [authentication](https://devthrottle.com/docs/api/authentication). ## What is available today - [Chat completions](https://devthrottle.com/docs/api/chat) - OpenAI-compatible `POST /chat/completions`, including streaming. - [Transcription](https://devthrottle.com/docs/api/transcription) - OpenAI-compatible `POST /audio/transcriptions`: audio in, text out. - [Speech](https://devthrottle.com/docs/api/speech) - OpenAI-compatible `POST /audio/speech`: text in, audio out. - [Models](https://devthrottle.com/docs/api/models) - `GET /models`, the catalog of ids you can call. It is the same catalog for every account. - [Errors and limits](https://devthrottle.com/docs/api/errors) - the error shape and status codes. Image generation is not available. ## How it is paid One rule: direct catalog-model calls are billed from prepaid credits - pay-per-use, and nothing can spend past the credits you loaded. Dictation, spoken replies, and the wingman are included in [Pro](https://devthrottle.com/pricing) with no usage charge - and that entitlement covers [transcription](https://devthrottle.com/docs/api/transcription) and [speech](https://devthrottle.com/docs/api/speech) reached through this API too. Every request appears in [Usage](https://devthrottle.com/docs/account/usage), per key and per model. > **Note:** OpenAI compatibility means request and response shapes, including SSE streaming. Point an existing OpenAI SDK at the base URL above with your `dt_` key and most code needs no other change. --- # Authentication > Authenticate with a dt_ API key as a bearer token - curl and OpenAI SDK examples, and the key-handling rules. Part of the DevThrottle documentation, section "DevThrottle API". Canonical HTML version: https://devthrottle.com/docs/api/authentication Last updated: 2026-07-06 Every API request authenticates with a DevThrottle API key - a token starting with `dt_` that you create in [your account](https://devthrottle.com/docs/account/api-keys). Send it as a standard bearer token: **Authorization header** ``` Authorization: Bearer dt_your_key_here ``` **Example: curl** ``` curl https://devthrottle.com/api/v1/models \ -H "Authorization: Bearer $DEVTHROTTLE_API_KEY" ``` **Example: OpenAI SDK (Python)** ``` from openai import OpenAI client = OpenAI( base_url="https://devthrottle.com/api/v1", api_key="dt_your_key_here", ) ``` ## Key facts - The full key is shown once, at creation. Store it in a secret manager. - A missing or invalid key returns `401` with an OpenAI-shaped error body - see [errors](https://devthrottle.com/docs/api/errors). - Activity is attributed per key in [Usage](https://devthrottle.com/docs/account/usage), so use one key per integration. - Revoking a key in [API keys](https://devthrottle.com/docs/account/api-keys) stops it immediately; other keys are unaffected. > **Warning:** A key acts as your account - direct catalog-model calls it makes are billed from your prepaid credits. Never commit a key to a repository or ship one in client-side code - treat it exactly like a password. --- # Chat completions > OpenAI-compatible POST /chat/completions with streaming - request shape, model selection from GET /models, and the 429 burst limit and 402 a client must handle. Part of the DevThrottle documentation, section "DevThrottle API". Canonical HTML version: https://devthrottle.com/docs/api/chat Last updated: 2026-09-06 OpenAI-compatible chat completions. Send the same request body you would send to the OpenAI API; DevThrottle routes it to the model you name and streams the response back. `POST /chat/completions` Create a chat completion. Supports server-sent-event streaming with `"stream": true`. ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Required | A model id from GET /models. Unknown models are rejected outright - there is no silent substitution. | | `messages` | array | Required | The conversation, OpenAI chat format: objects with role and content. | | `stream` | boolean | Optional | true streams tokens as SSE chunks in the OpenAI chunk format. | | `max_tokens, temperature, ...` | various | Optional | Standard OpenAI sampling parameters are passed through to the model. | **Example** ``` curl https://devthrottle.com/api/v1/chat/completions -H "Authorization: Bearer $DEVTHROTTLE_API_KEY" -H "Content-Type: application/json" -d '{ "model": "MODEL_ID_FROM_/models", "messages": [{"role": "user", "content": "Say hello."}] }' ``` ## Response The OpenAI chat-completion object (or SSE chunks when streaming), including the `usage` block with token counts. The same usage appears in [your Usage page](https://devthrottle.com/docs/account/usage). ## Models and billing The models you can put in `model` come from [GET /models](https://devthrottle.com/docs/api/models); the catalog is the same for every account. Chat completions are direct catalog-model calls, billed from prepaid credits per token; each request shows in [Usage](https://devthrottle.com/docs/account/usage). When there is nothing left to bill, the request is declined before it runs. An empty credit balance returns `402` with `insufficient_credits`, and your own monthly spending limit returns `402` with `monthly_limit_reached`. In both cases no model was called and nothing was debited - top up, or raise the limit in [Billing](https://devthrottle.com/docs/account/billing). ## Limits A burst limit applies per account. Over it, the endpoint answers `429` with `rate_limit_exceeded` and `"type": "rate_limit_error"`: slow down and retry after a moment rather than hot-looping. No per-account quota is published yet - see [errors and limits](https://devthrottle.com/docs/api/errors) for the full status-code list and what each one means. > **Note:** A request that fails returns an error without debiting credits - you pay for completions you received, not for attempts. Error shapes are on [errors and limits](https://devthrottle.com/docs/api/errors). --- # Transcription > OpenAI-compatible POST /audio/transcriptions - the transcript comes back as the speech model recognised it, included with Pro, with a deliberately forgiving model parameter. Part of the DevThrottle documentation, section "DevThrottle API". Canonical HTML version: https://devthrottle.com/docs/api/transcription Last updated: 2026-09-06 OpenAI-compatible audio transcription - the same endpoint DevThrottle's own [voice features](https://devthrottle.com/docs/voice/overview) use. Transcription is included in [Pro](https://devthrottle.com/pricing) with no usage charge: the same entitlement that powers dictation in the app covers the calls you make with your own key. Every call needs a [dt_ key](https://devthrottle.com/docs/api/authentication) - there is no keyless path to this endpoint. `POST /audio/transcriptions` Transcribe an audio file. Multipart form data, OpenAI shape. ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `file` | file | Required | The audio to transcribe. Same formats as OpenAI: flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, wav, webm. Max 4 MB per request (see Limits). | | `model` | string | Optional | Accepted for OpenAI compatibility (clients send whisper-1, gpt-4o-transcribe, ...). DevThrottle serves the request with its active speech-to-text model regardless of this value; see GET /api/v1/models for the current id. | | `response_format` | string | Optional | json (default), text, or verbose_json - shaped to what you asked for. | | `language` | string | Optional | Optional language hint. | **Example** ``` curl https://devthrottle.com/api/v1/audio/transcriptions -H "Authorization: Bearer $DEVTHROTTLE_API_KEY" -F file=@recording.wav -F model=whisper-1 ``` ## What comes back is what was said The endpoint returns the speech model's own words. Nothing between the model and you rewrites, summarises, translates or cleans up the transcript - it is shaped into the response format you asked for and returned as it was recognised. That is deliberate: your words become instructions to an agent, so a word you did not say is an instruction you did not give. One consequence for API callers: the [custom dictionary](https://devthrottle.com/docs/voice/dictionary) is applied by the DevThrottle app on your own machine, not by this endpoint. A direct call here gets no corrections at all - if you need your own terms fixed, apply your word list to the text you get back. ## Response `json` returns `{ "text": ... }`, `text` returns the transcript as plain text, and `verbose_json` returns the fuller object the speech model produced - language, duration, text and, where the model supplies them, segments. Each request's audio duration appears in [Usage](https://devthrottle.com/docs/account/usage). ## Limits Each request is a single, self-contained transcription with a **4 MB maximum body size**. A larger upload returns `413 payload_too_large`. Included use is also bounded overall: transcription is an included AI feature, and included AI features share a monthly fair-use limit. An account that reaches it gets `402` with `fair_use_limit_reached` until the limit resets at the start of the next month. It is not a credit balance - loading credits does not lift it. > **Note:** For recordings larger than 4 MB, split the audio into sub-4 MB parts and transcribe each, then join the text. The DevThrottle gateway does this for you automatically (chunking long recordings on silence and transcribing the parts in parallel), so end users never hit the per-request limit. ## Who can call it Transcription comes with [Pro](https://devthrottle.com/pricing) (and with a Pro trial granted before trials ended, while it runs). An account with no active subscription or trial is declined with `402` and `subscription_required` - a subscription enables it, not loading credits, because this endpoint never spends credits at all. ## Status codes - **400** - the upload could not be parsed, or the `file` field is missing. - **401** - `invalid_api_key`: missing, malformed, or revoked key. - **402** - `subscription_required` or `fair_use_limit_reached`, as above. - **404** - `not_found`: wrong path or wrong method (this endpoint is POST only). - **413** - `payload_too_large`: over 4 MB. - **500** - `internal_error`. - **502** - `upstream_error`: the speech service failed. - **504** - `upstream_unavailable` or `upstream_timeout`: the speech service is unreachable or did not answer in time. Retry after a short back-off. Full error shapes are on [errors and limits](https://devthrottle.com/docs/api/errors). > **Note:** The `model` parameter is deliberately forgiving: OpenAI-shaped clients hard-code their own model names, so DevThrottle accepts them and uses its own speech model - your client works unmodified. --- # Speech > OpenAI-compatible POST /audio/speech - text in, streamed audio out. Included with Pro; voices come from GET /models?type=speech. Part of the DevThrottle documentation, section "DevThrottle API". Canonical HTML version: https://devthrottle.com/docs/api/speech Last updated: 2026-09-06 OpenAI-compatible text to speech - the same endpoint DevThrottle's own spoken replies use. Send text, get audio bytes back. It is included in [Pro](https://devthrottle.com/pricing) with no usage charge: the same entitlement that speaks replies in the app covers the calls you make with your own key. Every call needs a [dt_ key](https://devthrottle.com/docs/api/authentication). `POST /audio/speech` Synthesise speech from text. JSON in, audio bytes out - streamed, not buffered. ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Required | A speech model id from GET /models?type=speech. Unknown models are rejected outright - there is no silent substitution. | | `input` | string | Required | The text to speak. Maximum 4,000 characters; longer text returns 400 input_too_long, and the error states the limit. | | `voice` | string | Optional | A voice id from the model's voices list in GET /models?type=speech. Omit it and the model's default voice is used. | | `response_format` | string | Optional | mp3 (default), opus, flac, wav, or pcm. Anything else returns 400 unsupported_response_format. | Only those four fields are sent on: anything else in the body is dropped rather than forwarded, so a field that is not documented here has no effect. **Example** ``` curl https://devthrottle.com/api/v1/audio/speech -H "Authorization: Bearer $DEVTHROTTLE_API_KEY" -H "Content-Type: application/json" -d '{ "model": "MODEL_ID_FROM_/models?type=speech", "input": "Your session finished." }' --output speech.mp3 ``` ## Response The audio itself, not JSON: raw bytes with the `Content-Type` of the format that was synthesised (`audio/mpeg` for mp3, and the matching type for the others). The bytes stream as they arrive, so a client can start playing before synthesis finishes. An error, by contrast, is always the OpenAI-shaped JSON body - so branch on the status code, not on the content type. ## Voices Voices belong to the model, so the catalog is where you read them: [GET /models?type=speech](https://devthrottle.com/docs/api/models) returns each model's `voices` (the ids you can send), `voiceDetails` (the same ids with the language each one speaks, so you can offer only the voices that match a user's language), and `defaultVoice`. Fetch them rather than hard-coding: which voices exist is a property of the model being served. ## Who can call it, and how it is paid Speech comes with [Pro](https://devthrottle.com/pricing) (and with a Pro trial granted before trials ended, while it runs). It never spends credits, on any path - so an account with no active subscription or trial is declined with `402` and `subscription_required`, and loading credits does not change that. Included AI features also share a monthly fair-use limit; an account that reaches it gets `402` with `fair_use_limit_reached` until it resets at the start of the next month. Every call still appears in [Usage](https://devthrottle.com/docs/account/usage). ## Status codes - **400** - `invalid_request_error` (the body was not valid JSON), `missing_model`, `missing_input`, `invalid_input`, `unknown_model`, `input_too_long`, or `unsupported_response_format`. - **401** - `invalid_api_key`. - **402** - `subscription_required` or `fair_use_limit_reached`, as above. - **404** - `not_found`: wrong path or wrong method (this endpoint is POST only). - **500** - `internal_error`. - **502** - `upstream_error`: the speech service could not be reached. When the speech service answers with an error of its own, that status reaches you unchanged - a `429` arrives as a `429`, with its `Retry-After` when it sent one - while the body is replaced with DevThrottle's own wording. Treat any non-2xx as an error rather than switching only on the list above; the full shape is on [errors and limits](https://devthrottle.com/docs/api/errors). > **Note:** Audio you never received is never metered: if synthesis fails, or the stream breaks mid-clip, the attempt is recorded as a failure and nothing is charged against your account. --- # Models > GET /models - the catalog of models you can call, the same for every account, plus the ?type=chat, ?type=speech and ?type=transcription filters. Part of the DevThrottle documentation, section "DevThrottle API". Canonical HTML version: https://devthrottle.com/docs/api/models Last updated: 2026-09-06 The models endpoint tells you what you can call. Treat it as the source of truth: a model that is not in it will be rejected by [chat completions](https://devthrottle.com/docs/api/chat). There are no plan tiers on the catalog - every account with a valid key sees the same list. `GET /models` List the models available to the caller. OpenAI list shape: `{ "object": "list", "data": [ { "id": ... }, ... ] }`. **Example** ``` curl https://devthrottle.com/api/v1/models -H "Authorization: Bearer $DEVTHROTTLE_API_KEY" ``` ## What the default response contains With no query string you get everything callable in one request: the chat models, the speech models, and the current speech-to-text model. Every entry carries a `type` field, so you can sort them yourself, and `owned_by` is `devthrottle` on all of them - the endpoint never names a hosting provider. ## Filters - `?type=chat` - the models [chat completions](https://devthrottle.com/docs/api/chat) accepts. - `?type=speech` - the models [speech](https://devthrottle.com/docs/api/speech) accepts. Each entry also carries its voice ids in `voices`, the same ids with their language in `voiceDetails`, and the `defaultVoice` used when you send none. - `?type=transcription` - the single speech-to-text entry. The transcription entry advertises the id [transcription](https://devthrottle.com/docs/api/transcription) is serving right now. Read it rather than assume it: that endpoint accepts whatever model name an OpenAI-shaped client sends, so the catalog is the only place the current id is stated. ## Practical advice - Fetch the list at startup rather than hard-coding ids - what is available changes over time, and unknown models are hard errors by design (no silent substitution, ever). - Model ids are public names; use them as-is in the `model` field. ## Status codes - **401** - `invalid_api_key`: this endpoint needs a valid `dt_` key like every other one. - **405** - `method_not_allowed`: only `GET` is supported here. - **500** - `internal_error`. > **Note:** The catalog is not a permission list. It says what DevThrottle serves; whether a given call runs also depends on how it is paid - credits for direct catalog-model calls, a [Pro](https://devthrottle.com/pricing) subscription or trial for the included services. See [errors and limits](https://devthrottle.com/docs/api/errors). --- # Errors and limits > The OpenAI-shaped error body and every status code the API returns - 400, 401, 402, 404, 405, 413, 429 and 5xx - plus what is and is not published about rate limits. Part of the DevThrottle documentation, section "DevThrottle API". Canonical HTML version: https://devthrottle.com/docs/api/errors Last updated: 2026-09-06 Errors come back OpenAI-shaped, so existing SDK error handling works unchanged: **Error body** ``` { "error": { "message": "human-readable explanation", "type": "invalid_request_error | api_error | ...", "code": "machine_readable_code" } } ``` Handle on `code` rather than on the message: the codes below are stable, the wording is not. ## Status codes - **400** - invalid request. On [chat](https://devthrottle.com/docs/api/chat): `invalid_json`, `missing_model`, `unknown_model` and `model_not_hosted`. On [speech](https://devthrottle.com/docs/api/speech): `invalid_request_error`, `missing_model`, `missing_input`, `invalid_input`, `unknown_model`, `input_too_long` and `unsupported_response_format`. On [transcription](https://devthrottle.com/docs/api/transcription): an upload that could not be parsed or a missing `file` field. DevThrottle never silently substitutes a different model; fix the id against [GET /models](https://devthrottle.com/docs/api/models). - **401** - `invalid_api_key`: missing, malformed, or revoked API key. See [authentication](https://devthrottle.com/docs/api/authentication). - **402** - the request was not run, and nothing was debited. Four codes, and they need different fixes:Dictation, spoken replies, and the wingman never cost credits - a declined included service is an entitlement outcome, never a balance one. - `insufficient_credits` - a direct catalog-model call with an empty credit balance. Top up. - `monthly_limit_reached` - your own monthly spending limit. Raise it in [Billing](https://devthrottle.com/docs/account/billing). - `subscription_required` - an included service called by an account with no active subscription or trial. Fixed by an active [Pro](https://devthrottle.com/pricing) subscription or trial, not by credits. - `fair_use_limit_reached` - the monthly fair-use limit on included AI features. It resets at the start of the next month; credits do not lift it. - **404** - `not_found`: an address the API does not serve, including the right path with the wrong method on `/chat/completions` and the `/audio/*` endpoints, which are POST only. - **405** - `method_not_allowed`: sent by [GET /models](https://devthrottle.com/docs/api/models) for any other verb. - **413** - `payload_too_large`: audio over the 4 MB per-request limit on [transcription](https://devthrottle.com/docs/api/transcription). - **429** - `rate_limit_exceeded`, with `"type": "rate_limit_error"`: the per-account burst limit on chat completions. Slow down and retry. - **500** - `internal_error` (or `config_error`): something is wrong on our side, not in your request. - **502** - `upstream_error`: the model service failed or could not be reached. - **504** - `upstream_unavailable` or `upstream_timeout` on [transcription](https://devthrottle.com/docs/api/transcription): the speech service was unreachable, or did not answer in time. No request was billed. One shape to expect beyond that list: when the model service itself rejects a chat or speech request, its status passes through to you - so a client should treat any non-2xx as an error rather than switching only on the codes above. A failed request is never debited, whichever status it carries. ## Rate limits A burst limit is enforced per account on chat completions and returns `429`. There is no published per-account quota yet - when one is published it will appear here. Until then, write clients the way you would for any rate-limited API: handle non-200s, back off on 429 and 5xx, and do not hot-loop retries. The included AI services - transcription and speech - are bounded differently: not by a request rate but by a monthly fair-use limit, which answers `402 fair_use_limit_reached` and resets at the start of the next month. Retrying does not clear it. > **Note:** The one error worth designing for up front is **402**: it is terminal for that request, not retriable. Read the `code` to know which of the four you hit - crediting an account does nothing for `subscription_required`, and subscribing does nothing for `insufficient_credits`. --- # The cc-* CLI tools > The command-line tools DevThrottle puts on your PATH - the nine that install, how the setup engine manages and repairs them, and where the wider toolbox lives. Part of the DevThrottle documentation, section "CLI". Canonical HTML version: https://devthrottle.com/docs/cli/overview Last updated: 2026-09-16 DevThrottle ships a small set of command-line tools onto your PATH - the `cc-*` tools. They exist for your agents as much as for you: an agent that needs to produce a PDF report or a Word document can call a tool that is guaranteed present, instead of improvising a different approach on every machine. ## What installs The installer delivers a deliberately small set - nine tools, each covered command by command in the [tool reference](https://devthrottle.com/docs/cli/reference): - Documents: `cc-pdf`, `cc-html`, `cc-word` - Markdown to a finished PDF, web page, or Word document, and back again. - Email: `cc-gmail`, `cc-outlook` - read, search, send, and manage mail and calendar from the command line. - Images: `cc-image` - describe a picture, read the text out of one, and resize or convert locally. - Vault: `cc-vault` - a personal store of contacts, tasks, goals, ideas, and documents, with search over all of it. - Secrets: `cc-secrets` - a password you store by hand, which a session can use to run a command or log in to a site without the model ever seeing it ([full guide](https://devthrottle.com/docs/cli/secrets)). - The fleet: `cc-devthrottle` - your sessions, the messages between them, missions, workflows, skills, schedules, and setup. Alongside them, the installer manages the apps themselves: the Director, the [Gateway](https://devthrottle.com/docs/gateway/overview), and the Launcher tray app. ## Managed, not dumped Tools are installed and updated by DevThrottle's own setup engine - versioned, hash-checked, and repairable. The Director shows their health in two places: a **DevThrottle tools** row on the home readiness card, which counts how many of the shipped tools are working and carries a **Fix it** button that rebuilds a broken install in one click, and a **Tools** tab in Settings with a row per tool and what each check found. DevThrottle also repairs a broken tool by itself when it starts, once per run, so most of the time there is nothing for you to notice - and a broken tool install is never a support ticket. ## The wider toolbox The shipped set is the floor, not the ceiling. The open source repository holds a larger collection of `cc-*` tools - buildable if you are working in the repository, and deliberately not installed: a tool is bundled only once it earns its place, and one that is not bundled is left out of the Tools tab entirely rather than shown as a row you cannot fix. Everything is MIT-licensed and readable in the [repository](https://github.com/thefrederiksen/devthrottle). **Quick check that tools are on PATH** ``` cc-pdf --help ``` > **Note:** The tools are plain executables on PATH: none of them needs the Director to be running, and they work in any terminal and from any agent. Several do need a credential first - `cc-gmail` and `cc-outlook` sign in once with `auth`, `cc-image`'s AI commands take your account key, `cc-vault`'s search and ask need a model key you supply, and `cc-devthrottle`'s fleet commands and `cc-secrets login` run inside a DevThrottle session, and `cc-secrets` only uses passwords you have added to it by hand. The [tool reference](https://devthrottle.com/docs/cli/reference) says which, per tool. --- # CLI tool reference > Reference for the nine tools the installer ships on PATH: document converters (cc-pdf, cc-html, cc-word), the cc-devthrottle fleet CLI and its sixteen command groups, email (cc-gmail, cc-outlook), images (cc-image), the cc-vault knowledge vault, and cc-secrets. Part of the DevThrottle documentation, section "CLI". Canonical HTML version: https://devthrottle.com/docs/cli/reference Last updated: 2026-09-16 Reference for the command-line tools the DevThrottle installer puts on your PATH. They exist so your agents (and you) have a reliable, pre-installed way to produce documents, send email, work with images, keep a personal knowledge vault, let an agent use a password it never sees, and drive the DevThrottle fleet itself. Nine tools ship; nothing else is listed here. Every tool answers `--help` with its full command list. ## Document conversion: cc-pdf, cc-html, cc-word Three converters that turn a Markdown file into a finished document - and read a finished document back to Markdown. They share the same two commands, the same option style, and the same theme set, so learning one is learning all three. **Usage** ``` cc-pdf from-markdown input.md -o output.pdf --theme boardroom cc-html from-markdown input.md -o output.html --theme paper cc-word from-markdown input.md -o output.docx --theme boardroom cc-pdf from-markdown input.md -o output.pdf --page-size a4 --margin 1in cc-pdf to-markdown report.pdf -o report.md ``` - `from-markdown` - Markdown in, finished document out. `to-markdown` - the other direction, extracting the document's embedded images as it goes. - `-o` - output file path. Required on `from-markdown`; on `to-markdown` it defaults to the input name with a `.md` extension. - `--theme` - document style, `paper` by default (see themes below). - `--page-size` - `a4` (the default) or `letter` (cc-pdf only). - `--margin` - page margin, `1in` by default (cc-pdf only). - `--css` - a custom CSS file to style the output (cc-pdf and cc-html). - `--strict-assets` - fail instead of carrying on when a local image cannot be embedded (cc-pdf and cc-html). - `--force` overwrites an existing output file, `--no-clobber` skips instead, and `--quiet` suppresses progress without hiding errors. The shared themes, from `cc-pdf --themes`: - `boardroom` - corporate, executive style with serif fonts; the pick for professional reports. - `paper` - minimal and clean (the default). - `terminal` - technical, monospace. - `blueprint` - technical documentation. - `thesis` - academic. - `spark` - creative, colorful. - `obsidian` - dark theme. ## cc-devthrottle The fleet command surface: talk to your running sessions, the machines they run on, and the Gateway that holds them together - the same tool your agents use to message each other. The fleet commands call the Gateway with the calling session's own key; every session launched by a Director attached to a Gateway carries that credential in its environment (`CC_GATEWAY_URL` and `CC_GATEWAY_SESSION_KEY`) - so run them from inside such a session, or export that pair in a plain terminal first. A local-only Director stamps neither, and the commands say so. Local commands such as `setup status` and `actions` work anywhere. **Usage** ``` cc-devthrottle session list cc-devthrottle message send "message" cc-devthrottle session workers cc-devthrottle schedule list cc-devthrottle setup status ``` Sixteen command groups plus two top-level commands, each with its own `--help`: - `session` - the sessions themselves: `list`, `whoami`, `rename`, `prompt`, `interrupt`, `raise`, `workers`, `report`, `hold`, `compact`, `compact-continue`, `buffer`, `role`, `done`, `stop`, `spawn`. - `message` - send a message to another session, or ask and wait for its answer (see [fleet messaging](https://devthrottle.com/docs/gateway/fleet-messaging)). - `mission` - the unit of work sessions attach to: `create`, `list`, `rename`, `complete`, `remove`, `reopen`, `attach`, `detach`. - `director` - list every Director this account is running, with the id to pass to `session spawn --director`. - `machine` - the computers you can reach: `list`, `apps`, `files`, `launch`, and asking for a Director restart - `restart-capability` (whether that machine can complete one; changes nothing), `restart-request` (ask, with a reason the owner accepts once) and `restart-request-status` (see [machines](https://devthrottle.com/docs/gateway/machines)). - `repo` - list the fleet's repositories with their state and worktree summary. - `worktree` - list the fleet's worktrees, their sizes, and which session is in each. - `workflow` - read and author fleet workflows: `list`, `show`, `instructions`, `versions`, `pull`, `push`, `publish`, `materialize`, `runs`, `run`, `enable`, `disable`, `clone`, `delete`. - `skill` - the same shape for fleet skills: `list`, `get`, `show`, `versions`, `pull`, `push`, `publish`, `clone`, `enable`, `disable`, `delete`. - `schedule` - `list`, `get`, `create`, `run`, `enable`, `disable`, `delete`, plus `runs` and `endpoint` (see [scheduled runs](https://devthrottle.com/docs/gateway/cron)). - `browser` - DevThrottle's drivable browser profiles, signed in once by hand and then driven by an agent: `list`, `create`, `signin`, `start`, `stop`, `attach`, `rename`, `remove`. Machine-local. - `diag` - `network` (per connected device: direct or relayed, latency, UDP and NAT) and `results` (recent speed tests submitted from the app or the Cockpit); see [network](https://devthrottle.com/docs/gateway/network). - `autostart` - `on`, `off`, `status` for starting the Gateway at login. - `email` - `owner` sends one email to the account owner, and there is no way to address anyone else. - `settings` - read and write Director settings: `show`, `get`, `set`, `list`, `path`. - `setup` - `status`, `install`, `update`, `repair`, `doctor`. - `selftest` - run the fleet-messaging self-test against the local Director. - `actions` - list the agent-discoverable actions. Two of the session commands are how a session asks for help when nobody is watching it. `session raise` puts a session's hand up to whichever session is driving it - a worker to its manager, say - with a line saying what it is blocked on; the hand comes down when that session's turn ends, or on `--clear`. `session workers` is the other end of the same channel: it lists the sessions you are driving and which of them have their hand up. They exist because a supervised session is quiet toward you by design, and it still needs somewhere to put a question it cannot answer itself. `session report` is the last step of delegated work: when a session's turn ends, it tells the session that owns it what it did, in its own words. Two commands end a session. `session done` is the polite one: it flags a session for deletion and its Director removes it once it is no longer working (`--undo` takes the flag back off). `session stop` ends it now - it stops the agent process on the machine that owns the session and removes the session - and it requires `--reason`, which is recorded with the stop. Neither touches files: uncommitted changes in the session's worktree are left as they were. `workflow` and `skill` are the command-line windows onto two Gateway-held libraries, and each has its own page: [workflows](https://devthrottle.com/docs/gateway/workflows) for how a whole job is run and who staffs it, [skills](https://devthrottle.com/docs/gateway/skills) for the individual capabilities an agent picks up in the middle of one. Both follow the same rule - `push` uploads a private draft that no agent sees, and `publish` is what makes it live fleet-wide. ## Email: cc-gmail and cc-outlook Read, search, send, and manage email from the command line - one tool per provider, with matching command styles. Both authenticate once (`auth`) and then work non-interactively, which is what makes them usable by agents. **Usage** ``` cc-gmail list cc-gmail search "from:someone@example.com" cc-gmail send --to someone@example.com --subject "Hi" --body "..." cc-outlook list cc-outlook reply --body "..." --send ``` - Shared commands: `auth`, `list`, `read`, `send`, `draft`, `reply`, `search`, `delete`, `archive`, `move`, `recipients`, `profile`. - `reply` saves a draft unless you pass `--send`; `--all` replies to everyone, and `--html` marks the body as HTML on both `send` and `reply`. - cc-gmail adds `drafts`, `count`, `untrash`, `archive-before`, labels (`labels`, `label-stats`, `label-create`), and a mailbox `stats` dashboard; searches use Gmail query syntax. - cc-outlook adds `forward`, `flag`, `categorize`, `unarchive`, `attachments`, `download-attachment`, and `folders`/`create-folder`; auth is Device Code Flow. - Both go beyond the inbox: `calendar` on each, and `contacts` on cc-gmail. - Both take `--account` to pick between signed-in accounts, and `accounts` to manage them. ## cc-image Image toolkit: AI description and text extraction plus local resize and format conversion. By default the AI commands run through the [DevThrottle API](https://devthrottle.com/docs/api/overview) with your `dt_` key (`--engine` picks another engine); the local commands need no key at all. **Usage** ``` cc-image describe photo.png cc-image ocr scan.png cc-image resize big.png -o small.png --width 800 cc-image convert image.png -o image.webp ``` - `describe` / `ocr` - AI analysis and text extraction, single image or whole folders (batch cataloging to JSON/CSV with resume). The default engine requires `DEVTHROTTLE_API_KEY`. - `resize` / `convert` / `info` - local, keyless image operations. - Images are downscaled before AI analysis, so bulk runs stay cheap. ## cc-vault A personal knowledge vault - contacts, tasks, goals, ideas, health notes, posts, and documents - with semantic search and ask-a-question retrieval over everything in it. Your vault's data is stored on this machine. Search and ask both use an outside model service, in different ways: `search` sends only your query, to turn it into a search vector, and then searches the stored vectors on this machine; `ask` also sends the vault content it retrieved, so the service can write the answer. Building those stored vectors in the first place - adding or re-indexing documents - sends the text being indexed to the same service. All of it needs a key you supply and pay for, set as `OPENAI_API_KEY`. `cc-vault config show` prints whether it is set, and without it those two commands stop rather than quietly returning something weaker. **Usage** ``` cc-vault init cc-vault search "kickoff meeting notes" --hybrid cc-vault ask "what did we decide about pricing?" cc-vault tasks add "Follow up with the pilot customer" cc-vault backup ``` - Entities: `contacts`, `tasks`, `goals`, `ideas`, `docs`, `health`, `posts` - each its own group of commands such as `add`, `list`, `show` and `update` (`health` only reads: `list` and `insights`). - Organising them: `lists` and `tags` for contacts, `library` and `catalog` for documents, `graph` for statistics and traversal. - Retrieval: `search` (semantic, with `--hybrid` to add keyword matching and `--type` to narrow it) and `ask` (question answering over the vault). - Connecting things: `link`, `unlink`, `links`, and `context`, which returns an entity together with everything linked to it - the shape an agent wants. - Care and feeding: `stats`, `config show`, `backup`, `restore`, and `repair-vectors` to rebuild the search index from the stored text. ## cc-secrets Lets a session use a password without the model ever seeing it. You add an entry by hand from your own terminal - never through a session - and a session asks the tool to run a command with the password supplied, or to fill a login form in a browser profile the Director owns. The tool hands back only the result, and every use goes in an audit log. It protects against accidental exposure - transcripts, logs, output, screenshots - not against a hostile program running as the same user. The full guide, including where the store lives and the limits, is [cc-secrets](https://devthrottle.com/docs/cli/secrets). **Usage** ``` cc-secrets add devlinux cc-secrets list cc-secrets run devlinux -- sudo -S apt-get update cc-secrets login github-work --browser center-consulting cc-secrets log ``` - Owner commands, run from your own PowerShell or cmd window and refused inside a session: `add`, `remove`, `list --all`. - Session commands: `list`, `run` (the password on standard input, in an environment variable, or through an askpass helper), and `login` (a Director-owned browser profile, on an allowed address only). - Anyone: `log` and `version`. - The store works on Windows and Linux. On macOS the store is not supported yet, so no entry can be added or used there. > **Note:** Only tools that actually ship in the installer are documented here, on purpose - this page never lists a command your machine might not have. How the toolbox is managed and tested lives in the [overview](https://devthrottle.com/docs/cli/overview) and the Director's Tools tab, in Settings. --- # cc-secrets: passwords a session uses but never sees > Store a password once, by hand, and let a session run a command or fill a login form with it - without the model ever seeing it. Adding entries, allowed addresses, run, login, the audit log, where the store lives, and the limits. Part of the DevThrottle documentation, section "CLI". Canonical HTML version: https://devthrottle.com/docs/cli/secrets Last updated: 2026-09-16 Sessions keep needing passwords: a website login for a browser check, the `sudo` password on a Linux server, an account the agent has to work in. Typed into the session, a password lands in the transcript. Written into a file in the repository, it gets committed. `cc-secrets` is the third way: you store the password once, by hand, on the machine that needs it, and a session asks the tool to *do the thing* that needs the password - run a command, or fill a login form. The tool acts with the password and hands back only the result. There is no command that prints a password. An agent can see which entries exist, their user names and the sites they are for, and it can use them. It cannot read them out. > **Note:** What it protects against, in the tool's own words: accidental exposure - in transcripts, logs, command output and screenshots - not a hostile program running as the same user. The [limits](https://devthrottle.com/docs/cli/secrets#limits) at the end of this page are part of the design, not small print. ## How it works - **You add entries** from your own terminal: `add` and `remove`. Each entry is a name, a user name, the password, the site addresses it may be typed into, a note, which uses it allows, and whether sessions may use it at all. - **A session uses them**: `list` shows the entries it may use, `run` runs a command with the password supplied, and `login` fills and submits a login form in a browser profile the Director owns. - **Every use is written down**: `log` shows who used which entry, for what, and what happened - never the password. Each machine has its own store, one per operating-system user. Nothing is synced and nothing is kept on the Gateway, so add an entry on every machine whose sessions need it. ## Adding an entry Only you add entries, and never through a session. `add` refuses to run inside a DevThrottle session, because a password must never be entered through one. Open an ordinary PowerShell or Command Prompt window and run: **PowerShell or cmd** ``` cc-secrets add devlinux ``` It asks for the user name, the allowed site addresses (blank for none), a note, and whether sessions on this machine may use the entry (the answer defaults to no). Then it asks for the password twice, with the typing hidden. The password is never taken as a command-line argument, where it would land in your shell history and the process list. You can also pipe the password in, for example from your password manager's own command. With nothing to prompt, the other fields must then be given as options: **Piping the password in** ``` | cc-secrets add github-work --username alice --domains https://github.com --agents ``` Git Bash and other mintty windows cannot hide what you type, so `cc-secrets` will not read a typed password there. Use PowerShell or cmd, or pipe the password in as above - piping works from Git Bash. - `--username` - the user name that goes with the password. - `--domains` - comma-separated site addresses `login` may fill (see [allowed addresses](https://devthrottle.com/docs/cli/secrets#addresses)). - `--notes` - a note for yourself. Sessions see it in `list`, so keep it free of anything private. - `--agents` / `--no-agents` - whether sessions on this machine may use the entry. - `--uses` - comma-separated `login`, `run`; both by default. - `--replace` - replace an existing entry of the same name without asking. An entry name is lowercase letters, digits, dots, dashes and underscores, starts with a letter or digit, and is at most 64 characters. A password must be at least four characters. A password that is part of the text `cc-secrets` shows in its place (`[REDACTED]`) is refused, because it could never be hidden. ### Removing and reviewing entries **PowerShell or cmd** ``` cc-secrets remove devlinux cc-secrets list --all ``` `remove` asks for confirmation unless you pass `--yes`. `list --all` shows every entry, including the ones sessions may not use, with an Agents column. Both are owner commands and are refused inside a session. ## Allowed addresses An allowed address is a whole site origin - scheme, host and port - and `login` compares all three exactly: - `example.com` with no scheme means `https://example.com` on port 443, and nothing else. `http://example.com` and `https://example.com:8443` are different sites. - `https://*.example.com` allows every subdomain of `example.com` on the same scheme and port, but not `example.com` itself. A wildcard as broad as `*.com` is refused. - A local address works when you give it in full, for example `http://127.0.0.1:8080`. - A path is dropped, and an address with a user name in it is refused. An entry with no allowed addresses can still be used with `run`, but `login` refuses it: there is no page it may be typed into. ## Agents on or off, and uses Two settings on each entry decide what a session may do with it. **Agents** (`--agents` or `--no-agents`) applies to every session on the machine. An entry with agents off does not appear in a session's `list` at all, and using it gets the same answer as a name that does not exist, so a refusal does not reveal which entries you hold back. **Uses** limits an entry to `login`, to `run`, or allows both. To change either, add the entry again with `--replace`. ## What a session can do **Inside a session** ``` cc-secrets list cc-secrets run devlinux -- sudo -S apt-get update cc-secrets login github-work --browser center-consulting cc-secrets log ``` - `list` - the entries sessions may use: name, user name, allowed addresses, uses and your note. Never a password. `--json` for a script. - `run` - run a command with the password supplied, and get back its exit code and output with the password removed. - `login` - fill and submit the login form on the open tab of the entry's site, in a browser profile the Director owns. - `log` - read the audit log. - `version` - print the tool's version. ### run Put the command after `--`. The program must be on the PATH or given as a full path. `--via` chooses how the command receives the password: - `stdin` (the default) - the password and a newline are written to the command's standard input, which is what `sudo -S` reads. - `env` - the password is placed in one environment variable, named by `--env-name` (`CC_SECRET` by default), in the environment of the command it launches. Programs that command starts inherit it in the usual way. - `askpass` - `SUDO_ASKPASS`, `SSH_ASKPASS` and `GIT_ASKPASS` point at a small helper that fetches the password from a one-time listener on this machine, guarded by a random token and answering at most three requests. The command is stopped after `--timeout` seconds (600 by default). Its output is captured in full and cleaned before anything is shown - it is not streamed, because a password split across two chunks of output would slip past a clean-up of each chunk on its own. The password is removed as typed and in the encoded forms output tends to carry it in: escaped for JSON, HTML or Python, percent-encoded, base64 (including of `username:password`, as in a Basic authorization header), hexadecimal, and as bytes in any text encoding. If output still cannot be shown safely it is withheld whole. `run` exits with the command's own exit code; `--json`returns the exit code, whether it timed out, and both output streams. ### login `login` types into a browser profile the Director owns - the profiles `cc-devthrottle browser list` shows - and nothing else: it cannot be pointed at a port or address a session started for itself. It therefore only works inside a DevThrottle session. It uses the first open tab in that profile whose address the entry allows - not necessarily the tab in front - so keep one such tab open. Before calling it, start the profile with `cc-devthrottle browser start ` and open the site's login page in it. `--browser` takes the profile's id or name; `--timeout` is how long to wait for the login to finish (30 seconds by default). The password goes from the tool straight to the page and never passes through the agent. Before anything is typed, three things are checked against the entry's allowed addresses: 1. the tab's address, read from the browser itself, where a page script cannot alter it; 2. where the form will send what is typed into it; 3. how the form will send it - only POST. A GET form would put the password in the page address and the browser history. From just before the password is typed until the tab has been cleaned, every request the tab makes is paused and judged. The password may travel only in a POST to an allowed address; a request that would carry it anywhere else, or in any request's address, is stopped before it leaves the browser and the login is refused. A redirect is judged again at each hop. That rule is what holds even when the page changes its own form: a page submit handler that switches the form to another address or method is also caught by a listener that cancels the submission, but a handler can stop that listener from running, and a change to another address the entry allows still goes through. Whatever the outcome, once a password has been typed the tab is made safe and that is confirmed, not assumed: every password field is emptied, the tab's back and forward history is reset, and the tab is read back to check. If that cannot be confirmed the tab is closed, and if it cannot be closed either, the login fails with a message telling you to close it. The answer is one of four outcomes: - `logged in` - the form was submitted and went away. - `refused` - a check failed, for example the tab is on an address the entry does not allow (then nothing was typed), or the page tried to send the password somewhere it may not go (then that request was blocked; an earlier POST to an allowed address may already have been sent). - `failed` - no login form, the site rejected the credentials, the site did not answer, or the profile could not be reached. - `verification` - the site asked for a two-step code or a captcha. Finish the login by hand in that browser profile. ### Exit codes - `0` - done. - `1` - failed, including a `login` that stopped at a verification step. For `run`, the command's own non-zero exit code is passed through instead. - `2` - refused: an owner command inside a session, an entry that is not available for that use, or a `login` check that did not pass. ## The audit log **Anywhere** ``` cc-secrets log cc-secrets log -n 200 --json ``` Every use writes one line: the time, the entry, the session that asked (empty outside a session), the machine, the command, the outcome (`ok`, `refused` or `failed`) and a detail such as the exit code. Adding and removing entries is recorded too. A line that would contain the password is refused before it reaches the disk. `log` shows the most recent 50 lines unless you pass `--count` (`-n`). ## Where the store lives - **Windows**: `%LOCALAPPDATA%\cc-director\secrets\secrets.json` - **Linux**: `~/.cc-director/secrets/secrets.json` - **macOS**: the store is not supported yet. On a Mac, `cc-secrets` refuses to create, read or write the store, so no entry can be added or used: a file's access control list there can let another account read it even when its permissions look private, and `cc-secrets` does not check those lists yet. The audit log (`secrets-audit.log`) and the tool's own diagnostic log (the `logs` folder) sit beside the store. The store is a plain JSON file, protected by file permissions, not encrypted. On Windows the folder's access list grants your user alone and inherits nothing from its parent folder; on Linux the folder is `0700` and the store file `0600`. When a command reads or saves the store, the folder is checked (once per command) and so is the store file. Loosened permissions on a folder `cc-secrets` created itself are tightened; an existing folder it did not create that is not already private is refused, never changed; and if anything is still open to someone else the command refuses to go on. Reading the audit log does not repeat that check. The store file is replaced in one step through a temporary file that is private from the moment it exists. ## Limits These are the limits the code states and the owner accepted. Read them before you store anything that matters. - **A program running as you can read the store.** An administrator can read any file on the machine, and any process running as your user - a session's own shell included - can open `secrets.json`. The rule that the model never sees a password is kept by the tool never printing one, not by the file being unreadable to the user the agent runs as. - **The clean-up catches accidents, not intent.** A command that deliberately transforms the password - reverses it, hashes it, splits it across lines - produces output with no recognisable form of it. What limits that is the entry's uses setting and the agents switch; what records it is the audit log. - **The page receives the password.** JavaScript already running in the login page gets it, because the site needs it. A listener attached to the page before `login` was called can copy it, and a page can transform it before sending, so it no longer looks like the password. - **The request guard sees one tab.** It covers the requests of the login tab's own frames. A service worker, a cross-origin frame running in another process, a WebSocket message and other tabs are outside it. A header a page script sets is judged as the browser reports it, and the browser reports a value holding a character outside plain ASCII with characters missing, so a page script that puts a non-ASCII password, as it is, into a header of a request to another site is not caught. - **The guard lasts only while the tool is connected.** If `cc-secrets` is stopped or crashes while a request is paused, the browser sends that request on without a judgement. The accidental case this leaves open needs a site that answers the login with a redirect to another address at the same moment the tool stops. - **Not handled**: login forms inside cross-origin frames, two-step codes and captchas (reported as `verification` for you to finish by hand), and a hostile program running as your user that takes over the browser profile's debug port. - **One machine at a time.** There is no sync between machines, and the agents switch applies to every session on the machine rather than to a named session or mission. > **Warning:** `cc-secrets` keeps a password out of the transcript, the logs and the output. It is not a vault against software you do not trust on your own account. Do not store a password there that a program running as you must never be able to read. The other shipped tools are in the [tool reference](https://devthrottle.com/docs/cli/reference); browser profiles are managed with the `cc-devthrottle browser` commands listed there. --- # Supported coding agents > The eight agents with built-in drivers - Claude Code, Pi, Codex, Gemini, OpenCode, Cursor, Grok, GitHub Copilot - what each one launches with, and the custom type that runs any CLI. Part of the DevThrottle documentation, section "Coding agents". Canonical HTML version: https://devthrottle.com/docs/agents/supported Last updated: 2026-09-06 DevThrottle is vendor-neutral: it runs the coding agents you already use, side by side in one place, each in its own session on its own repository. You keep your own subscriptions and keys - running an agent through DevThrottle costs nothing. ## First-class agents Eight agents have a built-in driver. There is no waiting list and no gate: you install the agent's own command-line tool yourself, DevThrottle detects it, it appears as a row under **Settings -> Agents**, and from there it is one of the options in the New Session window. An agent whose tool is not installed on this machine simply is not in the list - that is true of every one of them, Claude Code included. - Claude Code - Pi - Codex - Gemini - OpenCode - Cursor - Grok - GitHub Copilot Those are the names as they appear on the screen, in the order the list is built in. You can have more than one row of the same type - two Claude Code entries with different settings, say - and you choose the order they appear in. ## What each one launches with This is the real difference between them. A fleet that stops to ask permission on every tool call does not run, so a freshly detected agent is set up to work without stopping for approval wherever its command line offers a way to say so. Six of the eight do. Two do not, because their tool has no such option to give: Pi's approval flag only trusts files inside the project, and OpenCode keeps permissions in its own configuration file rather than on the command line. | Agent | Recommended setting | What it adds to the command | | --- | --- | --- | | **Claude Code** | Automatic | `--permission-mode auto` | | **Pi** | Standard only | nothing - Pi has no full-permission option | | **Codex** | Full access | `--dangerously-bypass-approvals-and-sandbox` | | **Gemini** | Automatic (yolo) | `--yolo` | | **OpenCode** | Standard only | nothing - OpenCode keeps permissions in its config file | | **Cursor** | Automatic (yolo) | `--force` | | **Grok** | Automatic (approve all) | `--always-approve` | | **GitHub Copilot** | Automatic (yolo) | `--allow-all` | **Standard** - the agent's plain command line, asking you for permission as it normally would - is selectable for every one of the eight, so nothing here is forced on you. Claude Code also offers **Skip permissions** (`--dangerously-skip-permissions`) as its own named choice; it is deliberately not the recommended one. Every flag above was read from the installed tool's own help output. > **Tip:** You change any of this per agent row in [Settings -> Agents](https://devthrottle.com/docs/director/agents), where the editor shows the command that entry will launch with as you edit it. ## Any other CLI: the custom agent The ninth type is called **Custom**, and it is the escape hatch: point DevThrottle at any command-line program and it runs as a session like the rest - terminal in the Director, cards, history. If a coding CLI exists, it can sit in the Director today, even before it gets a first-class driver. What a custom session does not get is worth knowing before you pick it. These are not weaker versions of the features - they never run at all: - **No Director-assigned session id.** The Director cannot name the session before it starts. - **No resume.** There is no reopening a custom session where it left off. - **No Studio mode**, the card view built on the agent's structured output. - **No turn detection, no wingman briefing, no transcript link.** There is no output pattern to read, so the session never announces that it needs you and never links to a conversation. Nothing breaks and nothing errors - the terminal, the repository, and the history are all there. The parts that read what the agent is saying are the parts that stay quiet. > **Tip:** Choosing an agent to start with? The [coding agents directory](https://devthrottle.com/coding-agents) compares the field, the [comparison matrix](https://devthrottle.com/coding-agents/matrix) puts them side by side, and the [Terminal-Bench scoreboard](https://devthrottle.com/scoreboard) shows how they score on real command-line work. All three are kept from research checked against each agent's own sources, with the date each entry was last verified. ## What "supported" means here A first-class driver knows the agent's install, launch, and interaction quirks, so the session's [state](https://devthrottle.com/docs/director/sessions) - Working, Needs you, Ready, Background, Snoozed, Exited, Crashed - is read from what that agent actually does. Every screen you can watch a session on shows the same word for it. A custom session gets the states its terminal can prove and none of the ones that need the agent to be understood. > **Note:** DevThrottle does not modify the agents. Each one runs as it does in your own terminal, with the Director watching from outside, and your existing agent configuration keeps working. The command line is not always character for character the one you would type: the recommended setting above adds its permission option, and Claude Code and Pi launches carry a session id so the Director can find that conversation again. --- # Glossary > DevThrottle terms in one place - the apps including the phone and AgentEyes, the Director, missions, Supervisor and Parent, account and money, voice, and automation - each defined in a sentence and linked to the page that goes deeper. Part of the DevThrottle documentation, section "Reference". Canonical HTML version: https://devthrottle.com/docs/reference/glossary Last updated: 2026-09-06 DevThrottle's terms, in one place, each with the meaning we use everywhere else in these docs and in the product. Each links to the page that goes deeper. ## The apps - **Director** - the desktop app, for Windows and for Mac (Apple Silicon, workstation only, with the Gateway hosted elsewhere): every agent session as a card in one place. [The Director](https://devthrottle.com/docs/director/overview). - **Gateway** - the always-on service that keeps agents reachable, serves the Cockpit and the phone, and runs schedules. It is also where your session state and conversations are stored, which is what the Director, the Cockpit and the phone all render; you either use the hosted one or run your own. [What the Gateway does](https://devthrottle.com/docs/gateway/overview). - **Cockpit** - the same sessions in a browser, served by your Gateway. [The Cockpit](https://devthrottle.com/docs/cockpit/overview). - **The phone app** - the same fleet on your phone: you add it to your home screen and it shows which sessions need you, so you can answer by voice or thumb. It is a view - putting it away never stops an agent. [DevThrottle on mobile](https://devthrottle.com/docs/mobile/overview). - **Launcher** - the tray app that keeps the pieces started. - **AgentEyes** - a separate screen and audio recorder for Windows that turns a recording into a transcript and a shareable write-up. Its own download, signed in with your DevThrottle account. [AgentEyes](https://devthrottle.com/docs/agent-eyes/overview). ## In the Director - **Agent** - the coding agent tool itself: Claude Code, Codex, Gemini, Grok. It is what you run; a session is one running instance of it. [Supported agents](https://devthrottle.com/docs/agents/supported). - **Session** - one coding agent running in one directory; one card in the Director. [Session cards and states](https://devthrottle.com/docs/director/sessions). - **Needs you** - the state where a session stopped and asked a question; the Director counts these so nothing waits silently. - **Snooze** - quiet a session so it stops asking for attention until a time you choose. Ask for it while the session is still working and it takes effect the moment the work stops. - **Queue** - where prompts you have written wait. The queue holds them: you can reorder, edit or remove them, and nothing goes to the agent until you send it. [Starting and steering agents](https://devthrottle.com/docs/director/steering). - **Agent driver** - the per-agent adapter (Claude Code, Codex, ...) that knows how to launch and read that agent; the custom driver runs any CLI. [Supported agents](https://devthrottle.com/docs/agents/supported). ## Working together - **Mission** - an undertaking: why you are doing something, who is working on it together, and the tasks it breaks into. Sessions attach to a mission, and that attachment is what makes them sessions of that mission - the mission IS the one idea for why they work together, so there is no second word for the set. [Session roles and missions](https://devthrottle.com/docs/director/roles). - **Task** - one piece of a mission, handed to one worker. A mission has several. - **Workflow** - a reusable, versioned way of working that a mission can follow, such as one session working alone, or one doing the work and a second reviewing it. The *how*, where a mission is the *what*. - **Run** - one execution of a workflow, carrying what that workflow promised and the evidence for each promise. - **Role** - what a session is for within its mission: **Standalone** works alone and faces you, **Architect** settles the design, **Manager** drives the work and supervises, **Worker** builds. Most are worked out for you. [Session roles and missions](https://devthrottle.com/docs/director/roles). - **Supervisor** - the session a working session answers to. It is a live relationship: while it holds, the supervised session's red is its Supervisor's business rather than yours, and the Supervisor is what the roles and colours are computed from. [Session roles and missions](https://devthrottle.com/docs/director/roles). - **Parent** - the session that started another one. A historical fact, recorded only when an agent session made the call, and deliberately not the same thing as the Supervisor: a session can have a Parent and no Supervisor. [Session roles and missions](https://devthrottle.com/docs/director/roles). ## Account and money - **Free** - the plan every account starts on: the Director on every machine you own, signed in to your account, with no Cockpit, no phone app and no AI. [Pricing](https://devthrottle.com/pricing). - **Remote** - the plan that adds the gateway we run, the Cockpit in any browser and the phone app, without the AI. [Billing](https://devthrottle.com/docs/account/billing). - **Pro** - Remote plus the AI: dictation, spoken replies, the wingman and the Mentor. [Billing](https://devthrottle.com/docs/account/billing). - **Money-back guarantee** - a full refund of your first payment if you ask within 30 days, once per person. There is no trial. [Terms](https://devthrottle.com/terms). - **Credits** - the prepaid balance for direct catalog-model calls on the [DevThrottle API](https://devthrottle.com/docs/api/overview). You want them when you are building something yourself: point any OpenAI-compatible script or tool at DevThrottle with one `dt_` key and it can call any of [the models your key supports](https://devthrottle.com/docs/api/models), instead of holding a separate account and key for each one. A nightly summary job, a bot, a batch pipeline - each direct model call draws on your credits, and nothing can spend past what you loaded. Running your agents in the app needs no credits; dictation, spoken replies, and the wingman are included in Pro, key or no key. [Billing](https://devthrottle.com/docs/account/billing). - **API key (dt_)** - a key you create for your own tools to call the [DevThrottle API](https://devthrottle.com/docs/api/overview). - **Device key** - the per-device credential a paired phone or machine holds; revocable per device. [Devices](https://devthrottle.com/docs/account/devices). - **Activation** - the browser approval step that registers a new device to your account. [Pairing your phone](https://devthrottle.com/docs/mobile/pairing). ## Voice - **Custom dictionary** - your words, taught once, applied to the dictation and voice-note transcripts DevThrottle makes for you, on every device. A direct [API](https://devthrottle.com/docs/api/transcription) call to the transcription endpoint does not go through it. [Voice](https://devthrottle.com/docs/voice/overview). - **Hosted transcription** - the speech-to-text behind dictation, run by DevThrottle and included in Pro. [Voice](https://devthrottle.com/docs/voice/overview). ## Automation - **Cron / schedules** - unattended agent runs on a timer. [Scheduled runs](https://devthrottle.com/docs/gateway/cron). - **Control API** - driving the fleet from code: the Gateway is the programmatic surface, called by `cc-devthrottle` with the session's own key. There is no local REST API on the Director. [Control API](https://devthrottle.com/docs/gateway/control-api). --- # Troubleshooting > The problems people actually hit - SmartScreen, agent CLI not found, phone reachability, an empty chat screen, voice that went quiet, API calls returning 402 - each with its fix and what the product is already telling you. Part of the DevThrottle documentation, section "Reference". Canonical HTML version: https://devthrottle.com/docs/reference/troubleshooting Last updated: 2026-09-06 The problems people actually hit, with the fix for each. If yours is not here, the [issue tracker](https://github.com/thefrederiksen/devthrottle/issues) is read daily. ## Install and first run - **The download stops just short of finishing and never completes.** Your browser is holding the file, not losing it. What it is weighing is the publisher, not the file: DevThrottle is signed by a young identity that has not yet shipped enough copies for the browser to know it, and that reputation is built by volume over time. Click the download icon near the top right of your browser - it will be showing a small warning badge. The short panel that opens says the installer is not commonly downloaded, but there is *no* Keep button in it: click **Downloads** at the top of that panel to open your full downloads list. There the file offers **Keep** and **Delete** as plain buttons - click **Keep**, and since the file has already downloaded in full it finishes at once. The publisher shown is Center Consulting Inc. On a machine managed by an employer, policy can remove the Keep option altogether - there is no way round that from our side, so ask whoever manages the machine. - **Windows SmartScreen shows a prompt on the installer.** Same cause as above, and nothing is misconfigured: the installer is code-signed, and SmartScreen is weighing how well it knows the publisher rather than how new the file is. Check the publisher on the prompt reads Center Consulting Inc., then **More info** - **Run anyway**. It clears as the identity builds volume, so it is not a wait you can shorten from your side. A hard block (no run option) is not expected - report it. - **An agent will not start: command not found.** The first-run wizard offers to install Claude Code for you; for other agents, install the agent's CLI yourself, confirm it runs in a plain terminal, then start the session again. ## The Director and sessions - **A session shows Working but nothing is happening.** Open the card - the terminal is always the ground truth. If the agent is genuinely stuck, [Interrupt](https://devthrottle.com/docs/director/steering) it and re-prompt; status detection is tuned per agent but the terminal never lies. - **Agents died when the machine rebooted.** Sessions run on the machine; a reboot ends them. What you get back is the Director, the history, and [recovery behavior](https://devthrottle.com/docs/gateway/lifecycle) - re-start the sessions from their cards. ## Phone and Cockpit - **The phone cannot reach the Gateway.** Reachability is the usual cause: the phone must be able to reach the Gateway machine (same Wi-Fi, or your VPN / overlay network from outside). Confirm the Cockpit opens from a browser on the same network first, then re-try the phone. See [pairing](https://devthrottle.com/docs/mobile/pairing). - **A device was revoked by mistake.** Revocation is not reversible in place - re-approve the device through the normal activation flow and it returns as a fresh row in [Devices](https://devthrottle.com/docs/account/devices). ## Voice - **Dictation gets technical words wrong.** That is what the [custom dictionary](https://devthrottle.com/docs/voice/overview) is for - add the term once and every device picks it up. - **Voice stopped working.** Read the session first - it says why. The badge on the session is decided for you and each one means something different: - **Nothing to read aloud** - the session is waiting on a prompt or a menu, not a text answer, so there is nothing to narrate. Not a fault. - **Voice service down** - the far end is not responding. It retries by itself; there is nothing for you to press. - **Voice needs credit**, **Monthly limit reached**, **Finish setup** - about your account or this machine, and each carries the button that fixes it. - **Voice did not arrive**, followed by how long it waited - after three minutes with no audio the session stops promising and says so. The Gateway keeps trying; read the turn instead. - **Update DevThrottle** - that session's computer is on a version that cannot send its conversation. See below. - **Voice is silent and the session shows no reason at all.** Check your subscription state on your [account dashboard](https://devthrottle.com/docs/account/overview) and the Director's status rail for connection health. - **Your own API calls return 402.** The refusal carries a code, and the code says which of several things happened - so read it before topping anything up. `insufficient_credits` means the prepaid balance for direct catalog-model calls is empty. `monthly_limit_reached` means you hit your own **Monthly spending limit**, which is a switch you set on the billing page and raise there - your credits are untouched. A call to your hosted Gateway can also answer `hosted_subscription_required`, which means the account has no live plan or trial; that response carries the address to act on. Dictation, spoken replies and the wingman are unaffected by all three - they are included in Pro and never draw on credits. [API errors](https://devthrottle.com/docs/api/errors). ## Chat and the conversation - **The chat screen is empty.** It tells you which of several reasons it is, and they are not the same news: this session is not known here (the id may be wrong, or it belongs to another account); this agent keeps no readable conversation, so nothing will ever appear and that is not a fault; that computer has not checked in recently; that computer cannot send it; nothing has been sent yet, which clears itself within a minute; or the session is here and has simply not spoken yet. Read the sentence on the screen - it is the answer, not a placeholder. - **"This session's computer is running an older DevThrottle that does not send conversations."** This is the one most people meet right now. Sending conversations arrived in v2.0.5, and it has to be installed on the machine the session runs on - not on the machine you are reading from. Update DevThrottle there and the chat fills in on its next check-in. The same fact appears on the voice screen as **Update DevThrottle**. - **A Pi session is showing an earlier session's conversation.** Fixed in v2.0.6 - but a Pi session that was already open when the update installed keeps the old behaviour for the rest of its life. Close that session and open a new one. [Changelog](https://devthrottle.com/docs/reference/changelog). > **Tip:** The Director's status rail (bottom of the sidebar) is the first diagnostic: it shows the Gateway connection - the same chip tells you whether you are signed in - the bundled tools, and auto-update, all at a glance. > **Note:** When you report an issue, say which agent CLI, what the status rail showed, and what the terminal showed - those three answer most tickets in one round trip. --- # Run DevThrottle on a Mac unattended > macOS cannot launch a new graphical app while the screen is locked. The never-lock setup for an unattended Mac - and its security tradeoffs, stated plainly. Part of the DevThrottle documentation, section "Reference". Canonical HTML version: https://devthrottle.com/docs/reference/mac-unattended Last updated: 2026-07-11 A Mac mini makes a great always-on machine for running coding agents - but macOS ships tuned for a person sitting in front of it, not for a machine nobody touches for weeks. This page is the checklist that turns a Mac into an unattended agent machine: what to change, the exact commands, and the tradeoffs stated plainly. (The Mac runs agents as a workstation; the machine that hosts the [Gateway](https://devthrottle.com/docs/gateway/overview) runs elsewhere - a Windows machine you host, or hosted for you.) > **Note:** **The one rule that matters:** never let the screen lock. Turn the display off instead. Everything else on this page is detail. ## Why the screen lock is the enemy macOS cannot launch a new graphical application while the screen is locked. When the lock engages, the login window takes ownership of the displays. Your session keeps running - applications that are already open keep working, and background processes are unaffected - but any **new** graphical launch cannot bind display resources at startup and fails. The Director is a graphical application, so on a locked Mac nothing can start a new Director - not a scheduled run, not a remote request, not a restart after an update or crash - until a human unlocks the screen. This is architectural, not a bug, and there is no setting, entitlement, or launchd trick that gets around it. We proved it on our own hardware (a Director launched into a locked session dies instantly with a render-timer error, even from a launch agent placed directly in the graphical user domain), and it matches what Apple's own engineers say on the developer forums: there is no mechanism for launching an application behind the lock screen. Windows is genuinely different by design - locking a Windows machine just switches which desktop is visible, while the session and its windows stay fully active underneath, so new applications launch fine on a locked Windows PC. That difference is one more reason the always-on [gateway machine](https://devthrottle.com/docs/gateway/overview) is not a Mac. The industry already solved this for Macs. Every commercial Mac build farm - GitHub's hosted macOS runners, Cirrus Labs images, Buildkite's Amazon EC2 Mac guide, GitLab's MacStadium images - ships the identical configuration: automatic login, screen lock disabled, screen saver disabled, system sleep disabled, FileVault off. The display may sleep; the session never locks. That is exactly the configuration below. ## The security tradeoff, stated plainly > **Warning:** After this setup, the machine logs itself in at boot, never locks, and its disk is not encrypted. **Anyone with physical access owns the machine and everything on it.** This is the right trade for a Mac in a locked home or office that only you can touch. It is the wrong trade for a laptop, a shared space, or anywhere the hardware could walk away. Compensating controls that still work: keep the machine reachable only over a private network or VPN (see [answering agents remotely](https://devthrottle.com/docs/cockpit/remote) for the reachability picture), keep Screen Sharing and Remote Login password-protected, and remember that Find My can remotely lock a stolen machine after the fact. ## The checklist Everything scriptable is collected in [scripts/mac-unattended-setup.sh](https://github.com/thefrederiksen/devthrottle/blob/main/scripts/mac-unattended-setup.sh) in the open source repository - it shows the current value of every setting and asks before each change. The same steps, in order, for doing it by hand: ### 1. Turn FileVault off Automatic login does not exist while FileVault is on: the encrypted disk needs a typed password before macOS can even start. Decryption runs in the background; the machine stays usable. **Terminal** ``` sudo fdesetup disable ``` *System Settings path:* Privacy & Security > FileVault. *Tradeoff:* the disk is readable if the hardware is stolen. If that risk is unacceptable, keep FileVault on and accept that every reboot needs a person (for a planned reboot, `sudo fdesetup authrestart` skips the unlock screen exactly once - it does not help with power failures). ### 2. Enable automatic login Every restart - planned, power failure, or crash - lands on the logged-in desktop where the Director can start. **Terminal** ``` sudo sysadminctl -autologin set -userName -password - ``` *System Settings path:* Users & Groups > Automatically log in as. *Tradeoff:* the account password is stored obfuscated (not encrypted) in `/etc/kcpassword`. ### 3. Set "require password after sleep or screen saver" to Never This is the setting that actually prevents locking. With it off, the display turning off no longer locks the session, and new graphical launches keep working around the clock. **Terminal** ``` sysadminctl -screenLock off -password - ``` *System Settings path:* Lock Screen > "Require password after screen saver begins or display is turned off" > Never. *Gotcha:* if the control is grayed out, open the iPhone Mirroring app and set it to "Ask every time" first - a known macOS quirk. *Note:* the old `defaults write com.apple.screensaver askForPassword 0` trick stopped working around macOS 13 - `sysadminctl` is the supported command, and it requires the account password by design. ### 4. Disable the screen saver **Terminal** ``` defaults -currentHost write com.apple.screensaver idleTime -int 0 sudo defaults write /Library/Preferences/com.apple.screensaver loginWindowIdleTime -int 0 ``` *System Settings path:* Lock Screen > "Start Screen Saver when inactive" > Never. ### 5. Power settings: never sleep the machine, let the display sleep **Terminal** ``` sudo pmset -a sleep 0 # the machine never sleeps sudo pmset -a disksleep 0 # disks never spin down sudo pmset -a displaysleep 10 # the display MAY turn off - harmless once the lock is off sudo pmset -a womp 1 # wake on network access sudo pmset -a autorestart 1 # start up again after a power failure ``` *System Settings path:* Energy. *Gotcha:* some Apple Silicon minis honor "start up after power failure" inconsistently after a hard power cut. Test yours (pull the plug); if it fails, a smart plug that cycles power is the community workaround. ### 6. Software updates: security automatic, reboots manual Keep the invisible security pieces automatic, but stop macOS from installing full operating-system updates on its own - those reboot the machine and kill every running session. **Terminal** ``` sudo defaults write /Library/Preferences/com.apple.SoftwareUpdate AutomaticCheckEnabled -bool true sudo defaults write /Library/Preferences/com.apple.SoftwareUpdate AutomaticDownload -bool true sudo defaults write /Library/Preferences/com.apple.SoftwareUpdate CriticalUpdateInstall -bool true sudo defaults write /Library/Preferences/com.apple.SoftwareUpdate ConfigDataInstall -bool true sudo defaults write /Library/Preferences/com.apple.SoftwareUpdate AutomaticallyInstallMacOSUpdates -bool false ``` Then install operating-system updates yourself, on your schedule: `sudo softwareupdate -ia` during a maintenance window. *Tradeoff:* you own the patch schedule now - put a recurring reminder somewhere. ### 7. Quiet-machine settings **Terminal** ``` defaults write com.apple.CrashReporter DialogType none # no crash dialogs (crashes still logged) defaults write NSGlobalDomain NSAppSleepDisabled -bool YES # no App Nap throttling of background apps sudo defaults write /Library/Preferences/com.apple.TimeMachine DoNotOfferNewDisksForBackup -bool true ``` ### 8. Enable Remote Login for recovery When the graphical session is unreachable, `ssh` over your private network is how you fix the machine without walking to it. Screen Sharing is the second door - keep both. **Terminal** ``` sudo systemsetup -setremotelogin on ``` ### 9. Privacy permissions: the one-time clicks The high-value privacy permissions live in a database protected by System Integrity Protection. **No script, no command line, no setting can grant them** on a normal machine - only a human clicking in System Settings (or mobile device management on a supervised fleet). The good news: a grant is inherited by every process the granted application launches, so granting the Director covers all the agent processes it spawns. Grant once, done forever - with one caveat: the grant is tied to the application's code signature, so it sticks for the installed app, but a rebuilt ad-hoc-signed development build counts as a new application. | Permission | Grant it to | Needed for | | --- | --- | --- | | Full Disk Access | The Director (and your terminal, if you launch agents from one) | Agents reading anywhere on disk without per-folder prompts | | Screen Recording | The Director | The screenshot features | | Automation | Approve prompts as they appear | Controlling other applications | *System Settings path:* Privacy & Security > (each category) > add the app with the + button. ### What you do NOT need to change - **Gatekeeper** - locally built binaries never get the quarantine flag, so Gatekeeper never prompts for them. Leave Gatekeeper on; do not use `spctl --global-disable`. - **The application firewall** - if it is off, there are no "accept incoming connections?" prompts. If you turn it on, know that ad-hoc-signed binaries get a fresh signature every rebuild, so each rebuild re-prompts; the fix is signing local builds with a stable self-signed certificate, or scripting `socketfilterfw --add --unblockapp` into the build. - **Notifications** - banners never block a background process; they only matter to a person looking at the screen. ## Verify the setup 1. Restart the Mac. It must land on the desktop with nobody touching it. 2. Turn the display off (`pmset displaysleepnow`), wait a minute, then start a new agent session on this machine remotely. It must launch cleanly. 3. Pull the power cord for ten seconds. The Mac should boot itself back to the desktop. 4. From another machine: `ssh` works and Screen Sharing connects. ## How the rest of the community handles this You are not alone in this configuration - it is what everyone running unattended Macs converges on: - **Mac build farms** (GitHub's hosted macOS runners, Cirrus Labs images, GitLab's MacStadium images, Buildkite's Amazon EC2 Mac guide) all ship automatic login with the lock, screen saver, and sleep disabled. Their provisioning scripts run the same commands listed above. - **The OpenClaw community** - thousands of people hosting the open-source agent on dedicated Mac minis - independently arrived at the identical recipe: automatic login, sleep off, lock and screen saver set to Never, "start up after power failure" on, and the FileVault tradeoff documented just as bluntly as here. Their guides add one more trick for Macs with no monitor: an HDMI dummy plug, because macOS graphical rendering and screen capture misbehave with no display attached at all. If your Mac mini has no monitor, buy the dummy plug. Browsers deserve a special note, because agents drive them constantly: - **Headless browsers are immune.** Headless Chromium (Playwright, Puppeteer) never talks to the display, so it launches and runs fine regardless of lock state or missing monitors. - **Headed browsers degrade rather than crash.** A visible browser window on a locked or backgrounded Mac gets its rendering and timers throttled - automation pauses and resumes on unlock. Browser-automation people work around it with launch flags (`--disable-background-timer-throttling --disable-renderer-backgrounding`), but on a never-locked machine the problem does not arise. - **Attaching to an already-running browser keeps working while locked**, because the remote-debugging protocol is a plain network interface and its screenshots come from the browser's own compositor, not the physical screen. This matches the general rule: existing graphical processes survive a lock; only new display-bound launches fail. - There is **no virtual-display server for macOS** the way Linux has one for X11 - a dummy plug or virtual-display utility is the closest substitute, and neither bypasses the lock screen. > **Tip:** Running the Mac headless (no monitor)? Get an HDMI dummy plug. It is the cheapest fix for every rendering and screenshot oddity a monitor-less Mac produces. ## Where to go next - [What the Gateway does](https://devthrottle.com/docs/gateway/overview) - why the always-on hub runs, and how a Mac fits in as a workstation. - [Scheduled runs (cron)](https://devthrottle.com/docs/gateway/cron) - unattended agent runs on a schedule. - [Answering agents remotely](https://devthrottle.com/docs/cockpit/remote) - reaching the Director from another machine. --- # What DevThrottle reports home > What leaves the machine you work on: the usage-telemetry program is gone, and since v2.0.5 your Director pushes each session conversation to your Gateway, which keeps it for 90 days. Hosted and self-hosted, and the one switch on your account. Part of the DevThrottle documentation, section "Reference". Canonical HTML version: https://devthrottle.com/docs/reference/telemetry Last updated: 2026-09-06 This page answers one question: what leaves the machine you work on, where it goes, and how long it is kept. It is a map, not a guarantee - and it changed in a way worth reading if you knew the old answer. ## There is no usage-telemetry program any more DevThrottle used to count feature use on your machines and send anonymous events home. That was removed from the product in July 2026, and nothing replaced it. There is no consent screen at the Gateway's first launch, there is no **Usage Telemetry** page in the Cockpit, and nothing on your machine queues events to send. A machine that still carries the leftovers has them removed the next time the Director or the Gateway starts: the retired settings, the queued event files, the consent cache, and the old raw transcription log. They are deleted where they sit - not read first, and not sent anywhere. ## What your Director sends to your Gateway This is the part that matters now. Your agents run on your machines, and your Director reports to your Gateway as they work: - **Session state and activity** - a session started, needs you, finished, was snoozed. - **The conversation itself.** Since v2.0.5 your Director pushes each finished turn up to your Gateway, and the Gateway keeps it. That is how Chat, the transcript view and the wingman can show you a session from your phone or a browser without your machine being asked to re-read anything. A pushed turn is the message as it was written: who spoke, the message text, the agent's thinking, the tool calls with their input, and the tool results. When an agent reads or writes a file, what it read or wrote is inside those tool parts. Each batch is also labelled with the transcript it came from, which for Claude Code is that file's path on your disk. Your Gateway keeps a session's conversation for **90 days** and then sweeps it, whole sessions at a time. > **Note:** If you read an earlier version of this page, it said DevThrottle never sends your prompts or your agent conversations. That sentence was written about the telemetry program, and it is not true of the conversation push described above. This page states the current answer. ## Who your Gateway is You choose this once, in the first-run wizard, and the product states it plainly on the card you pick: *Your agents run on your machines. Fleet metadata and conversation history are stored on the hosted gateway so remote history and supervision work.* - **Hosted** - the Gateway is ours, so everything above is stored by DevThrottle, in your account's own partition, on the published retention windows. - **Self-hosted** - the Gateway is a machine you own, so the same data lands on your own hardware and the retention window is yours to set. [What the Gateway does](https://devthrottle.com/docs/gateway/overview). ## Signing in is always recorded When you sign in - in a browser, or in the browser page the Director opens to sign you in - the website records the sign-in against your account, with where it came from: `web` from a browser, `app` from the Director handoff. That is the whole record. There is no switch for it: it is how accounts work, and it is what tells us how many people use DevThrottle. ## The one switch: Product usage data Your account has a single control, **Product usage data**, on the console's [Settings](https://devthrottle.com/docs/account/settings) page. It is on by default and you can turn it off at any time. Today it **records your preference and gates nothing**: the usage-telemetry program it was built for was removed in July 2026, and nothing collects on the strength of this flag. The sign-in record above is not covered by it, and neither is the conversation history your Director sends to your Gateway. The control is kept because the consent it expresses is real - if collection returns, this is what it will answer to. It is the only one. The Cockpit's fleet-wide telemetry switch went with the rest of the program described at the top of this page, so if something points you at a second switch on your Gateway, it is out of date. ## What is written on your machine - **Terminal screen recordings** - off by default. When you turn them on, frames are appended to a file in the Director's local application data folder on that machine, and removing the session removes them. - **Your working files** - agents run on your machines and edit the repositories you point them at, in place. > **Note:** This page is about DevThrottle. Your coding agents and any hosted AI you use have their own flows - an agent sends code to its AI service to do its job, dictation uploads audio to be transcribed, and spoken replies send the reply text to be read aloud. Those are covered where those features are documented, for example [voice](https://devthrottle.com/docs/voice/overview). The complete data map - every class of content, where it is stored, how long it is kept - is the [Privacy Policy](https://devthrottle.com/privacy). --- # Changelog > Recent DevThrottle releases with highlights - v1.0.0 onward - with the GitHub releases feed as the authoritative, always-current record. Part of the DevThrottle documentation, section "Reference". Canonical HTML version: https://devthrottle.com/docs/reference/changelog Last updated: 2026-10-13 DevThrottle ships continuously. The authoritative, always-current changelog is the [GitHub releases feed](https://github.com/thefrederiksen/devthrottle/releases), where every version lists its merged changes. Highlights of the recent line: ## v2.19.0 - October 13, 2026 Desktop dictation now works on a Linux Director, every schedule can be paused in one tap and the whole scheduler can be paused and resumed exactly as it was, every scheduled run says how it went, and a machine holding several Claude accounts can be switched to a spare when one runs out, as an opt-in setting. - **Desktop dictation on Linux.** The Dictate dialog in a Director on Linux now records from your microphone and transcribes exactly as it does on Windows. It records through PipeWire when that is installed, where you can pick any input, and otherwise through ALSA's default input. A machine with neither is told which package to install. On a Mac the dialog says dictation is not available there yet. - **Pause everything.** The Schedule page and the Factories screen in the Cockpit have one switch that stops every schedule from starting, and a banner shows while it is on, so a paused fleet never looks like a broken one. Resuming changes no schedule: each is exactly as active or as paused as it was. Pausing stops new runs from starting; it does not stop a session that is already running, and no missed run is recorded for a time that passed while everything was paused. - **Pause one schedule where you read it.** Each schedule on a factory's Seats tab has a Pause or Resume button beside it, and the schedule editor has an Active or Paused control, so editing a paused schedule never resumes it by accident. The state is called Paused everywhere, in place of Disabled. - **Every scheduled run says how it went.** A scheduled session ends by calling `cc-devthrottle run result ok` or `cc-devthrottle run result problem ""`, and a run whose session ended without saying is recorded as "did not report". `cc-devthrottle run problems` lists the open problems, and `cc-devthrottle run resolve` clears one with a reason that is kept. - **License switching, off by default.** A machine that holds more than one Claude account can now be moved to a spare when the active one runs out. With `licenseSwitching.enabled` set to true in a Director's config.json, that Director reports each account's 5-hour and weekly use, the Gateway checks once a minute and sends a switch when one is due, and the new Licenses page in the Cockpit shows the accounts, each machine's active account, the switch log and a Switch now button. The setting is off unless you turn it on, and with it off the Licenses page has nothing to show. - **Claude account usage and sign-ins from the command line.** `cc-devthrottle license usage` prints each held account's 5-hour and weekly use and when each resets. `cc-devthrottle license sign-in` adds a spare account by signing it in through one of the Director's browser profiles, and `cc-devthrottle license renew` signs in again every account whose sign-in ends within five days. - **Also in this release.** A session with a voice clip ready is no longer marked "retrying" on the phone. Before, a failed read after the clip was made could take the play button off the row and drop the session out of the voice queue. Factories, where the factory area is turned on: every seat on the Seats tab says whether it closes itself, from how its recent scheduled runs ended, and a factory with a seat that does not is flagged on the list, its card and its page. A factory's page lists its open problems, each with Handle the issue, which opens a talk with the factory's boss, and Resolve, which asks for a one-line reason. The Seats tab is grouped by shift, and the Schedule page shows each schedule's shift and warns when a run is due close to the end of one. The Factory Manager, where the factory area is turned on: one standing session can be set over all of an account's factories with `cc-devthrottle factory manager set`, and the Factories screen shows it on a card with a talk button. A problem in a factory that has no boss goes to the Factory Manager. The factory email, off by default: the Gateway can send a report at 08:00 and checks at 16:00 and midnight about your factories' scheduled runs, and keeps each one as it was sent. Turn it on with `cc-devthrottle factory email on`; `cc-devthrottle factory email list` and `show` read the kept ones, and a factory's page lists the emails that covered it. `cc-devthrottle license refresh` renews a spare account's key when it has under an hour left. The Accounts dialog is gone from the Director's Developer menu. `cc-devthrottle license` holds and switches accounts now. The old accounts file is left where it is and is no longer read. The release process: the test run before a release is much shorter, the largest suite going from about two hours to about nine minutes, and a test that depends on the machine it runs on - a sleep, the real clock, a real process - is refused before it can decide a release. The scheduler pause, the run results, the Licenses page and the once-a-minute license check, the factory email, the factory page's open problems, the Factory Manager, the shifts, the seat markers and the voice clip fix are in the hosted Gateway. The download carries desktop dictation on Linux, the Director's license reporting and switching, the `cc-devthrottle run`, `cc-devthrottle license`, `cc-devthrottle factory email` and `cc-devthrottle factory manager` commands, and the removal of the Accounts dialog. ## v2.16.0 - October 5, 2026 When you correct the Fleet Manager, the correction is kept as a lesson on the Gateway, and every Fleet Manager after it is given that lesson. - **Fleet Manager lessons.** A correction you gave the Fleet Manager used to live only in that one conversation, so it was lost at the next restart, move or compaction. Now it is kept as a lesson, in your words and with the date, and stored on the Gateway rather than on one machine. Every confirmed lesson is given to the Fleet Manager when it starts, when it is restarted or moved, when you mark a session as the Fleet Manager by hand, and after a compaction on the agents that have a session-start hook. - **Two ways to keep a lesson.** On the Cockpit's Fleet Manager page, press "That was a mistake", type the correction and press Keep: it is stored at once, confirmed, and the running Fleet Manager is told at its next free moment. The Fleet Manager can also keep one itself with `cc-devthrottle fleet lesson ""`; a lesson kept that way waits for you to confirm it with one press before it is given to a later Fleet Manager. - **Lessons and preferences on one list.** The Cockpit's Fleet Manager page shows your lessons first, then your standing preferences, each with the date and who kept it, and for a lesson whether it is confirmed. You can confirm a lesson, and edit or remove a lesson or a preference, there. An account holds at most 20 confirmed lessons of at most 500 characters each; nothing is ever shortened or pushed out. - **Also in this release.** `cc-devthrottle fleet preferences --kind lesson` lists the lessons, and `cc-devthrottle fleet digest` prints them first, before the sessions. After a compaction the lessons are put back by the session-start hook, on the agents that have one; on the other agents the Fleet Manager reads them again with `fleet digest`, and the Fleet Manager's agent setting says which agents are which. When a Director reconnects to the Gateway, it now sends its sessions' keys before it lists its sessions, which closes the moment in which another machine could claim a session started while the connection was down. If a key cannot be read or is refused, the session is still listed and that moment stays open until the key reaches the Gateway. The lessons, the Cockpit page and the Fleet Manager's new instructions are in the hosted Gateway. The download carries the `cc-devthrottle fleet lesson` command and the Director change that puts lessons back after a compaction. ## v2.15.0 - October 5, 2026 You can let two of your sessions talk to each other, and a session that needs to talk to another one can ask you. - **Message links.** A session can normally message only the session that started it and the sessions it started. You can now let any two of your sessions talk: once, once with a reply, or as much as they need. Set it up from a session's menu in the Cockpit ("Let this session talk to..."), or with `cc-devthrottle message link add`. You never approve the messages themselves; the two sessions decide what to send. A link for as much as they need ends when either session ends or when you remove it. - **A session can ask you for a link.** When a message is refused, the session is told how to ask: `cc-devthrottle message request "why it needs to talk"`. You see a card at the top of the Sessions screen in the Cockpit with who is asking, whom it wants to talk to and its reason, and you answer with One message, One message and a reply, As much as they need, or No. The session hears your answer in its inbox. A session may have at most three requests waiting, and after a No it may not ask for the same thing again for an hour. - **Also in this release.** `cc-devthrottle message link list` and `message link remove` show and end the links you have set up. A Fleet Manager session that you have given the right to manage links can list and answer requests with `cc-devthrottle message link requests` and `message link answer`. The links, the requests and the Cockpit screens are in the hosted Gateway and are already live there. The download carries the `cc-devthrottle message` commands that sessions use to ask, and that you can use from the command line. ## v2.14.0 - October 4, 2026 The Director asks the Gateway for far less while it sits idle, and links in the terminal are drawn where they are and open exactly what is written. - **The session list is read at most once every 30 seconds.** Before, the full rescan every five minutes asked the Gateway for the whole list once per repository, so a machine with 75 repositories made 75 downloads of about 68 KB each time - about 80 MB an hour from one machine doing nothing. - **Skills, workflows and injected text are downloaded only when they have changed.** The Director still checks once a minute, but the Gateway now answers "not changed" with no body when the Director already holds the current copy. The first check after the Director starts is always a full download. - **Links in the terminal are exact.** A link on the second or later row of a wrapped line is underlined and clickable on the row it is on, not on the row above. An address is no longer cut short at a bracket or an apostrophe, and a piece of a path is no longer linked as a drive letter. Rows are joined into one line only where the text really wrapped. - **The terminal honours the links a program marks itself.** When a program such as Codex sends a link with its own address, the terminal uses that address exactly instead of guessing it from the text. When a link's text is not its address, hovering shows the full address and it is the first line of the click menu. - **Also in this release.** A file an agent names before writing it becomes a link once it exists: a path found missing is checked again after two seconds, the next time the terminal redraws. More kinds of path are recognised as links: home-folder paths, network paths, bare file names in the repository, and file positions written as `:line 12` or `(42,7)`. The chat view shows a link as it was written. A failed read of the skill list no longer removes every installed skill. The AI summaries on the Cockpit History page are removed; the page keeps its record of which session came from which. Narration clips are read from disk when played, and a clip at least 14 days old whose session is gone is removed. ## v2.7.0 - September 18, 2026 Several sessions can now work on one repository at the same time, each in its own ready-made copy, and a copy is only cleared for reuse once its work has provably landed on the remote. - **Pooled worktrees: a ready-made copy per session, cleared only when the work has landed.** DevThrottle keeps a small pool of copies of a repository. A session takes a free one, works in it, and gives it back when it closes; a returned copy is reset and handed to the next session, so the build output in it stays warm. A copy is reset only when its work is proven to have landed: the copy is the one it claims to be, nothing is uncommitted or untracked, nothing of its own is sitting in a stash, and every commit in it is either on the freshly fetched default branch or is the same change as something that is. When git cannot prove it - a squash, a rebase, a merge git cannot compare - GitHub or Azure DevOps is asked whether a pull request carrying exactly those commits was merged into the default branch. A host can only turn "held" into "free", never the reverse. Anything unproven leaves the copy *held*: nothing in it is reset or deleted, and the reason is printed. Turn it on for a repository with `cc-devthrottle worktree pool on --repo `. It is off by default, there is no machine-wide switch, and the default pool is four copies. The tool is `cc-worktrees` and it ships in the toolbelt on Windows, macOS and Linux. Tested end to end on Windows. One thing to know before turning it on: a `git gc` holds every copy in that repository's pool, including free ones, because it rewrites the record the proof depends on; `cc-worktrees release --confirm-abandon` gives them back, one at a time. - **The Wingman tab: one screen to read a stop and answer it.** The Now view says which session it is on the first line of every state, has one place to type with one sending button per state, and no longer carries Stop, Interrupt, Compact and Clear context directly under where you click answers. "Stopped at" is the real stopping time, taken from the Director's own record rather than a join key - which is why three sessions on two machines used to claim the same minute. A finished session has somewhere to type, a snoozed one says when it comes back and offers to wake it, the pill wears the session's own colour, and an answer that cannot be taken back says so and asks once. - **Room for the report.** The left rail and the queue dock collapse, both remembered per browser, and collapsing never hides the attention badge. A report has its own address at `/report/{id}` with nothing beside it, so a printed link opens the report rather than the Reports tab of a session the reader does not have. Export HTML saves exactly the bytes the Gateway serves for the version on screen. - **Voice: whose session it is, and the clip belongs to the turn on screen.** A session held by another session says so and offers nothing, and the banner claims only what the product does - the sessions you own. A narration that failed can be asked for again, while automatic paths still never re-attempt one. The rule that drops an old clip now fires on a state check rather than a sampled edge, so a quick turn can no longer slip past it and leave the phone playing the previous turn as though it were this one. A failed switch or generate stays on screen until it is retried instead of being wiped by the next poll. ## v2.6.0 - September 18, 2026 One session now runs your fleet for you, and messages between sessions stop interrupting the work. - **The Fleet Manager: one session you talk to that runs the rest.** You tell it what you want. It starts the sessions that do the work, gives each one your words, watches them without you, and comes back with only three kinds of news: something is ready, something was found, or something needs your decision. It never does the work itself, so it is always free to talk. It replaces the Assistant on the Cockpit, on the phone and in Settings, it is pinned first in your session list with the sessions it started collected under it, and its news is held by the Gateway so a restart or a move to another machine loses none of it. - **A message is a record, not an interruption.** `cc-devthrottle message send` places the message in the other session's inbox and answers`queued`; the session reads it with `cc-devthrottle message inbox`. A session may message only the session that started it and the sessions it started. When a session has finished its turn and its composer is genuinely empty, the Director rings one fixed doorbell line - and if anything you typed is sitting there, even three spaces, it waits for the next opportunity. A doorbell never ends a snooze you armed. - **Passwords your sessions use but never see.** cc-secrets ships in the toolbelt on Windows, macOS and Linux. You add a secret by hand on each machine and a session can then use it without the secret ever reaching the model. Adding, editing, removing and importing are for you only and are refused inside a session. - **Linux: an app menu entry, and updates that work.** Installing on Linux adds DevThrottle to the app menu with its icon, the command-line install finishes cleanly instead of failing at the last step, and a Linux Director now checks for updates, downloads its own build and can install it. Before this the check reported "up to date" every time. ## v2.5.0 - September 17, 2026 Your sessions can now use a password without the model ever seeing it, and a Linux machine installs, appears in the app menu, and updates itself like the other platforms. - **cc-secrets: passwords your sessions use but never see.** cc-secrets is a new tool in the shipped toolbelt. You add a secret by hand on each machine, and a session can then use it without the secret ever reaching the model. `cc-secrets run` starts a command with the secret supplied on its input, in an environment variable, or to a password prompt, and removes every recognisable form of the secret from what comes back. `cc-secrets login` fills a login form in a browser profile the Director owns, after checking the page is on the site the secret belongs to. `cc-secrets import` moves a whole credentials file into the store, one entry per line, without printing any value, and `run --with` hands several entries to one command at once, such as a service key and the secret that goes with it. Values that are not secret, such as a host or an email address, can be stored as settings beside the secrets (`add --setting`, `import --settings`); `cc-secrets get` prints a setting, and a secret is never printed. `cc-secrets edit`changes an entry's user name, allowed site addresses, uses or agent access without re-entering its secret. Adding, editing, removing and importing are for you only and are refused inside a session. The store is one file per user per machine, readable by that user alone; every use checks this, and on macOS it also checks access control lists and refuses drives that ignore file ownership. Every use is written to an audit log, which never contains the secret. It runs on Windows, macOS and Linux. - **Linux: an app menu entry, and updates that work.** Installing on Linux now adds DevThrottle to the app menu, with its icon, so there is something to click. The command-line install finishes cleanly instead of failing at the last step, and uninstall removes the entry. A Linux Director now checks for updates, downloads its own build, and can install it. Before this release the check stopped before asking GitHub and reported "up to date" every time. - **Fleet messages are queued, not typed.** `cc-devthrottle message send` no longer types text into the other session's terminal. It places the message in that session's inbox and answers `queued`; the session reads it in full with the new `cc-devthrottle message inbox`, which marks it read. A session may message only the session that started it and the sessions it started, at most 6 messages an hour and 1 per recipient every 10 minutes. `cc-devthrottle message ask` has been removed. - **Also in this release.** The Cockpit has a Wingman tab on each session: every stop the Wingman judged, with the outcome, the colour it produced at the time, and why. The`cc-devthrottle` command line is easier for agents to use: lists show full identifiers, names and paths instead of cutting them short, filters work the same with`--json`, empty results say `count: 0`, running it with no arguments shows the live state, and a wrong flag fails with the valid choices listed. Dictation: the ready sound no longer ends up in the transcribed audio, the recorder keeps listening for a quarter of a second after you press Send or Pause so your last word is not cut off, and the time the microphone took to start is logged and shown. The stored raw transcript is the speech model's full output on every path, as the transcription rules require. The Fleet Map draws the same ownership tree as the Sessions list, across machines, so a session started from another machine shows under the session that owns it. The Fleet Map keeps a colour legend on screen, and hovering a session dot now gives the same words as its colour. The Missions board no longer says "needs you" under a session that does not need you. Voice narration is no longer silenced when a verdict check fails. The Wingman now judges sessions owned by a Fleet Manager session, so the Fleet Manager can act on its verdicts; those sessions are still never read aloud to you. On Windows, the Director prepares a spare Director slot in the background the first time it starts after updating. No reinstall is needed. ## v2.4.0 - September 16, 2026 The session list now tells you what every colour means, and the Wingman can tell a stop that needs you from one that is only reporting - as an opt-in setting, off by default. - **What do the colours mean?** The session list in the Cockpit and on the phone has a new link that opens a short legend: every colour a session can show, what the session is doing, and whether it is asking for you. The words come from the Gateway, next to the rules that decide the colours, so the legend and the dots always agree. If you ever see magenta, the legend says what that means too. - **The Wingman says whether a stop needs you (opt-in, off by default).** When a session stops, the Wingman can now read the screen and decide whether the stop needs you. With the account setting on: a stop that only reports finished work shows cyan, labelled Done or Report, and is not counted as needing you; a session that said it will carry on by itself shows purple, and turns red if it does not; while the Wingman is still reading a stop, the row is yellow; in the Cockpit a judged stop shows its options as buttons, with a This is wrong action for a verdict you disagree with; and a snooze that ends with nothing new comes back calm instead of red. Brand-new sessions stay green, labelled Ready, so a finished session never looks like a new one. - **The launcher updates itself on Mac and Linux.** Until now only Windows launchers updated themselves. From this release the launcher updates itself on every platform. - **Also in this release.** Voice mode names the right session when it speaks. When voice mode gives up on a spoken summary, the session no longer stays yellow: it asks for you instead. On Mac and Linux, `cc-devthrottle setup` looks for its commands in the right folder and downloads the setup tool built for that machine. The phone's Chat tab has its full screen back; answering a judged stop from its options is done from the Cockpit. A Director older than this release shows finished sessions in magenta until it updates. ## v2.3.0 - September 15, 2026 You can now see every machine you own in one place, see which ones are behind the newest release, and update them from the Cockpit without walking over to the machine. - **A Machines tab: every machine, its launcher and its Directors.** The Directors page used to list Directors and nothing else. A machine whose Director was closed but whose launcher was still running did not appear at all, and there was no single place that showed every machine, its launcher and the Directors on it together. The page now opens on a Machines tab: one row per machine, with its launcher and how recently it was heard from, and the Directors on that machine listed underneath. Each launcher is described in plain words - connected, offline, or too old to be sent commands - and the last two say what to do about it. The Directors tab is the list you had before, with one change: the version column now says whether each Director is current or behind, and sorting by version puts the ones that are behind at the top. - **The Gateway knows the newest release.** Every Director used to check for new releases on its own and keep the answer to itself, so the Cockpit could show a version number on every machine but could not say whether any of them was out of date. The Gateway now reads the newest release itself, about once an hour, and every version on the page is compared against it. If it cannot read the newest release, the page says so rather than calling everything current. - **Update now.** A machine whose Director is behind and has no sessions running now offers an Update now button, on the Machines tab and on that Director's own page. Pressing it installs the downloaded update straight away: the Director restarts into the new version, and if the new version does not start, the previous one is put back. If the machine has not downloaded the new build yet, it says so and installs nothing. It is the same update your launcher already performs by itself once a Director is empty - it simply no longer waits for the launcher's next check - and the rules are unchanged: an update is never installed while sessions are running. A busy machine says how many sessions are running and that it will update by itself once it is empty. Each Director's page also has a new Version and updates card: the version it runs, the newest release, whether a newer build is downloaded and waiting, what the launcher can do, and the result of the last update on that machine. - **Update now needs a launcher from this release.** A launcher updates itself, so machines pick this up on their own. Until one has, its machine says its launcher is older than remote updates and keeps updating the way it always has. - **Also in this release.** Restart and Start for a Director are now buttons on the Machines tab and the Director page. Restart only happens when the Director is empty - the launcher checks again at the moment it restarts, and refuses if it is not. ## v2.2.0 - September 15, 2026 The session list is now the shape of the work: sessions fold underneath the session that started them, on the Director, the Cockpit and your phone, by the same rules and in the same words. A session now wakes when its conversation actually moves, not whenever its screen redraws. - **Your sessions fold under the session that started them.** A flat list stops telling you anything the moment you run a real amount of work - one Architect with nine sessions under it took ten rows of a fourteen-row rail, and the four sessions you were actually looking for were off the bottom of the screen. Any session that started other sessions is now a parent, and the sessions it started sit underneath it, folded away by default. A session that started nothing is an ordinary row, exactly as before, which is most of them - so on a quiet day nothing looks different at all. The relationship is ownership, not grouping: it is the session a session answers to, the same fact the product already uses to decide whether something interrupts you. It goes as deep as it really goes, so an Architect's Manager's Workers are all there, each nested under the session that actually started it. - **A folded group hides nothing.** A folded parent carries one small square per session underneath it, at every level, in that session's own colour; the counts - working, stopped, and how many need you; and how long the oldest session in the group has been going, ticking as you watch it. A group that is hiding a session that needs you says so without being opened: the count is on the line, and that session keeps its own colour in the row of squares. Open it and its sessions appear underneath, indented behind a guide line, each with its own chevron if it started sessions of its own. Which groups you left open is remembered, per group, and survives a restart. - **One switch: your order, or what needs you most.** There are no tabs and there is no second list. *My order* is the one you made by dragging rows around, and it is unchanged. *Attention* puts the session that has been waiting for you longest at the top, then the rest that need you, then the ones still working, then the snoozed ones at the bottom. Nothing is hidden; the order simply changes. Sessions never re-sort underneath their parent, because a session with a live supervisor is not waiting on you in the first place. Dragging still works, and now understands ownership: a row moves among its own siblings and never across a parent boundary, so rearranging your list cannot tell you something untrue about who started what. - **The same answer on every screen.** The Cockpit, your phone and the Director now compute none of this for themselves. The tree, the counts, the age and the attention order are worked out once and read everywhere, and the two implementations - one for the browser, one for the desktop - are checked against a single shared file of worked examples that neither of them owns. Change one side alone and its own tests go red. That is deliberately harder than letting each screen do its own arithmetic, and it is the reason the same group of sessions cannot be described three different ways depending on where you are standing. - **A session wakes when its conversation moves, not when its screen redraws.** Until now a settled session went blue the moment any output arrived, so an agent redrawing its own screen could make a session look busy - and end a snooze - with nothing new in the conversation. A settled session now opens a turn only when the conversation gains a new row. It is on by default on every Director, with nothing to configure. It targets a measured problem: on one Director over one day, 107 wake-ups were a single burst of output with nothing behind it, 85 of them fell on an exact 30-minute cycle while the agent's footer drew "Checking for updates", and 81 snoozes ended on one of those repaints. Checked against 4,328 pinned screen pairs, the new rule kept 93.8 percent of short unexplained wakes red, while 229 of 231 longer ones still opened a turn. Its effect on live snoozes has not been measured yet. If it misbehaves on a machine, setting`CC_DIRECTOR_CONTENT_TURN_RULE=off` restores the old rule on that one Director. - **Also in this release.** A failed session-key registration now says why. A single invalid value used to produce an unexplained error and take every other session key registering at the same time down with it - on one machine, 2,310 identical errors in a row, none of which named what was actually wrong. Built-in skills now have one source rather than two copies that drifted apart, with a check that keeps them that way, and the skills the product ships no longer teach a way of starting a session that the product refuses. Groundwork for the Wingman judging every stop has landed, switched off: the two per-account switches that will let it change how a stop is shown are both off by default. ## v2.1.3 - September 14, 2026 A release about who a session answers to, and about being able to see the shape of the thing you are running. - **A session that starts a session has to say who owns the result.**Every session answers to something: either another session is holding it and gets told when its turn ends, or it is yours and it goes red and asks you. That rule shipped in v2.1.2, but nothing enforced it - the refusal lived only in the `cc-devthrottle` command line tool, a convention the tool chose to follow rather than something the product required, so anything that skipped the tool got an unowned session. Three things were wrong underneath, all the same shape: the spawn path trusted the request for facts the caller should not have been able to choose. The origin of a spawn - a person, an agent, or a schedule - was read out of the request itself, and only one of the two spawn routes checked it at all, and not the common one, so a caller could simply say it was a person. Nothing required an agent to say who would own what it started. And a caller that did declare an owner but got the identifier slightly wrong had that declaration silently discarded, producing exactly the unowned session it had been trying to avoid, with no error to say so. - **Who is asking now comes from the credential, not the request.** All three are closed, on both routes, in one shared place. A person - the desktop, the Cockpit, the phone - is recognised from their signed-in device and is never asked who owns anything: a session you open is yours. A session starting another session is recognised from its own key; it cannot claim to be a person, its parent is taken from the key rather than from what it says, and it must declare who will own the result or the spawn is refused with the options spelled out. A scheduled run declares nothing and is yours, exactly as before. A malformed owner is now refused, naming the value, instead of being dropped. One limit, stated rather than left to be found: the refusal applies where the caller can be identified. A spawn relayed between machines by a Director carries that Director's own credential and is trusted, because its request was written by a command line that had already been through the gate. A test says so, and it will be the first thing to change if that ever stops being true. - **Handing work to you now says why.** `--standalone` means the user owns the session: it goes red and asks you when it finishes, and the agent that started it hears nothing back. It exists for real cases - you asked for the session, or the work genuinely needs you - but it cost exactly as much to type as `--controlled-by self`, and agents were reaching for it. On a fleet of nineteen sessions, three of the thirteen that agents had started had chosen it, and two of those were sitting red waiting for attention that need never have been asked for. It now requires a reason. The choice is not forbidden; an agent that cannot say why the work is yours keeps it and collects it itself. - **The architecture documentation is five documents and has pictures.**The architecture tree had grown to 192 files across two directories, and most of it was leftover instructions rather than description: briefs addressed to sessions that finished months ago, phase plans, dated review rounds, handovers. Several still announced themselves as active work, and two were the same document in two formats that had drifted apart. It is now five documents - sessions, the fleet, the Director and Gateway, terminology, and an index - each owning its subject completely, with nothing stated twice. Every claim was re-checked against the code rather than carried across, which turned up three documents describing a product that no longer existed, including one instructing agents to connect to a network port removed months ago. The diagrams draw the outbound-only model - Directors dialling out, nothing reaching in, no ports on any machine, with the mechanisms that used to need a way in marked - and also what decides whether a session interrupts you, who gets told when a turn ends, and the shape of a mission. - **Also in this release.** The test suite now builds its own PostgreSQL rather than assuming one, and a missing database fails the run instead of quietly skipping the tests that need it. ## v2.1.2 - September 14, 2026 A release about sessions you are not watching: the ones nobody is holding, the ones that finish and never say so, and the one you are trying to stop. - **Stopping a session asks you once, and takes your word for it.** The Director and the Cockpit had turned a stop into an interrogation - four sentences explaining the audit trail, a box demanding a written reason, a Stop button that stayed switched off until you filled it in, and a panel afterwards reporting what had happened to a session you had just watched disappear. Both now ask one question with Cancel, Stop, and a note you may leave blank. If the stop works the window simply closes; only a failure says anything. The reason requirement stays where it belongs - on the REST interface, because one agent can stop another agent's session and the trail has to say why - and a stop you make yourself is recorded as coming from you. The phone was changed this way two days earlier, so all three screens now behave the same. - **A session stays quiet only while somebody is holding it.**Whether a session could go quiet used to be decided by what kind of session it was, fixed when it was born - so sessions were quietened for the category they belonged to rather than because anyone was there to catch them. On 13 September six sessions sat grey and labelled "Snoozed" with nothing snoozed, and five of the six had nobody who would ever come back for them. The question is now asked fresh every pass: is there a supervisor alive right now? If not, the session turns red and asks you. Alongside it, owning a session is something a session must now say out loud - a session that spawns another must declare who owns the result, where before it took ownership silently just because it could. - **A session tells its parent when the work comes back.** Going quiet is only safe if somebody is told when it is over, and until now nothing was: a session finished delegated work and simply stopped, so "quiet" could quietly mean "lost". A session that was given work now reports back in its own words, and that report interrupts its parent - the right cost, because a session that took ownership took on being interrupted when the work returns. - **A dictation to a session that has exited stops retrying forever.** It was refused and left unresolved, so the phone kept trying it every few seconds, paying for a full transcript each time and throwing it away, repainting a dead session orange on every lap. The only way to stop it was to delete the session. It now resolves the first time, tells you the session has gone, and keeps your audio. - **Also in this release.** The Gateway's own unit tests had grown past the time limit on the everyday test run, which meant they were being stopped before they finished and counted for nothing. They now run on the release check instead, where they count. ## v2.0.6 - September 3, 2026 A small release with one fix that matters if you run the Pi coding agent: a new Pi session no longer shows, or reads aloud, a conversation that belongs to an earlier session. - **A new Pi session showed the previous session's conversation.** Open a Pi session in a repository where you had used Pi before, and the chat screen filled with the conversation from that earlier session - a review from weeks ago, in one case - before you had typed a word. The spoken narration read that same old conversation out, and the turn counter on the session card counted the old session's turns as well. DevThrottle was finding a Pi session's transcript by taking the newest transcript file in the repository, and Pi only writes a session's file when the first message is sent - so at the moment a new session started, the newest file was always the previous session's, and that wrong answer was kept for the whole life of the session. - **Every Pi session now starts with its own session id**, and Pi names the transcript file after it, so DevThrottle knows which file belongs to which session from the moment it starts and never has to guess. Reopening a Pi session brings its conversation back, because the same id is what Pi uses to resume. Clearing a Pi session's context is followed correctly: Pi starts a fresh transcript when you clear, and DevThrottle now follows the new file rather than staying on the old one. The context gauge and the model shown for a Pi session come from that session's own file, not the newest file in the repository. - **A Pi session that was already open when you install keeps the old behaviour until you close it.** Sessions opened after the update behave as described above. - **Also in this release.** The `cc-devthrottle` command line tool gains `session raise` and `session workers`: a session that is being driven by another session can put its hand up when it is blocked, and the driving session can see who is blocked. *The two new commands need the hosted service update that follows this release.* They do not work until it is deployed. ## v2.0.5 - September 3, 2026 Install this release before the hosted service is updated. It teaches your computer to send its conversations up to DevThrottle instead of being asked for them every time, and the next update to the hosted service expects that. The order matters, and it is explained at the end of this entry. - **Your computer now sends each finished turn as it happens, and DevThrottle keeps it.** Until now, every time DevThrottle needed a conversation - to draw the chat screen, to read a turn aloud, to wait for a spoken answer - it sent a request down to your computer asking it to open the agent's transcript file and read it back. On the chat screen that happened every two and a half seconds. Chat, the transcript view and the spoken narration now all read from the copy that is already there, so the chat screen stops waiting on a round trip to your machine, and a conversation you have already had stays readable when your computer is briefly unreachable. To be exact, because this is easy to overstate: the session itself still needs your computer - that is where the agent runs. What changed is that reading what has already been said no longer waits on reaching it. - **The narration that went silent for hours is fixed.** A session could stop producing spoken narration and never recover, with nothing on screen saying why. Chat in the same session kept working, which made it look like the voice feature was broken. DevThrottle worked out where the agent's transcript lived by building a path from the session's folder; when an agent moved into a Git worktree the transcript moved with it, and every read from then on opened an empty spot, forever. The path is now resolved in one place, following the pointer the agent itself reports - and because conversations are sent up as they happen, nothing reads that file at all any more on the path that failed. - **Dictation stops changing words you never asked it to change.** The correction list is for words you have listed, and it had been guessing at words you had not: between 8 and 17 August the fuzzy matcher turned "sure" into "Soren" 261 times, "many" into "Banya" 138 times, and did the same to "code", "single" and "focus". Only words on your list are replaced now. That matching is off, and stays off. A model may check a candidate before an unlisted word is touched, but it can only choose between candidates - it never supplies text of its own. Dictation transcripts are kept for 90 days, matching session history, so you can go back and see what was actually said. - **Smaller things.** The session picker on the phone is searchable, so a long list is usable. An empty recording no longer retries forever, and a stuck dictation no longer holds its session locked. The Gateway starts listening before it opens its database, so a slow database no longer looks like a dead service during startup. And `cc-scrub`, a screenshot scrubber, removes private details from an image before you share it. *Install this before the hosted service is updated.* This release is safe to install right now, while the hosted service is still the current one: your computer checks whether the service is ready to receive conversations and simply does not send them if it is not, so nothing changes for you today. The hosted service will then be updated to read conversations from the copy your computer sends. A computer still on v2.0.4 or earlier cannot send them, and after that update its chat and voice screens will say so and ask you to update, rather than showing the conversation. That message is correct, and installing this release clears it - but you can avoid seeing it at all by updating now. ## v2.0.4 - August 16, 2026 A small release with two fixes, both named in the v2.0.3 notes as things that were still wrong: a session waiting for voice now has a clock and can admit defeat, and the Gateway waits longer for its database before the platform gives up on it. - **The wait is now on the screen.** A session waiting for voice says how long it has been waiting, in whole minutes, timed from the moment the wait began rather than from the last time anything happened. A row reading "Preparing voice" used to read exactly the same at two seconds and at forty-eight minutes. - **After three minutes the product stops promising.** The row turns red and says the voice did not arrive, with the elapsed time, instead of another calm "on its way". Three minutes is the standard the product already held itself to and had written down; it is now shown rather than merely intended. The Gateway keeps trying in the background - what ends is the promise, not the effort. And the reason you can act on still wins: if the speech service is down, or the account is out of credit, or setup is unfinished, the row says that, and none of those sentences is replaced by the give-up message. A session that has audio, has an attempt in flight, or has nothing to read aloud is unaffected. - **The Gateway waits longer for its database.** A deploy on 12 August took the hosted service off the air for 46.7 seconds: the container gave up on its database after ninety seconds and exited, and stopping a failed container during startup also takes down the healthy one serving traffic next to it - while the same database opened cleanly minutes later. The Gateway now waits inside the startup budget it actually has, with room left to finish starting up. This is a mitigation, not a cure: it widens the window in which a slow database can recover, and the real fix - a Gateway that starts answering before it touches the database at all - is not built yet. It has one deliberate cost: a Gateway that cannot reach its database at all now takes about eighty seconds longer to report the error. - **Known and not fixed here.** Five faults are known, filed, and deliberately left for the next release: every new account gets a 14-day Pro trial, but the trial is invisible in the app, so no screen says a trial is running or how many days are left; a snooze does not survive the agent's own update check, so a snooze on an idle session can die within about half an hour; a Gateway serving an evicted Director shows an empty fleet as though it were a fact while the sessions are running normally; spawning a session with a prompt can lose the prompt and tell the caller nothing went wrong; and the hosted morning report can say no sessions ran on days when they did. *Both fixes live on the Gateway side.* If you use the hosted service they are already running, and updating the app is all you need. If you run your own Gateway, update it too. There is no migration and no new setting. ## v2.0.3 - August 12, 2026 Sessions no longer go quiet without saying why, you can sign out of the mobile app, and two accounts can share one browser. - **Sessions no longer go quiet without saying why.** A session in voice mode could stop speaking and never start again. Its row sat on "Preparing voice" indefinitely, no narration was produced, and nothing anywhere reported a fault - one session was found sitting like that for forty-eight minutes. Reading a session's conversation could fail and be reported as a success with nothing in it, so narration concluded there was nothing to say and never tried again. A failed read is now treated as a failure: the narration is attempted again on its own, and the row says voice is on its way instead of claiming it is being prepared when nothing is happening. - **The row tells you the real reason.** Where it used to say "Preparing voice" for every possible cause, it now says "Nothing to read aloud" when the session is waiting on a question rather than a written answer, "Voice service down" when the speech service cannot be reached, and "Voice needs credit" when that is what is wrong. An agent that keeps no conversation at all is said so once, rather than promising a narration that could never arrive. And asking for a narration by hand no longer reports a failed read as a session that has not produced anything to summarize yet. - **You can sign out, and keep two accounts.** The mobile app previously had no way to sign out at all. You can now sign out, and you can keep two accounts and switch between them on both the phone and the desktop Cockpit, without a password and without a connection. Signing out always asks first, and the confirmation says which of the two outcomes will happen, because signing out of one account and signing out of all of them are different things. - **Also in this release.** An administrator can extend a member's Pro trial, so a promise made to somebody about their trial can be honoured; this is an administrator action on the hosted service, not something a member does. The project now carries a contributing guide and a security policy, so anyone reporting a vulnerability has a stated route. And repairs to the build and the test suites. - **Known and not fixed here.** There is still no clock on a session waiting for voice, so no screen can tell you how long it has been without narration; and there is still no point at which a session whose narration keeps failing admits defeat rather than saying voice is on its way. Both are stated in the release note. *The voice fixes need both halves to be current.* The part that reads a session's conversation runs in the app on your own machine; the part that decides what to say about it runs on the Gateway. Until the app is updated, a transcript that cannot be found is still reported as an empty conversation, and the session it belongs to can still go quiet. Update the app, and update your Gateway too if you run your own. There is no migration and no new setting. ## v2.0.2 - August 8, 2026 A small release that finishes the mission lifecycle. Missions could be started but never ended, and the fleet was found in exactly that state - eleven missions, several of them finished days earlier, with no way out of the list. You can now end one - from the command line, which is the whole surface for this until the Cockpit gets an archive view. - **A mission can be ended, renamed, or brought back.** A mission is the body of work a session belongs to. Until now nothing anywhere could end one, so the list only ever grew, and finished work sat beside live work with no way to tell them apart. Five commands now do the whole lifecycle: `cc-devthrottle mission rename`, `mission complete`, `mission remove`, `mission reopen`, and `mission list` filtered by state - `--all` or `--state active|complete|removed`. All of them are in the agent-discoverable actions list, not just the help text, so an agent that finishes a body of work can find the verb that ends it. - **The wording is most of the work here,** because these commands are the only surface for it. A rename names the old name too, so it is visible which mission moved, and says the identifier is unchanged - because "will this detach my sessions" is the first thing anyone wonders. Ending a mission says where the record went and how to get it back, naming both the list command and `reopen`: there is no other way to see an ended mission yet, so a bare "done" would leave you unable to find it. An empty filtered list says *which* list is empty, because a bare "no missions" under a filter reads as "you have none at all" - a different and much more alarming thing. And a mission with no stated reason for existing is flagged rather than shown as an empty cell, the same rule the Cockpit card follows. - **Your agents can actually use those commands.** The commands above reached a service that refused them: every mission verb answered `403` for an agent session, on a service that had just been given the routes - a session key could create a mission and read one, but not change one. An agent may now change a mission it can already create and read. This is no wider than what it already held - the mission is resolved inside the caller's own account, and another account's mission answers "not found" exactly as a read does. - **Also in this release.** `mission create --parent` is gone: missions are flat now, and the flag was still sending a parent identifier to a service that no longer has the field. Resolving a mission by name or short identifier now looks at every mission rather than only the active ones - without that, `reopen` was impossible, and `rename` failed on exactly the missions most likely to need correcting. ## v2.0.1 - August 7, 2026 A hardening release. Every item here is a defect found during or just after v2.0.0, several of them by walking the product on a clean machine as a new user would, and several more by an independent review that sent the work back before it shipped. - **Your dictionary now reaches your own dictation.** If you use DevThrottle in the cloud, the words you added to your dictionary were not affecting your dictation at all: the correction pass read a shared dictionary rather than yours, so adding a term you say all day changed nothing, and the promise that your dictionary follows you everywhere quietly failed. Your dictation now reads *your* glossary. Two details worth stating plainly, because either could have been got wrong and both were checked: if you have written no dictionary you get *no* correction, never somebody else's terms; and running DevThrottle on your own machine is unchanged. - **A broken dictionary no longer costs you the transcription.** A malformed or unreadable dictionary file could fail the whole transcription instead of stepping aside - backwards, since the dictionary exists to improve a transcript. One that cannot be read is now skipped and you get your raw text. It does not fall back to anyone else's terms either: failing open means your own words, not a stranger's spelling. - **The dictionary never did bias speech recognition, and now says so.** The product told you, in the app and on the phone, that your terms were "biased into speech-to-text". They were not, and the code path that would have done it had no caller - your audio goes to speech recognition untouched, and your terms are applied afterwards to the finished transcript. The wording is now what actually happens everywhere it appeared, and the dead path is gone. This changes no behaviour; it stops the product describing a design it does not have. - **A request we cannot place is refused rather than guessed at.** On the hosted service, one voice route would accept a request whose account could not be resolved and quietly treat it as a local, single-machine request - reading the shared dictionary and filing the transcript in the wrong place. Every comparable route already refused; this one now refuses too. - **Also in this release.** The Missions board groups sessions by the mission they belong to, hides missions with nothing in them, and always tells you how many there are. Dictation no longer carries a finished recording into a session you have since moved on from - the guard now arms from both ways of starting to speak. The root folders caption says what actually happens: discovery is the local scan. And `workflow run` accepts the short run id it prints to you, while a web page answer is never mistaken for data. ## v2.0.0 - August 6, 2026 On 5 August every session on every machine was locked out at once. The cloud Gateway was older than the app talking to it, so it refused each session's credential, and every command an agent ran answered "missing or invalid token". The outage lasted hours rather than minutes because nothing said so - the Home page showed no problem, and the error the command line printed blamed the credential, which was fine all along. That is what this release fixes. - **The Home page shows a red Sessions row** when the Gateway will not accept this Director's session keys, and says that it affects every session rather than one. Previously that state produced no row at all, so the one screen built to surface it was blank while the whole fleet was locked out. - **The command line no longer blames your credential.** A refused session key now explains that the Gateway may simply be older than the app - and says which line in the log tells the two apart - instead of asserting that your token is wrong. It deliberately does not guess which cause applies, because it cannot tell from where it stands. - **The app asks the Gateway what it can do** the moment it connects, and says plainly in its log when the Gateway is missing something it needs. Before, it discovered this one failed call at a time, from an error carrying no version and no detail. - **Sessions no longer go permanently silent.** A session could stop speaking forever with nothing reporting a fault - its rail sat on "Preparing voice" indefinitely, it was never played, and no error was raised anywhere. The cause was a corrupted internal pointer: something could overwrite a session's record of its own transcript with a value that was not a transcript at all, after which the session could never be narrated again. Running DevThrottle's own test suite from inside a live session did exactly that, which is how it was found. Both halves are fixed, and a session already damaged this way is repaired by restarting it. *If you run your own Gateway, update it as well as the app.* This release changes what the app asks the Gateway for. An older Gateway will still work - that is tested in both directions, and the app now says clearly when it happens - but the fleet features are only fully available once both sides are current. ## v1.9.11 - August 5, 2026 Your plan now includes the AI features, the phone recorder lasts all day, and the Windows application finally carries the current mark. - **The AI features are included in your plan - no credits needed.** Dictation, spoken replies, session naming and the Wingman come with DevThrottle Pro and with the 14-day Pro trial, and the app no longer asks you to add credits for any of them. Dictation and voice work on a brand-new account from the first minute, with no balance to top up. The Wingman, session naming and dictation cleanup run on DevThrottle's included models, and the model settings offer exactly those models, so a saved setting can never route your included features onto paid API models. If your trial has ended and you have no subscription, the app says so plainly and points you to the pricing page rather than asking you to buy credits for features credits do not buy. Prepaid credits remain what they always were: optional, and only for calling the DevThrottle model APIs directly with your own API key. - **The phone recorder lasts all day.** Recording no longer stops at a default time cap, keeps capturing while you navigate between screens, and shows a recording indicator on every screen. It holds a wake lock and asks Android to exempt it from battery Doze, so long recordings are not silently killed in your pocket. If a recording ever has to be cut short, it is cut short loudly - you are told, instead of discovering a truncated file later. - **The Windows Director shows the current mark, not the old name.** Every surface had moved to the new mark except the Windows executable, which still carried the old two-C icon in the taskbar, Alt+Tab, the title bar and the installer's file properties. Windows and macOS now match, and the icon carries nine drawn sizes instead of four, so it no longer looks soft at taskbar scale. Windows caches application icons aggressively: if a pinned shortcut still shows the old mark after updating, unpin and re-pin it, or sign out and back in. ## v1.9.10 - August 5, 2026 A single fix: the Handovers list in the New Session dialog now shows your newest handover first. The tab ordered documents by their filename rather than by their date. Handovers written by the product itself are named for what they are - a session move, a rebuild manifest - while the ones you write are named for the day and minute they were written, and sorting those names as text floated every name beginning with a letter above every name beginning with a date. The result was a list that looked sorted but was not: a handover written minutes ago sat thirteenth of a hundred and forty-three, below a dozen machine-written files, and the date shown against each row ran out of order the whole way down - so the one column you would use to find your document was the one column you could not trust. The list is now ordered by that same visible date, newest first, which is how the Cockpit has always shown it. Reading the list is also no longer done on the interface thread, so opening the tab with a few hundred handovers no longer briefly holds up the window. ## v1.9.9 - August 5, 2026 The portless release. Until now both the Director and the launcher listened on a local network port, and agents could reach the fleet two different ways - through the Gateway, or directly through that port. Neither listens any more: everything an agent does now goes through the Gateway, one door, always. - **Windows will not ask about the network on first launch, and cannot start asking again.** The security prompt that appeared on top of the setup wizard, swallowing the clicks meant for it so a new install looked frozen in its first minute, was caused by the Director opening candidate ports to test them. v1.9.8 stopped the prompt by narrowing what that code touched; this release deletes the code outright, so the cause is gone rather than avoided. - **Your agents stop having a wrong door to find.** An agent that can reach the fleet two ways will eventually use the wrong one, and documentation does not fix that. There is now one way, so there is nothing to choose - and the product stopped shipping agents instructions that pointed at the old door. A machine that never accepted a connection cannot have one guessed at, scanned, or exhausted. - **A security fix you did not ask for.** Skill, workflow, schedule and mission commands used to read your account-wide credential from disk and present it, which meant any agent running one of those commands held authority over your entire account, on every machine - true of every release before this one. Each session now gets its own credential instead: bound to that session, limited in what it may call, expiring, and revoked when the session ends. An agent can still change how the product behaves - settings, handovers, sessions, missions - but it cannot change who is allowed in. Device enrolment and account identity are refused to it. - **What you will notice day to day.** Fleet-wide commands are slightly faster, since the local hop is gone. A session reading its own terminal is slower - roughly a third of a second to under a second against a hosted Gateway - because what used to be a local read is now a round trip. With no Gateway reachable, agent tooling does not work: a deliberate trade, not a regression, and the error says so plainly and names the self-hosted gateway as the answer. Starting, stopping and updating the application still work with the Gateway down, because process lifecycle never asks the Gateway anything. *Update the launcher with or before the Gateway.* A launcher older than this release registers normally but cannot be commanded by an upgraded Gateway, because commands now travel down the connection the launcher itself opens; if that state occurs, the refusal names the cause rather than failing vaguely. Stated honestly: the Director still opens a local listener during interactive sign-in, to receive the callback from your browser - loopback-only, lasting as long as the sign-in, and carrying nothing an agent can call. The Director runs without a listening socket; it is not that it never opens one. ## v1.9.8 - August 3, 2026 Sessions can now move in and out of missions while they run - shipped quietly in v1.9.7 and announced here - and a brand-new Windows machine's first minute no longer looks broken. - **Move any session in and out of any mission.** The v1.9.7 release included this and its notes never said so, so it is announced here. A session no longer has to be born into a mission: attach any running session to a mission, move it between missions, or detach it entirely - from the command line, with no restart and no respawn. `cc-devthrottle mission attach` attaches a session, or moves it if it already belongs to another mission, and tells you which mission it left; `--with-children` also brings along every session the target controls, all the way down; `cc-devthrottle mission detach` returns a session to belonging to no mission, the ordinary state. The session's workflow seat moves with it, so a session shown under one mission is never quietly governed by the conduct of the one it left, and a seat you chose yourself at spawn is preserved. Sessions spawned by a controlling session now also inherit that session's mission by default, so a team stays a team without anyone remembering a flag. One honest limit: a running agent keeps the instructions it was handed at birth, so after a move the command tells you exactly how to ask the session to fetch its current conduct. - **The setup wizard no longer appears frozen on a brand-new Windows machine.** Windows showed its firewall security prompt directly on top of the wizard's first button, where it silently swallowed every click aimed at it - no error, the product simply looked broken in its first minute of use. DevThrottle no longer does the thing that made Windows ask: it now checks candidate ports on the machine's internal address only, so the firewall prompt does not appear at all. - **Browser profiles is one clickable row again.** The entry in the Director's side rail used to unfold into a list of every profile with its own Start link, taking a third of the visible rail. It is now a single row showing the profile count and a green dot when at least one is running; clicking it opens the Browsers settings screen, where all the actions already lived. - **A logging fault can no longer take down the work that was being logged.** Stopping and restarting the application's log writer left it in a state where every later log line threw an error into whichever operation happened to be logging - so one defect surfaced as several unrelated, unreproducible failures. The writer is now replaced rather than revived, and a log call that cannot be accepted is dropped and counted instead of thrown. This one fault was behind most of the sporadic test failures seen on the local gate. For people running the source, two test-suite fixes make the local gate more trustworthy: a backoff test now measures the code's behaviour rather than the machine's load at that moment, and a test that takes the machine-wide gateway lock is kept out of the parallel run, where it could stall the whole run indefinitely. Known and not fixed here: the Director's large-object heap still grows on an instance left running for days, a vault catalog scan over a synced folder can run away (diagnosed, not fixed), and four repository views still show a failed git read as an empty result rather than saying the read failed. ## v1.9.3 - July 31, 2026 A security release. The Director's local control interface now requires a credential, and terminal session recording is off unless you switch it on. - **The local control interface requires a credential.** Anything on your machine that talks to the Director - the command line, hooks, the launcher, the settings tools - now presents a credential it is given automatically, and requests coming from a web page in your browser are refused. The tools that needed credentials were updated in the same change, so there is nothing for you to do. - **Terminal session recording starts off.** It used to record by default and keep everything indefinitely. It is now a visible setting that starts off, recordings are deleted when their session is removed, and recordings left behind by earlier versions are cleaned up the first time this version starts. *If you have old session recordings you want to keep, copy them out before you upgrade.* - **The download comes from DevThrottle's own storage.** The download link on this site used to point into GitHub's release storage; the release pipeline now publishes it directly. ## v1.9.2 - July 31, 2026 The main window fits the screen it opens on, a first install stops reporting its own success as a failure, and sessions stay in the Director when a machine's connection wobbles. - **The window fits the screen.** The main window could open larger than the display it was on, putting the Settings button off the right edge - which quietly broke every "you can change this later in Settings" the setup wizard says. The window is now measured against the screen's usable area and centred before it is shown, down to a 1280x720 display. - **A first install stops calling a healthy launcher dead.** On a clean machine the launcher unpacks itself on first run, which took longer than the installer's fixed twenty-second allowance - so the install ended on an error while the launcher was answering perfectly well. Waiting is no longer treated as a verdict. - **Sessions survive a wobbly connection** instead of vanishing from the Director, and renaming a Director now carries everywhere. ## v1.9.1 - July 30, 2026 The app stops getting slower as sessions pile up, and one number was removed on purpose. - **The context percentage is gone where it was guessed.** The gauge divided real usage by a context window inferred from the model's name, which was wrong for the model DevThrottle is most often run with - a session with roughly 800,000 tokens of room left could read 92 percent in red. DevThrottle now shows a context window only when the agent itself reports one; where it does not, you get the raw token count with no percentage. A missing number is an annoyance, a confident wrong one gets acted on. - **The app stops feeling slow as sessions accumulate** - three costs that grew with every open session were measured and cut - and buttons answer the moment you click them. - **Auto-update says which situation you are in** rather than leaving you to guess. ## v1.9.0 - July 30, 2026 DevThrottle speaks French and Spanish, and several things that used to fail quietly now say so. - **Pick a language and everything spoken follows it.** DevThrottle speaks from four places - the narration of what a session just did, the direct reply when you ask it something, the in-product help, and the assistant. The speaking rules now live in one place, so a language reaches every spoken path. What is translated is what DevThrottle *says*: the on-screen text stays English, deliberately, for now. - **The voice choice is not evenly matched, and the screen says so.** English has twenty-eight voices, Spanish three, French exactly one. English is unchanged unless you choose otherwise. - **Car Mode is out of the product for now.** The assistant that shared its underlying brain stays - it is the same thing that answers you in the app. - **A prompt that was never delivered is surfaced** instead of being recorded where nobody would look. ## v1.8.1 to v1.8.8 - July 27 to 30, 2026 A fast line of releases between the work-history release and 1.9. The ones worth knowing about: - **Updating became something you can check (v1.8.8).** DevThrottle has updated itself for a long time; from this version something is left behind to verify that the update worked, and to put the previous version back when it did not. - **Agents launch ready to work (v1.8.6)** instead of asking for approval on every call, and a whole skill directory can be held and placed where each agent looks for it. - **The installer offers Git (v1.8.3)**, which the app needs to read repositories at all, and the macOS file-search guidance now names the path to grant access to. - **Every session records who started it (v1.8.2)**, and History shows the shape the work had rather than a flat list. The screenshots folder you set is the one you see. - **Cockpit dictation matches the phone (v1.8.1)** - live level bars and a Speak button that sends without making you wait on it. ## v1.8.0 - July 27, 2026 Every session now tells you its story: when it started, how long it has been open, how long it has been waiting on you, and what it did - live on the session cards, and kept in a durable work history you can read back across all your repositories. - **Session cards answer the supervision questions.** Every card in the Cockpit and on the phone now shows when the session started, how long it has been open, how long it has spent waiting on you, and how many turns the agent has completed - ticking live. Waiting time turns amber after an hour and red after four, so a neglected session looks neglected. - **Work history.** DevThrottle keeps a durable record of every session as it runs - what it was asked to do, how it ended, and a summary of what it built. The new History page shows your work across all repositories, grouped by repository and day, and survives crashes and power cuts because the record is written while the session runs, never at the end. - **First-run wizard.** Setting up a new machine is now one guided journey instead of a chain of dialogs - it finds your coding agents, offers to install what is missing, locates your repositories and screenshots, and explains each step as an offer, never a demand. - **Fleet Assistant.** Ask questions about your whole fleet in plain language - by chat or voice, from the Cockpit or the phone - without being tied to any one session. - **Trustworthy voice input.** Test your microphone and test transcription from Settings on both surfaces, and DevThrottle now measures every dictation's microphone quality in the background and shows the detail in a Transcription Health view, so a bad microphone gets caught before it ruins a day of dictation. - **One Settings page.** The phone and the Cockpit now show the same Settings - same tabs, same names, same cards - so a setting you find on one surface is where you expect it on the other. - **A 14-day Pro trial for every new account.** Also in this release: voice mode is a real switch with the way out on every screen, and the voice queue plays the waiting sessions first-in-first-out with big buttons on top; the phone's voice recorder is back, with durable segments that survive interruptions and transcripts on both surfaces; the mobile Snooze button lets you pick a length, and a session returning from an expired snooze is labeled so you know to go see why it went quiet; repositories are a first-class subsystem - an always-current monitor, safe worktree and branch cleanup with an orphaned-worktree reaper, and a worktree that an open session is using is never touched; the shared workflow library lets you browse the built-in workflows, switch them on or off per account, and clone one to customize it; each session's uncommitted file count shows in the roster, so you can see who is sitting on unpushed work; the session roster puts Sessions first in the rail, and the Needs-you group is a waiting line with the longest-waiting session on top; the phone says nothing about the network unless something is actually wrong; no user is ever shown a bare status code - errors arrive as plain sentences, and browser errors also land in the Gateway log so they can be diagnosed after the fact; the About page reports the Gateway, Cockpit, and mobile app versions; one Director executable can run several named profiles, and a staged update applies itself automatically when no sessions are running; scheduled runs name their sessions after the schedule and fire time, and asking an agent to clear a session's context now asks you first; and many reliability improvements to the hosted service, including safer deploys with a warmed standby, honest network verdicts, and per-account serving of settings, statistics, and transcripts. ## v1.7.4 - July 23, 2026 The macOS setup wizard now mirrors the Windows one, the hosted gateway now scopes every surface by account, and dictation is more reliable and more honest when something goes wrong. - **The Mac setup wizard, rebuilt to match Windows.** A cleaner Welcome screen, the obsolete Standard/Developer choice and the separate Gateway step are gone, and uninstall is fully ported - so setting up on a Mac is the same simple flow as on Windows. - **Strict account isolation on the hosted gateway.** A large hardening pass makes every hosted surface account-aware - directors, sessions, voice, devices, stats, and keys all now enforce account-scoped authorization - and per-device keys are stored hashed at rest. - **More reliable, more honest dictation.** Dictation keeps your last word instead of clipping it, pads trailing silence, and warns you when a send drops audio instead of shipping silence - across the desktop, the Cockpit, and your phone. - **macOS tools fix.** The command-line Python tools now find their config on macOS, shipped through the tools bundle. Also in this release: the desktop status box shows which gateway you are on and its connection state; Send-direct from the Cockpit Speak box sends the transcribed text; scrollbar thumbs draw at full thickness instead of a hover-only sliver; and many correctness and test fixes across the fleet. ## v1.7.1 - July 21, 2026 You can now change which gateway a Director connects to right from the app - disconnect and reconnect to a gateway on your own machine or the hosted one, without editing any files. - **Change gateway from the app.** Settings -> Gateway has a new "Change gateway" button: it disconnects this Director and takes you back to the connect screen to pick another - your own machine or the DevThrottle hosted gateway. No config files, no command line. - **One-click hosted connect.** The "Use hosted" choice is live - sign in with your DevThrottle account in the browser and the machine joins the hosted gateway under your account, with no address to type. Also in this release: if a new connection does not take effect immediately, the app now tells you clearly instead of sitting on "Connecting". ## v1.7.0 - July 21, 2026 Sign in with your DevThrottle account and control a hosted cc-director from the Cockpit and your phone - on the shared hosted gateway, with each account seeing only its own work. - **Sign in on the hosted gateway.** Open the Cockpit or the phone app, sign in with your DevThrottle account, approve the device once, and land in your own hosted Cockpit - no tokens to paste. Everything you see is scoped to your account. - **The Cockpit opens from the gateway address.** Clicking Cockpit on a hosted director now opens the real hosted Cockpit in your browser. The Cockpit and the phone app are both reached from the one gateway address - its cockpit and mobile paths - the same way whether the gateway is hosted or running on your own machine. - **Strict separation between accounts.** The gateway works out which account a request belongs to from the signed-in identity alone, never from anything the browser or app claims, and refuses by default anything it cannot place. One account's directors, sessions, voice, and usage stay entirely separate from another's. - **A hosted gateway is a paid gateway.** Signing a device in to the hosted gateway now requires an active subscription. A gateway you run yourself is unchanged and needs no subscription. Also in this release: the phone app now lives at the gateway's mobile path, with the old address redirecting so nothing you have bookmarked breaks; the in-window Fleet Map was removed from the desktop app; voice recordings still uploading are cleaned up on an activity-aware schedule; and a plain-English guide to trying the hosted gateway is in the documentation. ## v1.5.0 - July 16, 2026 The Gateway becomes the single source of truth for what each session is doing, you can install from the command line with no wizard, and the Gateway core gains the groundwork to run beyond Windows. - **One honest picture of every session.** The Gateway now decides each session's state and pushes it out, so the desktop rail, the Cockpit, and the mobile roster all show the same thing - including how long a session has been snoozed and when it is winding down - instead of each surface guessing on its own. - **Install from the terminal, no wizard.** A command-line installer sets DevThrottle up end to end from the terminal on Windows and macOS, and macOS gets a curl-based install that Gatekeeper cannot block. Command-line sign-in is Windows-only today; on macOS a machine joins your gateway with enroll instead. - **Groundwork to run the Gateway anywhere.** The Gateway now runs headless on Linux and macOS, proven in a Linux container, and ships with a Dockerfile you can build yourself. This is foundation work - the Gateway downloads are still Windows-only. - **See what you have spent.** New governance screens show your usage by day, week, and month, and each session's token spend is stored and sliced by hour and model. Also in this release: the text injected into every new session is now a Gateway-owned setting you can view and replace; a self-imposed hold now goes through the Gateway and actually takes effect; Your Throttle stats recognize Azure DevOps remotes alongside GitHub; remote session spawn works over a tunnel-only connection; the move-session skill ships; and the Speak box opens instantly without ever opening a second copy. ## v1.4.0 - July 16, 2026 A big reliability-and-visibility release: the fleet's voice is steadier, your stats now show which AI model did the work, and the desktop app gains a live fleet map. - **See which model did the work.** Your usage stats now break down by the AI model and the agent tool behind each turn, and each session's token spend is carried up to the Gateway, so you can see what you actually ran. - **Live fleet map in the desktop app.** Watch every session across your machines at a glance, click to select, with the supervisor spawn tree laid out. - **Know who is speaking.** The wingman says which session is talking before it reads a summary, so when you are listening without looking you always know who is speaking. - **Steadier voice.** A single slow moment on one session no longer silences narration for the whole fleet, and when speech genuinely fails you are told the truth instead of getting silence. - **Pick a snooze length.** The desktop and Cockpit menus now offer a list of snooze durations, not just one default. Also in this release: the Gateway now runs as a background service with a simple Start and Stop tray, and first run no longer asks for a pairing code or a consent window; the mobile app's layout was reworked to sit correctly in the visible screen area, with play controls that mean the same thing everywhere; the Cockpit's settings are organized by topic, the session rail scans by icon, and workflows are served straight from the Gateway; many session-state corrections, so a session's colour and status always tell the truth; and more resilient dictation - a dropped dictation is now loud and gives your words back rather than failing quietly. ## v1.3.0 - July 14, 2026 A reliability-and-honesty release: when something goes wrong you are told, and a session's state always tells the truth. - **Honest failures.** A dropped command now explains itself instead of hanging or returning a bare error, and writing into an agent's terminal tells you when it fails. - **Session state you can trust.** A working session is always blue, matching the spec, so a session's colour and status tell the truth. - **Full prompt-and-reply logging.** Every prompt and reply, for all agents, is recorded with where it came from. Also in this release: the inbound network port was closed and Director Settings restored, removing a connection check that could only mislead; and a cleanup pass deleted dead code, corrected the public API reference, and removed documentation describing features that never shipped. ## v1.2.0 - July 14, 2026 This release brings session rename and close back, fixes glitches on large replies, and adds full macOS support. - **Session rename and close work again** across the fleet. - **No more glitches on large replies.** Voice, Wingman, History, and the mobile session roster stop blinking when a reply is large. - **macOS support.** Mac builds, app-bundle placement, launcher start, and the command-line tools. - **Clear All screenshots deletes the files on disk** after a warning. - **New Session picks the agent, not the model.** Also in this release: Tailscale is no longer required to install; a per-repository default for Open in Browser; Repos becomes a fourth tab of Your Throttle; the terminal verifies every prompt actually submits, not just large ones; snooze honors a requested duration; and fleet-wide "message all" is back. ## v1.1.0 - July 10, 2026 This release gives your sessions real roles and missions, lets your other machines connect without opening a port, and makes voice dictation and long recordings far more reliable. - **[Session roles and missions](https://devthrottle.com/docs/director/roles).** Every session now shows a role at a glance - Architect, Manager, or Worker - and related sessions group into a named mission. Roles are worked out automatically from how you start and connect sessions; you set the Architect yourself for the session that plans and oversees the work. - **[Connect other machines without opening a port](https://devthrottle.com/docs/gateway/portless) (preview)**. Let your other computers connect to your main machine without opening or forwarding a network port - the other machine reaches out instead of waiting to be contacted, which is simpler to set up and safer. Opt-in and off by default for now. - **More reliable voice dictation on your phone.** Dictation holds your audio in a durable queue and keeps trying to deliver it, so a brief network problem or an app restart no longer loses what you said - with clear status instead of silent failure. - **Long recordings and clearer transcription.** Long voice clips are split at natural pauses and transcribed in parallel, and a failure now shows a plain-language message instead of a raw error. Also in this release: a clearer signed-in version and self-repair in the phone app; fewer duplicate and stale notifications; Wingman voice fixes; a security fix that stops the Gateway leaking extra service keys; in-app image generation available again; and a simpler, more focused interface with several in-progress panels removed while they are finished. ## v1.0.6 - July 6, 2026 - Cockpit: major port of the Director experience to the new React Cockpit - session roster and rail, reply and action bar, fleet views, schedule, dictionary, and account pages. - Mobile: voice-mode audio player (resume, restart, seek), durable server-owned dictation upload (a refresh never loses recorded audio), and screens that stay awake. - Reliability: crash-safe Python tools install and Director self-repair of a broken shared runtime. ## v1.0.0 - July 4, 2026 - First stable release: the signed Windows installer line (Azure Trusted Signing) that ships from devthrottle.com today. ## Before 1.0 The 0.9.x line was the pre-release run-up during quiet launch week. Its history is preserved in full on the releases feed. > **Note:** Pricing lives on its own [pricing page](https://devthrottle.com/pricing). We keep prices public and never raise yours without telling you first.