About and install

Hand it off. Walk away. Return to results. Files open right in the app, every step shows, and Bots get better with use; multi-day, multi-step jobs that need rework are safe to hand off too: when a Bot says done, the app checks first.

What it fixes

The three places other agent tools most often leave you stuck are the app's own job here. Each point ends with a real case from another tool.

• Files have a place, and open where you are. Each job gets its own folder under work/ in the workspace, each ticket a subfolder; the files a Bot writes in a turn are attached to its reply on their own, and scratch files and large tool output are not counted as work. They open in the app: images, audio and video, PDF, text and code, single-file HTML, and .docx, .xlsx and .pptx read locally (switch worksheets, browse slides, view full-window, Escape or phone Back to leave full-window; format support and limits); text in the workspace can be edited and saved back where it was. Opened from a message, the tree lists only the files it names; opened from the flow, every file the job has referenced. Find fault right on the file: a spot in text or code, rendered Markdown, an image or PDF region, an HTML element or a moment of audio or video; the batch goes out as one reply, and the Bot that handed it over works through it and resolves it note by note. Making films with Claude Code or Codex before, you opened each cut in a player yourself, noted which second and which frame was wrong, and typed it back.
• It shows its work. A job is one tab: tickets on the left, each row with who makes it and who reviews it; the flow in the middle, drawn by who woke whom, a card per turn marking the ticket it worked on, the files it handed over, the model it ran on and why; the app's own calls (reading your line, filing, the settle, retrospectives…) sit between the cards and open to their verdict, prompt and raw answer. The app files each message you send under the job and its ticket and lists your requirements in the plan's spec, the same list as the requirements ledger; you can open the direct chats Bots have with each other, and watch a Bot's command print its output as it runs. Running a long job in Codex before, you could not tell which task a step belonged to, and by the end the work was unrecognisable.
• Bots get better with use. Once a job you accepted is delivered, each Bot that handed something over in it and had something go wrong reads the job's record, finds where it tripped up, which of its ways made you send work back and what to do again, and works that into its own memories and skills: the same subject overwritten, two about one thing merged, a wrong one corrected, so they don't just pile up. It posts nothing and asks you nothing; the trace's Plan view lists it under Retrospective, with an undo for each change. All three built-in engines run it; switch it off under Tools → Roles if you don't want it — how it works. With Gemini or Grok before, a requirement you had given was forgotten again on the next job.

Why you can hand it over

The model does the work; the app holds it to account: where a job stands is decided by the app's own records, and what a Bot says only counts as a proposal. Each of the four points below came out of a real failure. They are rules in code, not prompts: you can change how Bots work and which of the app's own steps run (see Make it work your way below), but no prompt loosens them. They come as a whole: you can leave them out (the engine with no jobs, Plain), but not take them apart.

• Your words are never lost. Every line you send is kept word for word in the same write that records it, and no Bot can write there; the rules and done-when you write on the flow board go into the requirements ledger and are only ever added to; a line in which you find fault with work handed over is kept too, as an entry waiting for your confirmation. Writing your requirements down from every line you send is the scribe's job, and the scribe is a step of the engine: on in the video engine, off by default in general and coding, so nothing is written down behind your back; to have it, choose the video engine for the conversation, or switch the scribe on in its engine under Roles (every conversation on that engine follows). It can only propose patches, every quote has to be words you actually wrote, which the app checks, and a change is only a replacement waiting for your confirmation while the old one stays in force. Before this, your requirements lived on one list rewritten whole each time; across 70 revisions it dropped 15 rules, and "the robot arm is the left hand" and "about 2 minutes long" never came back.
• Done has a definition. A ticket moves only on a delivery, checks the daemon runs on your Mac, a review backed by evidence and your approval; with nobody to review, the app approves only when every check passes, and waits on your word when evidence is missing — no card: say it is fine and it goes through, say what is wrong and it goes back. A Bot writing "PASSED" moves nothing. Lines of the done-when that a machine can decide (a file exists, contains something, matches a pattern, a command succeeds, the parts several Bots made — chapters, images, shots — fit together) become checks, with the results on the flow board; you add them, or the app turns a command the job actually ran successfully into one, and Bots cannot write them. Before files are handed over, a "results to follow" needs a booked check-back or a named handoff, and a "tests pass" or "verified" needs a command that turn actually ran, or it goes back. Before this, a reviewer Bot passed a 107-second cut as "about 2 minutes", and you overturned five full-cut approvals. A large job — a whole episode, a book of many chapters — is laid out first: one part is the sample you approve, the others wait for it and are compared with it when handed in.
• Stop is a state. A stop is a record only you can lift, and starting a turn, waking a Bot and every tool call with side effects check it first; Stop ends a running turn at any time. Before this, after you said "hold on", the video director kept sending shots for review in two other direct chats, and a plan call-back had it hand in a new one.
• Stalls get chased, without pestering you. A supervisor looks every 15 seconds, calls no model and survives restarts: when a job goes quiet, it calls back the Bot holding the ball, and work a restart cut off picks itself up. The app comes to you only for your approval, for something only you can give, or when work has truly stopped; ask "how's it going" and it tells you what is waiting on you, who is on it, how far it got and which check fails, without waking or interrupting a Bot at work. Before this, a long job cut off by a restart sat for 7.6 hours with nobody knowing; then it swung the other way, with four cards in a day asking about default models.

Who it's for

• For solo developers, technical individuals and small studios who already use a local agent such as Claude Code or Codex, or can set up a model endpoint and API key themselves, with multi-day, multi-step work that needs rework and can't be watched all the time: a multi-episode AI video (shots, renders, review, rework), a daily news brief on a routine, a launch kit. The built-in video engine is tuned on the record of exactly this kind of work; the coding engine has little record behind it yet, so its numbers are still the old defaults. One Bot on its own will do, and a team of Bots is for work that really splits.
• Not yet for a one-off question or a job done in half an hour (one Bot is plenty, and lighter tools exist); several people sharing one setup, work that has to carry on while the Mac sleeps (on power, while work runs, the app keeps the Mac from idle sleep; closing the lid or running on battery still puts it to sleep), or anyone with neither a local agent nor a model endpoint of their own. Windows and Linux are experimental previews: each release carries an unsigned Windows installer and a Linux AppImage and deb, and some features are not there yet — see Get it.

What it does

• Persistent teammates. Bots have names, duties and boundaries; they chat one to one, join groups, get @mentioned and hand work to each other; a Bot that is mid-task is not cut off when a teammate @s it, and reads the line on its next step — as it does several lines you send in a row, or a line of yours you changed after sending it; a line not read yet can be taken back, or inserted to be read now. One Bot on its own will do; when the work splits, let it hire the rest.
• It asks as much as you want it to. A permission mode — read-only, ask first, auto (the default) or allow all — says what Bots do without asking: under auto they write files and run commands, and adding endpoints or MCP servers or changing built-in prompts waits for your approval; one Bot can have its own mode. The workspace is where every Bot's work is kept, not a permission line. What waits on you is marked on the conversation list, with macOS banners and a Dock badge.
• The work and the files stay on your computer. Window, daemon, sessions and the shared workspace are local, and keys go to the Keychain (Credential Manager on Windows, the system keyring on Linux). You bring the models and MCP servers: any OpenAI-compatible or Anthropic-compatible endpoint works, including Ollama or LM Studio on your own computer (see Local models), and each turn's context goes to the endpoint you configured.
• Or let your own Claude Code run a Bot. Set a Bot to Claude Agent and each of its turns is run by the Claude Code you installed and signed in to, with its own tools, on the account it is signed in with (a Claude subscription or an API key); approvals, Stop, hand-overs and reviews work as for any Bot. A floating usage widget (and the menu bar) then shows how much of your plan's 5-hour and 7-day windows is used, as your Claude Code reads it — Codex's too, and the other agents' turns today. With several Claude accounts on one computer, each Bot can run on the one you pick (by its Claude Code config directory). Or talk to it directly in a project directory, as in its own desktop app: the sidebar's Projects section holds those sessions, grouped by directory, and can carry on one you started in a terminal from where it left off, your terminal's session untouched. All of it can be set up from the paired phone too. The app never signs in to Claude or touches its credentials — how it works.
• Or another agent. The Runner can also be your own Codex, Grok, OpenCode, ZCode or Antigravity, or any program that speaks ACP that you add in Settings; on your own sign-in, with the same boundary, approval cards, hand-overs and reviews, and a turn stopped on the spot if it did without asking what its permission mode would have asked about (ADR 0079).
• Make it work your way. The four rules above are code and no prompt changes them; everything hung on them can, and the engine Plain leaves them out altogether: no plans or tickets, no reviewed hand-overs, nobody chasing the work, only your approvals, stops and spend (ADR 0103). How the app's own steps run is the engine: whether the scribe, the closing check, the settle, escalation, retrospectives and reflection run, and numbers such as how far apart check-backs are and how many failed hand-overs stop the work to ask you; general (the default), video and coding are built in, chosen per conversation (a group's Actions, or a Bot's Actions in your direct), and what you change keeps only what differs from the built-in, or becomes an engine of your own — ADR 0085. Each step's model and prompts are set together under Tools → Roles: a map draws the steps by when they run, and a step opens in place to switch it, change its numbers, pick its model and edit its prompts. The System section and tool descriptions every Bot reads are under Settings → Prompts. Any prompt can be restored to its default and every change undone, or a Bot can propose one that you let through on its approval card; for now only you change an engine. The answer formats code reads stay locked, and approvals and holds do not change with a prompt or an engine — how it works.
• Bots argue from the records. Ask a Bot which kind of work keeps coming back, or which prompt to change, and it reads what the app keeps on this computer (conversations, turns, the requirements ledger, spend, work events…) and the daemon's log, read-only, and proposes changes from what it finds — only when you ask. Remote access's keys, push settings and your terminals stay out of its reach — how it works.
• Speak instead of typing. Set up a speech service under Settings → Models → Speech recognition — OpenAI, Groq, SiliconFlow, Alibaba Bailian (pay-as-you-go or Token Plan, which can reuse a Bailian endpoint's key), Xiaomi MiMo (any plan, reusing a MiMo endpoint's key the same way), Deepgram, ElevenLabs, or any address in one of their formats, a local Whisper server included — and a microphone appears beside the message box, on the computer and the phone: what you say becomes text in the box, for you to read over before sending. The recording goes through this computer to that service and is not kept — ADR 0073.
• Models by rule, stepping up when stuck. Each Bot has a default model, the one it used most over the last 7 days, or one you pin; work that needs to see images skips models marked as unable to. When the same job keeps failing or a turn keeps erring, it thinks one level harder, then climbs the ladder of models you order in Tools → Roles → A Bot's turn — models run by your own local agents included — Claude Code, Codex, Grok… (a pinned model stays put; the video engine does not step up). Each turn's card on the flow board says which model it ran on and why. What went wrong is filed by type, without asking a model whether the model fell short; a command that times out again and again, like a search of the whole disk, gets a warning and then a block from the app before the next call.
• A split-pane workbench. Divide the desktop window into panes of conversations, terminals, the routine calendar, workspace, Spend and Usage; where each kind of window opens (a new tab, in place, split some way, the pane beside, floating) is set in Settings → Behavior → Where windows open — by default a conversation replaces the one in front, artifacts and the job's views open on the right, terminals below. Drag a tab along its strip to reorder it; drag a conversation from the sidebar onto a pane, a tab strip or a pane's edge to open it there (one already open moves its tab there); right-click a tab to close it, the other tabs, the tabs to its right, or all of them. Close an empty pane with its top-right ×, or choose Close pane from a pane’s context menu. In the workspace file tree, ⌘-click or Shift-click picks several files and folders; right-click moves them to the Mac’s Trash, where Finder can put them back, or drag them onto the composer to attach them to your next message by path, with nothing copied. Fold the session list to a rail of avatars with the last button in its search row or ⌘B; the pulse button before it (on a phone, right of the search field; on the rail, under search) shows only the conversations a Bot is working in, counting those waiting on your approval or answer.
• Global search. Open Search from the sidebar or folded rail, or press ⌘K (Ctrl+K). Filter conversations, messages, files and routines in a keyboard-friendly dialog; phones use a full-screen view. In the editor or terminal, use ⌘⇧K (Ctrl+Shift+K). Rail icons explain themselves on hover or keyboard focus.
• Your own terminal. Shells held by the daemon keep running when the window closes; while a Bot works, its message shows what it has said so far, the commands it has finished folded into a line that opens onto a card (each one's output too, coloured like code), which stays under its reply once it is done, and at the end the step it is on — the file it is reading, the command it is running — with how long the turn has taken; the step opens onto what is printing right now.
• Spend by model, conversation and Bot, with a daily cap. Track turn, decision and feedback calls; reported amounts and estimates stay separate; with a daily cap set, every Bot stops once the day has cost that much, until you lift it — spend and billing rates.
• Routines. Bots start work daily or weekly on the local clock of the computer they run on — how routines work.
• From your phone — off by default. Reach your Mac through a relay you run yourself, end-to-end encrypted — remote access. With Screen Sharing on at the Mac (a VNC server on Windows), you can also see and operate its screen from the phone, lock screen included.

Get it

macOS 13 (Ventura) or later, Apple silicon or Intel. Windows x64 and Linux x86_64 (glibc 2.35 or newer) are experimental previews (see below).

• What you need: any one of these three.
  • A local agent, no API key: the Claude Code, Codex, Grok, OpenCode, Antigravity or ZCode (through the community zcode-acp bridge) installed and signed in on this computer, or any ACP program you add in Settings. Step 2 of the wizard lists the ones it finds signed in; pick one and Bots run on your own sign-in and plan (ADR 0078, ADR 0079).
  • A model endpoint: Anthropic, Xiaomi MiMo, Qwen (Alibaba Cloud Model Studio) and DeepSeek are built in, and the app tells which plan a pasted key belongs to; OpenAI and OpenRouter are presets; or any OpenAI- or Anthropic-compatible address.
  • A model server on this computer: Ollama, LM Studio or llama.cpp's llama-server, no key (see Local models).
• Download the latest .dmg from Releases; nothing else to install. From 0.1.0-rc.16 it is signed with Developer ID and notarized by Apple, so it opens with a double-click (older builds: Gatekeeper FAQ). On Windows, run Deskfolk_<version>_x64-setup.exe from the same release: it installs for the current user without admin rights, and as it is unsigned, SmartScreen warns about an unknown publisher (More info → Run anyway).
• Updates show as a dot on the labeled Settings entry at the bottom of the desktop sidebar; Settings → About downloads and installs them (on Windows and Linux, About opens the download in the browser for now). Appearance is in Settings → General → Appearance.
• From source on macOS (Node 22+, pnpm 12.3.4, Bun 1.2+, Rust, Xcode Command Line Tools):

git clone https://github.com/Blackman99/deskfolk.git
cd deskfolk
pnpm install
pnpm dev

• From source on Windows: the same git clone / pnpm install / pnpm dev, with Rust's MSVC toolchain and Visual Studio Build Tools ("Desktop development with C++") in place of Xcode, plus a one-time cargo build --manifest-path apps/conpty-helper/Cargo.toml for the terminal helper. Install Git for Windows as well: Bots' shell tool runs commands in Git Bash when it finds one, and in PowerShell otherwise. pnpm --filter @real-bot/desktop tauri build --bundles nsis builds the installer locally.
• Not on Windows yet: the independent runtime, installing an update inside the app, desktop notifications and the badge, and image thumbnails. Data lives in %LOCALAPPDATA%\real-bot and keys in Windows Credential Manager; installing it and how it differs are in Windows preview, prerequisites and packaging in the development guide.
• On Linux: download Deskfolk_<version>_amd64.AppImage (make it executable and run it) or Deskfolk_<version>_amd64.deb (sudo apt install ./Deskfolk_<version>_amd64.deb) from Releases. Data lives in ~/.local/share/real-bot and keys in the system keyring (GNOME Keyring or KWallet); Bots' shell tool runs commands in bash. Not on Linux yet: remote access, desktop notifications, installing an update inside the app and image thumbnails. Installing it and how it differs are in Linux preview; from source, prerequisites and packaging are in the development guide.

For long jobs on a source build (a multi-shot video, say), run pnpm dev:steady instead of pnpm dev: the daemon does not restart when the code changes or you git pull, so turns in progress are not interrupted.

First run: the setup wizard, in Chinese or English as this computer's language is (switch it in its corner, or later in Settings), walks you through picking a workspace folder, connecting a model, then a way of working (General, Video, Coding or Plain) and the Bot templates ready for it, made together, with a group when there are two or more; then let them hire the rest. If you already use Claude Code in a terminal, that last step can instead carry one of its sessions on as a project session. A model is either an endpoint and key (a preset or an address of your own) or a local agent already installed and signed in on this computer (Claude Code, Codex, Grok…): with that, no endpoint is needed, the Bots made run on that agent and the app's own calls run on its model (ADR 0078, ADR 0079). Anthropic, Xiaomi MiMo, Qwen (Alibaba Cloud Model Studio) and DeepSeek are built in: pick one and paste a key, and the app finds which of the vendor's plans it belongs to. A personal Anthropic key not scoped to a workspace also needs the workspace ID (wrkspc_…, from Console → Settings → Workspaces); see ADR 0072.

Once they are made, open your direct with a Bot: its first starter is "🌙 Hand it off, see it tomorrow morning". Pressing it fills the composer with one line asking the Bot to look through the workspace now, write a one-page brief into briefs/, and set up a routine at 9 every morning that writes a fresh one. Read it, send it, and come back in the morning to a brief already there.

Local models

Ollama, LM Studio and llama.cpp's llama-server all work as endpoints: pick the preset in the wizard, or add one under Settings → Models (an address such as http://localhost:11434/v1). An address on this computer or your network needs no key, and the model list and each model's context window are read from the server. Worth knowing first:

• The context has to be large. A Bot's step is often 20–90K tokens; the persona, instructions and tool definitions alone come to over 10K. Raise the server's context to 64K or more: on Ollama set OLLAMA_CONTEXT_LENGTH=65536 (or PARAMETER num_ctx 65536 in a Modelfile), in LM Studio set Context Length when loading the model, in llama.cpp pass -c 65536. When a long turn nears the window, its earlier work is condensed into a summary and it carries on; when even the instructions, conversation and tool definitions do not fit, the turn stops and says how big the step was and how big the window is, instead of answering from a prompt with its start cut off.
• The model has to call tools. A Bot's work is all tool calls. Test in a model's attributes shows its tokens per second, the time to its first token and whether it calls a tool it is given; a model the server says cannot call tools is tagged "No tools" in the list.
• Mixing works better. The readings of your lines and the planning calls run on the default model unless you choose others, and a local server that handles one request at a time puts them behind the step a Bot is writing. Keep the default endpoint and model on a cloud model and pin Bots to the local one in their profiles, or, under Tools → Roles, move just Reading and the Organizer to a cloud model (the organizer wants a strong one).
• Local is much slower. An 8B model writes about 30 tokens a second on an M4 Pro. Local endpoints get longer time limits (up to 15 minutes for the first token), and how long a step may write follows the measured speed. Details in ADR 0067.

Status

macOS is the primary target; features and data formats may still change there too. Windows and Linux are fresh, experimental previews — expect rough edges and missing features (see Get it); Linux has not been used end to end on a real desktop yet. Remote access is off by default and works on macOS and Windows (not on Linux yet). The installed app can pair: it keeps the Mac's remote identity in a private file rather than the Keychain and approves each device with Touch ID, or Windows Hello on Windows (ADR 0033, ADR 0059).

What is live and what is not · Roadmap · Domain language · Relay deployment

What is live, what is being built, what we will not do

"Live" means the code exists. It does not mean every model, tool combination or full task path has been accepted in a real environment.

Contributing

Development guide · Contributing · Security. MIT licensed. Not affiliated with xAI / Grok.