Skip to content

Latest commit

 

History

History
2664 lines (2366 loc) · 160 KB

guide.md

File metadata and controls

2664 lines (2366 loc) · 160 KB

Using Threadbear

Threadbear is a Mac app for running AI agent threads. It drives the official Claude Code and Codex command line tools on your own logins. A small program called the runner keeps every agent going in the background, so quitting or updating the app never stops a thread. Your threads are also copied to a Convex deployment of your own, which is how the iPhone app and the website can follow along.

This guide is for using it. INSTALL.md covers setting it up, and docs/ has how it all works inside.

Threads

A thread is one conversation with an agent, working in one folder on your Mac. You say what you want done, the agent does it (reading files, running commands, making changes) and replies. You can have as many threads going as you like, and each one remembers its whole conversation, so you can come back to it days later and carry on.

The list

The threads view has four sections. Inbox holds the threads for you, with the ones that need you at the top. The number on the Threads icon in the left-hand rail is how many are in it. The arrows at the end of its heading sort it newest first or oldest first instead, which is handy for working through a long inbox from the bottom up. Whatever the order, a thread that's stopped mid-turn on a card for you (a password, a question, a permission) stays at the top, as the card closes if nobody answers it. ⌥⌘↓ (Go > Next Inbox Thread) opens the thread below the open one in the Inbox, or the Inbox's first if the open one is somewhere else; past the last one, a note says you're caught up. Once you've clicked the list, the up and down arrows move through the threads, and Esc in the Scheduled, Projects or Librarian view goes back to the Inbox. The list scrolls to keep the open thread's row in sight, whether you got there by the arrows, ⌥⌘↓ or a thread named in a reply. When your threads pass 100, and each thousand after (archived ones count), a note says so once, the next time you're at the app, with a burst of confetti. Running holds threads whose agent is working now, and one you've just sent a message to: while your message still has its spinner (a busy Mac can take a while to pick it up), the thread has already left the Inbox. If the message can't go, it comes back. A thread that asks you something keeps its place in the inbox, wake-up or not, and so does one that has left a job running while it waits for you: a small grey arc turning by its time says the job is still going, and hovering it says what it is. Sub-agents are different: while they're working the thread stays in Running, even if it has asked you something, as what they find can change what it asks. It comes to the inbox when they're done, and you can still open it and answer early. Hibernating and Archived, at the foot, hold the threads that are put away (see Hibernate and archive). They start folded, showing only how many; click a heading to open or fold it. A thread whose agent is waiting on its own work stays under Running too, with a grey spinner and what it's waiting for: on other threads to finish (a fix it needs, a review of its change), for something it's watching for while its commits aren't on main yet ("Waiting to land"), or for your app to restart onto what it landed. Its card says that rather than Done, as the job isn't over until it is. Hibernating also has the threads that have booked a message to themselves for later (an agent saying "I'll check again in 20 minutes") and have nothing for you until then. Each row says when it wakes, soonest first. When the time comes one of these runs again, and lands in the inbox when it's done.

To keep a thread at the very top, star it: hover its row and press the star, or use its right-click or ... menu. Starred threads sit in a Starred section above the Inbox, whatever they're doing, hibernating ones too, in the order you starred them, so they don't jump around. Archiving one moves it to Archived; bring it back and it's starred again.

The search box at the top, beside the New thread button, looks through every thread, the put-away ones too. Type part of a title, or of a thread's last reply, and each section shows only the threads that match, with folded ones opened. It also matches a few search words the librarian gives each thread, so "dentist" finds a thread called "Wisdom tooth meeting location". The x clears it.

What a row tells you

Each row has the thread's title, with its project under it (or its folder, when it's in none). Hover that line to see the last thing you said to it. The tile before the title shows the project too. Your phone's list shows the same line. A title in bold needs you or has a reply you haven't read.

A thread you didn't start has a small mark before its project: a ladybug or other tool symbol for a tool such as Sentry, a clock for a schedule, a pawprint for another thread's agent, books for the librarian. Hover the mark to see who started it and why.

Before the title, in the gap at the left:

  • A blue dot: the thread has finished and is waiting on you, with a reply you haven't read yet. It stays near the top of the inbox.
  • A tick: the thread has finished and said there's nothing needed from you. It shows until you open the thread, so you can see at a glance what got done while you were away.

At the right of the row:

  • Working, with a spinner and a timer: the agent is busy. In the Running section the spinner and timer are enough, so the word is left off.
  • A grey spinner with something like "2 sub-agents": the turn has ended but helpers or jobs it started are still going.
  • The blue dot, with an approval card at the end of the thread and no grey line: a sub-agent is waiting on your answer. It waits as long as it takes, whatever the agent does in the meantime, and carries on when you answer. Stop closes the card and stops that sub-agent.
  • A time: the thread is idle, or the blue dot on the left says it's waiting on you. After a while Threadbear stops an idle thread's agent to save memory, and your next message starts it again where it left off.
  • Failed: the last turn ended with an error. Read the thread to see why, and send a message to try again.
  • Waiting for connection (on the Mac and the iPhone): its turn failed because your internet went. It carries on by itself once the connection is back, so there's no need to tell it to continue. A thread cut off mid-turn because the Mac or Threadbear restarted carries on by itself too, once it's back up.
  • Stopped: the runner restarted while the thread was busy.
  • Waiting for room, with a time: every login it could use has hit its limit (see Accounts, pools and Usage). It carries on by itself when one has room again. A box at the top of the message field says so, with a button to switch to the login with the most room, and Carry on by itself (Yes or No) to have it wait for you instead.

Your messages from the phone app have a small phone beside the words or pictures. Hover or click it to see where the message came from.

Reading a reply

When an agent finishes a piece of work, its reply is the message it writes at the end: what it did and what it found. While it's being written, each new piece fades in as it arrives. Everything it did to get there, its notes, thinking, commands and edits, is one line above the reply, "Worked for 2m 13s": click it to open it. Pictures it made stay out, as they're often the answer. When the agent carries on by itself after that (to check its change once the app restarts, say), the follow-up joins the same line, so there's still one reply to read. When it picks up again because a sub-agent or a background job finished, a thin line between its messages says how long it waited and what finished ("6 min later · Mine the repo finished"). When it needs something from you, a card under the reply asks, and each answer says what happens if you pick it. If you'd rather have a few short bullets in place of the agent's message, ask a thread to turn off One reply ("oneReply": false in runner.json). A link with ↑ after it goes to the step it's about: click it and the work opens there, with that step lit up. A link to another thread opens that thread.

An agent can draw a diagram or a small page in its reply: a ```mermaid block shows as the diagram (drawn with Pele, in Threadbear's colours, light or dark), and an ```html block as the page, each in a box with the language on the left. Its Diagram / Source switch (Preview / Source for a page) flips it to the code, the copy button copies the code, and the arrows open it full size in a window of its own. A diagram that can't be drawn says why above its code. A page is only shown, never run: its scripts are off, it can't reach the internet or your files, and it can't open anything, so only its own styles, SVG and data: pictures appear. Your phone draws them the same way, with the arrows opening it full screen. The new desktop app draws them with Chromium, which it downloads the first time one needs it: the box asks "Show this diagram? It needs the web runtime, a 135 MB download, once." with Install web runtime and Not now, and shows the code until then (or after Not now, until the app restarts). Settings > General > Web runtime says where it's got to and installs it too. If Chromium doesn't start, a web panel and that row say why, with Try again, or Restart Threadbear when only a new run of the app can try again (Chromium starts once per run); the window and what you've typed stay. Its own log is web-runtime.log in the web-runtime folder of Threadbear's data folder.

The installed Mac runner checks the web runtime's CEF pin daily while a runtime is installed. Updates and tb status warn if it is two weeks behind stable, or the check has failed for three days. Bringing in a Threadbear update carries a newer pin when one is available. Chromium's sandbox stays off so the runtime can be downloaded on first use; keep these updates current.

Text an agent writes for you to send somewhere else (a Slack message, an email) comes in a ```slack, ```email or ```draft block. It shows in a box the way it'll go out: every line where the agent put it (the rest of a reply joins single lines up, as Markdown does), and a Slack draft's *bold*, _italic_, ~strike~ and <url|label> links drawn as Slack draws them. Copy, at the box's top right, puts it on the clipboard with its links and bold, so it pastes into Slack or Mail as it looks. The phone and the website show it the same way.

To change a draft before the agent sends it for you, press Edit beside Copy, change the words and press Done (or ⌘Return). The box says "edited" and shows your version, and Undo puts the agent's back. Your version goes on the end of your next message to that thread (an answer on its card counts, from the thread or a project page), with a line asking the agent to use your words, so picking "Post and close" posts what you wrote. The change is kept on your Mac, in the desktop app.

A reply that needs nothing from you ends with a Done card at the top of the message box, with an Archive button to put the thread away. When something it talked about is still worth doing (a piece it didn't get to, a check that's due), the card lists them under "Or carry on". Click any of them to tick them (click again to untick), add anything you like in the message box, and send: the ticked ones go to the agent together, with your words. Not sure what one means? Click the ? at its right to ask; it toggles the same way, so you can ask about several, tick others, and send them all together.

Before you archive, the Done card says what's still open, so you don't have to ask the agent first. Threadbear checks it itself: commits on the thread's worktree branch that aren't on main, files in its worktree that aren't committed (or, for a thread with no worktree of its own, files it changed that aren't committed and commits it made that aren't pushed), work it pushed that isn't on main yet (naming the PR when one is open on GitHub), threads it started that are still working or waiting for you, and a background job it's still running (archiving would stop it). The agent adds the things only it knows, like a reply it's waiting on from someone. They're listed under "Still open": a thread opens from its line, and Land is the chip above the message box. A check-in it booked shows under "Coming back", as the thread comes back by itself when it runs. If nothing is left, the card just says Done, so Archive is safe. It checks again when you open the thread, after an action like Land, and when a thread it started finishes. The phone's and the website's Done cards show the same list, though not for a thread on another Mac.

When the reply does need you, a Needs you card takes its place in the message box, outlined, listing what to do; the same list is near the top of the thread's Highlights, with a box to tick off beside each one. Its heading says what's wanted ("Decisions needed" when every ask has answers to pick). When there are several asks and they'd take a lot of room, the card shows one at a time, with ‹ 1 of 3 › by the heading; picking an answer moves on to the next ask still waiting for one. A long ask scrolls inside the box, so the reply stays in sight. The chevron at the card's top right collapses it to its heading, to read the reply behind it, and brings it back; the next card opens again. Once you reply, the card goes.

To answer a Needs you card, click its buttons: your picks show on the card and go with your next message. A button you pick fills and hops, so you can see the click land. To answer an ask in your own words, click Something else under it and write in the box that opens there. You can paste or drop screenshots in that box too, or use its picture button, and each goes in where the cursor is as a chip, as in the composer. Each ask can have a box of its own. Return in a box takes you on to the next ask that hasn't got an answer yet (a box left empty doesn't count as one; Shift-Return adds a line), and once they all have one it sends the lot as one message, with anything you wrote in the message box at the end. Return in an empty message box does the same with your picks. To send with some left unanswered, press ⌘Return.

When an ask is about pictures the agent put up to compare, its button can open that comparison window straight from the card.

A reply can have buttons partway through it, beside the line they're about, so you can set jobs off as you read without typing: one starts a new thread with a brief the agent wrote ("Fill in the form"), another sends a message to a thread that's already going, and a third opens a panel from another folder's patches beside the thread (the Daily brief's "Go through comments" opens the YouTube panel), as often as you like. Hover over a button to see the brief and where it runs. Nothing happens until you press it, and it only runs once: after that it turns green and opens the thread it started. The agent hears which you pressed with your next message, so a go ahead in your reply doesn't set the same job off twice. It works the same on your phone and the website, except a panel button, which only works on the Mac. A thread without Full access can't make a button that does more than it could itself, and that's checked again when you press it.

On the iPhone, tap Reviews in the thread's top bar, or a review link in a reply. The sheet shows the options, their notes and a still of each picture. Pick any options, None of these, or write a reply, then Send answer. Reference options are there to compare and can't be picked. The thread's Mac has to be on to load the review and take the answer, and it sends the stills only once you open the review, so they can take a moment to turn up. Pages and videos show their still; open the real thing on the Mac. Pictures pasted into an answer on the Mac stay with it, though the phone doesn't show them. This needs your backend on API 86 or newer. If the review changes on the Mac while you're answering, your answer stays in the sheet while it reloads, ready for you to check and send again.

The comparison window starts on the first option's first picture. An option can have several (its overview, how it looks mid-drag, a detail), shown in a strip under the picture. Next and back (or the left and right arrow keys) step through every picture of every option, up and down jump to the option before or after, and after the last one they're all side by side. Click an option on the right, one of its small pictures, or a dot under the stage, to go straight to it, and Open live to try one the agent has running (a web page only). A review from a thread on another Mac opens on that Mac. An agent can show a video or an HTML page in place of a picture: videos play quietly on a loop, side by side when they're all showing, with controls for sound when one is big; a page shows as it does in the side pane, with its scripts off. When the agent includes today's version to compare against, hold Space (or click its button over the picture) to flick to it and back. To look closer at a picture, scroll or pinch over it to zoom in where the pointer is (a long page starts small enough to see whole). Then scroll or drag to move around, or use the small picture in the corner to jump to a part. Pinching out, ⌘0, Esc or a double-click goes back to the whole thing, and ⌘+ and ⌘- zoom too. Tick as many as you like, or None if none of them will do, write what you think in the box at the bottom, and Send takes it all back to the thread. Pasting with the keyboard outside the reply box puts the words in it and moves the cursor there, so you can dictate just after ticking an option.

Short tables in replies stay as wide as their words need. Wide tables fit or scroll inside the reply, and list items have space between their lines.

Inside a thread, rest the pointer on a link for a moment, in a reply or on a Needs you card's buttons, to see where it goes: a picture of the file, or the page's address. On a Mac a local PDF shows its first page and a video its first frame. A PDF over 16 MB or a file that can't be previewed keeps its file symbol. Click it to open it (the middle mouse button works too). A file the side pane can draw opens there: Markdown, text, a page, a picture, a PDF, data and logs (JSON, YAML, TOML, CSV, .log) and code (TypeScript, Python, Rust, shell scripts and the rest), data and code coloured. Anything else opens in its own app, and ⌘-click opens any file there. A path with lines after it, in a link or in a reply's code (server.ts:12 or server.ts:121-125), opens with those lines tinted, marked beside their numbers and scrolled to. If an agent already has that page open in Chrome through BrowserBear (say, a sign-in page it wants you to use), the click brings the agent's tab into your Chrome window rather than opening a second one. A link to a file without its whole path (shorts-plan/candidates.md) is looked for from the thread's folder, as a path in a reply's code is. On the phone and the web, links to files on the Mac only say so. A link that isn't a web page (one that would open Slack, System Settings or another app) asks before it opens, naming the app, on the Mac and the phone, and so does a file that isn't a plain document (a .command, an app, a kind Threadbear can't place). For a kind it can't place, the question names the app it opens in and offers to always open that kind there ("Always open .tandem in Tandem"), so your own apps' files stop asking. To take that back, remove the entry from trustedOpeners in desktop-links.json in the data folder and restart the app. Another Mac's program never opens here, and its replies never show pictures from this Mac.

On a Mac, selected words offer Look Up, Translate, Services and, where the Mac supports it, Writing Tools. The app menu's Services uses the selection in the focused text box, or the selected words in a reply. Passwords and one-time codes stay out of these menus. A Service can replace an unchanged selection in a text box, and Undo restores it. Replies, picture selections, multiple cursors and an active input-method composition are copy-only. Control-Command-D looks up selected words. Writing Tools opens the Mac's native commands, including Show Writing Tools, Proofread and Rewrite.

On Windows, file links and their hover cards only read local drives. A UNC share, mapped network drive or device path is refused, including through a local symbolic link or junction. A local link to another local file works. WSL's \\wsl$ and \\wsl.localhost paths count as shares too. Files on ordinary disk and CD/DVD volumes work; third-party virtual drives such as VeraCrypt and RAM disks are refused until the app can verify them. An open Terminal shell holds off an automatic update restart on Windows: the app cannot yet tell whether PowerShell is waiting or running a command. On Windows, for now, a project's patches only run what you click: their buttons work, but their hooks, worktree setup and teardown, and the commands their panels and badges run don't run, even once you've trusted the patch. A folder's Claude Code hooks and the settings that run commands stay off too. Patches says so beside each patch it affects, and a new worktree's thread says when its setup didn't run. A schedule's check doesn't run in a repo's folder either.

The Browser panel, the globe on a thread's right-hand rail, lists the pages a thread's agents have open through BrowserBear: in the agents' own browser (Helium, in real windows that open behind yours without taking the focus) or in one of your Chrome profiles. Each page has a still of how it looks, what the agent is doing in it, and Show window, which brings its real window to the front. The panel doesn't draw the live page or take clicks for it: you use the page in its own window. An address typed at the top opens a new page in the agents' browser.

When the agent needs you to do something in a page (sign in, approve, pay), handoff brings that page's window to the front. For a page in the agents' browser it also opens this thread's Browser panel, with the page marked Your turn and a Done button, even if the panel was closed; your selected thread stays yours. The agent waits for Done or for the page to settle after your step. Normal browsing by the agent doesn't open the panel.

An agent can also use a separate Chrome with --profile agent. Its pages show in the same panel, with its own sign-ins. When that Chrome asks for a passkey or a permission, its window comes to the middle of your screen and the panel says so, with Show it to bring it to the front. Existing-profile pages use captured frames, so movement is less smooth than the separate Chrome's stream.

A link to a folder opens it in the side pane, where it works like a Finder window. Double-click a folder to go in, or a file to see it there, and the back arrow takes you back to where you were. Press the space bar for Quick Look, or use the path along the bottom to go up. ⌘↑ goes up too, and ⌘⇧. shows hidden files. The button in the bar, or Show as in the right-click menu, swaps the list for icons, with thumbnails of pictures and videos, and the list sorts by whichever column you click. It works for folders on your other Macs too, though only this Mac's files have thumbnails and Quick Look.

On a Mac, Office and iWork documents in the pane show a read-only Quick Look thumbnail. Videos have playback controls and PDFs can be read and scrolled. The thumbnail cannot follow links or run document actions. Open the document in its own app to work on it. Files from another Mac stay on that machine. Documents over 256 MB can be opened in their own app instead.

Files, the folder on a thread's right-hand rail, opens the thread's own folder that way, without a link to it. Click it again to close it.

Code and plain text in the side pane open ready to type in, with line numbers down the side; the check mark in its bar puts the file away to read, and the pencil brings it back. Nothing is written until you type. Lines a link named lose their tint as soon as you do. What you type is saved a moment after you stop, and ⌘S saves it straight away. If the file changes on disk while you have unsaved edits (an agent rewrote it), nothing is written over: a bar asks whether to take the file's version or keep yours.

A Markdown file opens drawn, as a page to read: headings, lists, tables, code and pictures, with the lines kept to a comfortable width. In place of the pencil, a menu in its bar switches between Preview (drawn) and Markdown (the raw text, ready to type in, saved as above), and the next Markdown file you open shows the way you last picked.

An HTML file opens in the side pane as a static page, with the styles, pictures, fonts and media beside it that its markup names. Script files, SVGs and other pages beside it don't load, so a mockup made of several HTML or JS files shows only its main page. It's kept off the internet too, so a font or picture from the web is left out, and its links don't open. A page with scripts of its own opens with them off and a bar over it: Run them turns them on for that page, still kept off the internet, until the file changes, when it asks again. Open the file in your browser to see it with everything. The GPUI app shows these pages with its web runtime: until that's installed, the pane asks for it where the page would be.

To share a file somewhere else, drag it out of the app: a file link in a reply, a picture in the transcript, a file in Highlights, a row in a folder in the side pane, or the picture or video showing there. It drops as the file itself, so you can drag a clip straight into a post on X, or onto the Finder. A web link drags out as its address. To paste a picture instead, right-click it in the side pane and choose Copy Image. The same menu has Show in Finder and Copy Path, as a file link's right-click menu in a reply does.

Full access or Ask before edits

Read this before your first thread. Every thread runs in one of four modes, shown on the composer (the box you type in) and changed by clicking it.

  • Full access: the agent edits files and runs commands without asking. It can do anything your Mac user account can do, in any folder, including deleting files. This is how Threadbear is meant to be used day to day, and it's fine for a folder you trust it with.
  • Ask before edits: the agent stops for your OK before it edits a file or runs a command. A card shows in the thread with Allow, Always allow and Deny. Always allow only lasts for that thread. A Codex thread in this mode can read files but not change them unless you agree. It also asks before it does anything to Threadbear itself: messaging or starting another thread, changing this one, schedules, projects, pins, panels and the Pocket. Reading threads, asking you for a secret and ending its turn never ask. When a Claude agent sends several things that ask at once (say four edits), they come on one card, each with a tick and a cross: Allow lets through the ticked ones and refuses the rest, and Deny all refuses them all. The iPhone shows the first and asks about the rest one at a time.
  • Auto (Claude threads only): a separate safety check approves or blocks each action, and a card shows only when it can't decide. The card says why it couldn't, in the check's own words, and an action it stops outright leaves a note in the thread saying why. It's for work on text you didn't write, like an error report or a web page. It catches a lot but it's no guarantee, and on a Codex thread it behaves like Ask before edits. Before a card reaches you in an Auto thread (the safety check unsure, an edit to a file Threadbear runs as code, a message to a thread with more access, a project's brief), a reviewer looks at it first: Opus, with no tools, shown the card in full and what the thread was asked to do. If it fits the task and can't do real harm, it goes ahead and the thread says "Allowed by the reviewer" with its reason. If the reviewer has doubts, or can't run (no pool, a private folder, a card or brief too long to read whole), the card comes to you after a note with its reason. It treats everything it reads as data, and text trying to tell it what to answer is a reason to hand you the card. Cards that hand out access lasting past the one action (switching a thread to more access, starting a thread with more, a schedule, moving a thread or changing its logins) always come to you, and so do Codex threads' own tool cards.
  • Plan first: the agent looks around and writes a plan, but changes nothing yet. The plan shows as a card with Go ahead and Send back. Go ahead (or Return in an empty message box) lets it start, back in the mode the thread had before. Send back, or just writing what you'd change, has it plan again. Once it's working, the same card ticks off its steps. On the iPhone app the plan shows as a card in the thread: tap it to read the whole plan, copy it, or share it as a Markdown file (Save to Files, Notes, AirDrop). Typing what should change sends it back. Go ahead is on the Mac.

In Ask before edits and Auto, an edit to a file Threadbear runs by itself (a patch, a file a patch uses, or Claude Code's settings) always asks, with no Always allow, and the card says Threadbear runs the file as code. If a patch runs something Threadbear can't follow, every edit asks, and the card says it can't tell whether the file runs as code. The thread then says which patch it is, the command and why, and so does that patch in Patches. Usually it's a command built from something only known as it runs, like node ${script}: write it as plain text, or from constants in the patch (node ${join(import.meta.dirname, 'x.mjs')}), and edits go back to normal. URLs, patterns and prompt text in a patch don't count, only what it runs. Even once you allow it, the patch waits for you to trust it in Patches.

The mode belongs to one thread. On the Mac a new thread starts on the mode you last picked for one, as it does the model (Plan first aside, which is for one task), so if you're unsure about a task, switch it to Ask before edits before you send. Until you've picked one it's your default mode. On a new install the default is Auto; an install from before 9 Nov 2026 keeps Full access. Threads you start from the phone, the website, tb new or a schedule with no mode of its own start on the default. It's "defaults": { "permissionMode": "auto" } in runner.json in the data folder ("full", "ask" or "auto"; none is Full access), so ask any thread to change it. It applies once the runner next restarts. The threads Threadbear starts by itself, to bring in Mike's releases or fix a failed update, start on it too, so on Ask before edits (or Auto on Codex, which asks before edits) they wait for you to allow what they need. Deleting a thread is one thing an agent always has to ask about, whatever the mode.

An agent in Ask before edits or Auto can't give itself more room, with its tools or with tb: tb in a thread signs in with that thread's own key and gets what the thread can do, and anything more is refused with a pointer to the tool that can ask you on a card. Switching any thread or schedule to more access, starting a thread with more access than its own (the threads it starts get its mode), messaging or moving a thread that has more, changing the brief of a project such a thread is in, lowering a thread that has more access, adding a schedule check, or deleting, lowering, moving to another login, model or time zone, or taking the check off a schedule that has one or whose runs have more access all show a card for that one call, with no Always allow. The card shows the whole message or brief, and the folder where it really is. On a Codex thread, Always allow on a command allows that exact command again in that folder, not anything that starts the same way, and it's only offered for simple commands like ls or grep: one that runs the repo's own code (npm test, make, cargo run) asks every time, as the repo can change what it runs.

A card shows the whole command. On the phone, one that's too long to read there in full, one with anything but plain ASCII in it (an accent, an emoji, an invisible or text-reversing character), one asking for more access, or any file edit (the phone shows only its path) has only Deny: allow it in the Threadbear app on the machine the thread runs on (the card names it), which shows every line an edit writes and writes an invisible character out by name (like ⟨U+2028⟩). On a machine with no Threadbear app of its own (none has connected in two weeks), such a card couldn't be allowed anywhere, so it isn't put up: the agent is told to do it another way, and a note in the thread says so.

A thread on another machine shows its real access in the composer (Auto, Ask before edits and so on), or "Access unknown" while that machine runs a Threadbear from before 18 Nov 2026. It can only be changed in the app on that machine.

When an agent needs a password or a key

An agent that needs a secret (your Mac's administrator password for a sudo command, an API key, a token) asks for it in a card in the thread instead of in its reply. Type it into the card and click Save securely, or Decline. You can answer it on your phone too, where it's sealed so only your Mac can read it on the way through. The phone only sends secrets to Macs it learned about from a pairing code, so if it says it doesn't know this Mac yet, answer on the Mac, or pair the phone again from the code in that Mac's Settings > Phone & browser.

It never goes into the chat: the agent gets a private file holding it, which its commands can read for 24 hours, and then it's deleted. That's not the same as hiding it from the agent. A command that prints the file would put it in the transcript, so only give a secret to a thread you'd trust with it.

If a key does end up in a thread's words, Threadbear takes out what it can recognise before the text reaches your phone or the website, which show [REDACTED] there; the Mac keeps every word. It goes by the shapes keys usually have and the values in your .env files, so it won't catch everything, and it can't read pictures. Treat a key that showed up in a thread as leaked and replace it, since the AI provider has seen it too. tb status says what this runner does.

Your first thread

Press ⌘N, or click New thread (the pencil beside the search at the top of the list), type a message and press Return.

New threads start in the ThreadbearThreads folder in your home folder (~/ThreadbearThreads), which setup makes for you. You can pick another folder for one thread from the composer's + menu, or change the default in Settings (⌘,).

A safe first message is one that only reads, such as "What's in this folder?" or "Explain what you can do for me here." When you're ready for it to make something, try "Make a file called hello.txt that says hi" and watch it appear in ~/ThreadbearThreads.

Return sends and Shift-Return (or Option-Return) adds a new line. In a list, Shift-Return starts the next item ("2. " after "1. milk", "- " after "- milk"), and Shift-Return on an empty item ends the list. You can paste or drop images into the composer, or add them with +. Each one goes in where the cursor is as a small chip, "Picture 1", "Picture 2", with its thumbnail, which drops into a strip over your words as the box opens for it, and the agent gets each picture right there in your words. In the new app, + > Attach images or Markdown… also takes .md files: each goes in as its path, as a dropped file does, and the agent reads it from there. Let go of a file over the box's words and it goes in right there. You can also let go of it anywhere else over the thread: the thread's outlined while it'll take it, and the file goes in where the cursor is. A picture or file dragged out of the app itself (a picture in the transcript, a Highlights file) only goes in when you let go over the box, so a drag out that changes its mind doesn't land in your message. So "this one [Picture 1] should look like this one [Picture 2]" says which is which. In the new app, thumbnails wrap to the box's width; after three rows, their strip scrolls so the words stay in view. The thumbnails show over the text too; the cross on one takes it and its chip out. Hover a chip to see its picture, in the composer or once it's sent. Click a chip or a thumbnail, in the composer or in the thread, to open the picture, with the arrows to step through the others. On the Mac, screenshots dragged from the floating thumbnail, pictures dragged from a browser, HEIC pastes and photos copied from Photos work here too. Threadbear keeps image data and temporary screenshots before the source can take them back. It opens and copies ordinary files in the background, showing a loading chip while it waits. Keep those files in place until their pictures finish loading. A picture being copied from another app or fetched from a web URL shows a dim chip while it arrives. Send spins until the picture is ready. If a running thread's draft contains only a loading picture, Stop stays available instead. The Stop keyboard shortcut still works. A web URL is fetched by Threadbear without the browser's cookies or sign-in, using public internet addresses only. For a picture on a local or private-network server, copy the picture itself. Any other file you paste or drop in (a video, a PDF, a folder) goes in as its full path where you drop it, for the agent to open where it is. Nothing's copied, so a big one is fine. On the Mac app it shows as a chip with the file's name and a small dot, which means it isn't uploaded: only an agent on that Mac can open it. Click the chip to open the file.

Paste a thread's id (Copy thread id in its ... menu or its right-click menu in the sidebar), or drag its row from the sidebar onto the open thread, and it goes in as a chip with that thread's title. Dragging a row left still archives it; any other way drags the thread. The agent gets a thread:<id> link it can read the thread from, and clicking the chip once it's sent opens that thread. An id that isn't one of your threads pastes as plain text.

When an agent's reply links another of your threads (one it started, say, or one it's waiting on), a small copy of that thread's tile sits just before the link and shows how it's getting on, changing as it does: a turning ring while it works, an orange dot when it needs you, a red one if it failed, and a tick once it's done. Rest the pointer on it for the words. The Mac app shows these; the phone and the website show the link alone. Stop (⌘.) ends a turn that's running. If you stop before the agent starts reading your message, Threadbear saves it and its pictures and leaves a note under that turn's Worked for line. They go with your next message, including after you switch models or restart Threadbear. Stop on its own doesn't retry them. Clearing the conversation discards them. Moving the thread to another runner keeps the original messages in its history, but you need to send the stopped request again there.

The caret stays visible after ten seconds without editing or moving it, and starts blinking again when you continue typing or refocus the box.

On a Mac the composer checks your spelling as the Mac's own text boxes do. A misspelled word gets a red wavy line once you've finished typing it. Words aren't changed for you: Correct Spelling Automatically is off to start with, whatever your Mac's Keyboard settings say (right-click the box, then Spelling and Grammar, to turn it on). With it on, the Mac's correction goes in as you start the next word, as your text replacements do either way (those start as your Mac's Keyboard settings have them); ⌘Z puts back what you typed. A correction you take back (⌘Z straight after it, or deleting into the word and typing it your way again) isn't made again while the app runs, and the word stops being marked. "Threadbear" is never marked or corrected. Right-click a marked word for the Mac's guesses, Ignore Spelling and Learn Spelling. The same menu has Spelling and Grammar (a green line under grammar, off until you turn it on), Substitutions (smart quotes and dashes, off to start with, and text replacement), Transformations (upper case, lower case or capitalized, for the selection or the word the cursor's in) and Speech, which reads the selection, or the whole message, aloud. Edit > Paste and Match Style (⌥⇧⌘V) pastes only the words, leaving out any picture or file that was copied with them. Windows and Linux have no spell checker here.

A message shows in the thread as soon as you send it, faded, with a spinner beside it until the runner has it (a busy Mac can hold the runner up for a few seconds). A clock instead means it's waiting for the turn that's running to finish, and it starts its own turn then. If it can't be sent, it goes and its text is back in the composer. Starting a new thread keeps your message in the composer, greyed, with a spinner in place of Send, until the thread exists.

Going back to an earlier message

Hover over one of your own messages and click the pencil to change it. Its text goes into the composer; send it and the thread goes back to that point. The agent forgets that message and everything after it, the changes it made to files since then are put back, and your new version is sent as if the rest had never happened. A turn that's running is stopped first. What was cut is gone from the thread, and a line where it was says how many files were put back.

Going back stops anything the agent left running in the background (an upload, a long build), even if it started it before the message you're changing. When something is, the app asks first and says what: Cancel keeps it running, and you can send your change as a new message instead.

Files changed by commands the agent ran (a script, git, npm install) aren't put back, only ones it edited or wrote itself. If you've changed one of its files yourself since, that file may be left as it is, and the line says so. A message you sent while the agent was working went into that turn, so edit the message that started it instead.

Slash commands

A message that starts with a command, like /compact, runs it rather than going to the agent as words. In a Claude thread Claude Code runs its own commands and your skills (/compact, /context, /cost, /clear, /code-review). A Codex thread runs /compact, /review (the uncommitted changes, or what you write after it), /clear or /new, /status, and / with the name of one of your Codex skills.

Two are Threadbear's own, on both: /model and /effort change the thread's model and effort level, the same as the menus under the message box, so the change sticks. On their own they say what the thread is on and what you can pick. /clear starts the agent on a fresh session; the transcript above stays for you to read.

Type / in a thread's message box, a new thread's included, and a palette opens above it with every command the thread can run: Threadbear's, the CLI's and your skills, with Recent for the ones you picked lately. What you type narrows it, and the one picked is described on the right: how to use it, its other names, what /model and /effort are set to now, and where it comes from (yours, this folder's, a plugin's) with its file and an Open button that shows the file beside the thread. Up and Down move, Return runs it, Tab puts it in the box so you can type its details after it, and Esc closes the palette. Clicking a category shows only those; double-clicking a command runs it. Drag the palette's top edge or sides to make it bigger or smaller (the border lights up where it will drag), as wide as the window, and the lines between its columns to size them. It keeps the sizes for next time. Right-click it for its default size or column widths, or double-click a line to put that column back.

Type / partway through a message ("then use /td") and the palette lists the skills the agent can run when it reads one named there. Return or Tab puts the skill in your words, and nothing is sent until you send the message. Claude Code's own commands, and skills set to run only when you type them (disable-model-invocation: true), work only at the start of a message, so they aren't listed there.

The iPhone app has it too: type / in a thread's reply box and a list of its commands opens above it, with the categories as buttons along the top. Tap one to put it in the box, then send it (add details first if it takes any). It comes from the thread's Mac, so with that Mac asleep it says so, and a command typed in full still runs.

A command waits for a running turn to finish rather than going into it. Commands that only make sense in a CLI's terminal (/resume, /rewind, /login) get a line saying how to do that here. Anything else starting with a slash, such as a file path, goes to the agent as words.

Hibernate and archive

To put a thread away for a while, hibernate it: hover its row and press the moon, or use the Thread menu or the ... menu. Pick when it should come back: in an hour, this evening, tomorrow, next Monday, or a day on a calendar and a time of your own. It leaves the list, its agent stops, and it comes back marked unread when the time comes. Its row says Woke up until you open it, and the thread says how long it was away, beside a bear that's only just got up. Hibernating threads wait in the Hibernating section at the foot of the list, soonest to wake first. Hibernate the thread you have open and its page sinks into the moon on that heading as the next thread comes in.

Or pick Wake when… and say it in your own words: "at the weekend", "in a few weeks", "next time I talk about woodworking". Opus works out what you meant (the row says Thinking… for a few seconds) and the thread says what it settled on. A topic waits for you to bring it up: when the librarian sees you talking about it in another thread, it wakes this one and says where.

When a thread is done, archive it: press ⌘E, hover its row and press the box, or swipe the row left with two fingers on the trackpad (right with natural scrolling off), or drag it left with the mouse, and let go once the space behind it turns blue (a quick flick works too). However it's archived (⌘E, a button, or an agent or your phone doing it), its row slides off the same way. Archive the thread you have open and its page drops into the Archived heading as the next thread comes in. If it was the last one in the Inbox (archived or hibernated), confetti pops from the empty Inbox. When you archive one, a note saying so floats at the top of the thread panel for a few seconds (longer while the pointer's on it): Undo puts the thread back, and a click anywhere else on it opens the thread. Its x, or a sideways two-finger swipe on it, puts the note away early. In the desktop app on a Mac, ⌘Z brings back the last thread you archived, then the one before, up to seven, even after the note has gone. It works outside a text box or in an empty message box; while there's typing in the box to undo (words, or ones you've just cleared), ⌘Z undoes that first. The Archived section at the foot of the list has them, most recently archived first, with the older ones behind Show more (the search at the top finds any of them). Unarchive, or the same swipe there, puts one back. To get rid of one for good, hover it there and click the trash, or right-click it and choose Delete…; after you confirm, it goes to the runner's trash folder, with no Undo in the app.

A thread another thread's agent started archives itself when it finishes with nothing left for you: nothing asked, no follow-ups suggested, nothing uncommitted, unlanded or unmerged, no background job running and no check-in booked. If threads it started itself are still going, it waits for them first. A note in the thread says why it went, and it shows as archived under "Threads it started" in the Highlights of the thread that started it. It stays in the inbox if you've written in it, starred it or brought it back out of the archive, and so does one that failed or was stopped. Threads you started, and ones a tool or a schedule started, never archive this way.

Back and Forward (⌘[ and ⌘], in the Go menu, or the ‹ and › beside the share icon at the top right of a thread) step through the threads and pages you've had open, as a browser does. Hover either arrow to see which thread it goes to. A mouse's side buttons do the same, and so does a trackpad swipe, as in Safari: with natural scrolling right for Back and left for Forward, and the other way round without it. A card in the middle of the window says which thread or page you'll land on, and fills the way your fingers go, turning blue once letting go will go. With nowhere to go that way, it says so. A swipe that starts mostly up or down is a scroll, so a long thread still scrolls. It follows Swipe between pages in System Settings > Trackpad (two or three fingers). Over a thread's row a swipe left still archives it. A thread you start takes the place of the new-thread screen, so Back from it goes to wherever you were before you pressed New thread.

Hibernating or archiving a thread that's partway through a turn stops that turn. It also stops any background jobs that thread's agent left running, including shell jobs waiting their turn in a queue. From the row's hover buttons, Threadbear asks first. A scheduled message can bring the agent back later, but it does not keep those jobs alive. To let a job finish, leave its thread awake; the agent can end its reply while the job carries on. An agent that only needs to wait for something (a merge, CI, another thread) is stopped from doing it with a background job, and uses a scheduled check instead, so its thread can still hibernate.

You can also ask a thread to do it to itself ("hibernate this until Thursday", "archive this when you're done"). It finishes its reply first, then goes, with a note in the thread saying when it'll be back. A time works, or words like "until the phone arrives", read the same way as Wake when…. When the words are something to happen ("until the GPUI app replaces the Swift app"), the librarian wakes it once another thread shows it has, not just when it's talked about, and the thread gets a turn to check for itself: if it hasn't really happened, it goes back to sleep. It won't put itself away while it's waiting on you. A thread whose next step waits on other threads hibernates by itself until they finish, then wakes with what they said and carries on; its row says Waiting on and which. If it was given more access while it slept, and one of them has less, it wakes for you instead, with a note, and what they said isn't passed on until you send a message. It can also say what it's waiting for a thread to do ("until it reports the I/O saving"), and then the librarian reads that thread after each of its turns and wakes it once it has. On the iPhone and the website a hibernating row starts "Until …" when it waits for more than a time. A thread can also hibernate until the runner updates to a new release (a restart on the same one leaves it asleep). One that has landed a change to the app and is waiting to check it hibernates by itself when it's done for now, and wakes once the app has restarted onto a build with the change. One waiting on a job that will message it does the same until the message comes. Either way it has a time it comes back anyway, a day unless it says otherwise.

Panels

The window is made of panels you can move around: the list of threads, the thread you're reading, Highlights, a project's panels, Patches, and the ones you open from the left-hand rail, such as Usage and Updates. Each panel has a bar along its top with its title, and panels that share a space show as tabs in it. To begin with there are three side by side: the list, the thread and Highlights. Highlights, Files, Patches and a project's panels each show their own content wherever they are, so you can keep Files open beside Highlights; a file opened from one opens over that one.

To move a panel, press and hold on it for a moment, then drag. That works on its title, one of its tabs or the empty part of its bar, and on its background too if you turn on Settings > General > Move panels by their background (a panel with its title hidden always moves from its background). On a title or tab a plain drag works too. A quick drag on the empty part of a bar moves the whole window instead, as there's no title bar, and a double-click there zooms it. While you drag, the panel shrinks under the pointer and shows where it will go when you let go:

  • Over another panel's bar, a tab with its name shows there: let go to add it as a tab.
  • Near one side of another panel, that side lights up: let go to split that panel's space in half.
  • In the middle of another panel, a compass shows. Drop on one of its arrows to dock above, below, left or right of it, in the middle to add it as a tab, on Swap to change places, or on Window to give it a window of its own.
  • Along the window's own edge, it docks across that whole side.
  • Past the edge of the window, it opens in a window of its own. Right-click a panel's title for Open in New Window too, and Put Back in Main Window to bring it home.

Escape, or letting go anywhere else, puts it back where it was. Drag the line between two panels to resize them, and click × on a tab to close it. Right-click a title for Hide Title, which leaves the panel without a bar while it's on its own; a thin strip along its top still lets you drag it.

The icons down the right edge of the window open and close the thread's own panels: Highlights at the top, one for each panel its patches add, and Patches at the foot. To open a thread in a panel of its own, beside the one you're reading, right-click it in the list and pick Open in New Panel. The × at the end of its title bar closes it, and Move to Main Panel, on the same right-click menu, brings it back to the main panel.

A patch's panel follows the thread you pick, and steps aside for a thread that doesn't have it. To keep one in view while you work in another thread (one project's Convex dashboard while you're in another project's thread, say), right-click its tab and choose Pin. It stays where it is, with a pin on its tab, showing the thread it was pinned from whichever thread you pick; hover over the tab to see which. That thread's button on the rail brings it to the front. Unpin, on the same menu, puts the ordinary panel back. Pinned panels are in the new desktop app only.

The View menu has the rest: Show or Hide Threads (⌃⌘S) for the list, Collapse or Expand Threads (⌘/), which folds the list away while the bar of icons on the left stays, gives its room to the thread, and brings it back at the same width (clicking Threads, Scheduled, Projects or Librarian in that bar brings it back too), Show or Hide Panels (⌥⌘P) for the panels beside the thread, Show or Hide Terminal (⌘J), and Reset Panel Layout, which puts everything back how it started. Threadbear remembers your layout between launches.

Terminal

⌘J opens a terminal under the thread, and ⌘J again hides it. It's a real one, with your login shell, its colours and full-screen programs like vim or htop, and it takes the keyboard as it opens. Each thread has a shell of its own, started in the thread's folder (its worktree, when it has one), and it keeps running while you look at other threads, so going back finds it as you left it. A thread on another Mac or the cloud gets a shell on this Mac in your home folder, with a line saying so, and so do an archived thread (its worktree may be another thread's by now) and the new-thread page. If the shell exits, New Shell starts another. A shell only starts when you ask for one, with ⌘J, a click on the empty panel or a command's play icon (below), so looking through threads with it open starts nothing. A thread's shell stops when the thread is archived or deleted, and they all stop when you quit Threadbear. The Terminal is a panel like the others: drag it beside the thread, into a tab, or out into a window of its own.

⌘-click a web address, a file path or a labelled link printed in the Terminal to open it (Ctrl-click on Windows and Linux). Programs and links that start another app ask first, as they do elsewhere in Threadbear.

A shell command an agent gives you (a ```bash, sh, zsh or shell block) has a play icon and a copy icon at its top right. Play opens the Terminal with the command typed at the prompt and the keyboard there, and you press Return, so you see it before it runs. Pressing play on another block while one is still waiting copies it instead, so run or clear the first. If something is already running in that shell (or the shell has become another program, as exec ssh does), or you've typed on its prompt, nothing gets added: the command goes on the clipboard and a bubble says so (a shell without bracketed paste, like macOS's old bash, always copies). Pasting lines (or a Tab) into a shell like that asks first, as each line would run as soon as it arrived. A paste leaves out control characters (anything but Tab and line breaks), so copied text with a hidden one in it can't run itself. Play isn't there on a thread on another Mac or the cloud, or an archived one, as this Mac's shell wouldn't be in the right place; Copy still is. Nor is it on a thread open in a panel of its own, as the Terminal shows the main panel's thread's shell: open the thread in the main panel to use it. It's on the Mac app only. A block with control or invisible characters in it has no play icon.

A link in the Terminal (one a program prints, or a path you click) opens the way a link in a reply does: a web page in your browser, a document in its app, and anything that would run something, or start another app, only once you've said yes.

Highlights

Highlights is the panel beside the thread that collects what the thread has made and shared, so you can find it without scrolling back through the conversation. It fills in by itself as the agent works. Its icon is the pin at the top of the right-hand edge, which gets a dot while the last reply has things for you to do.

From the top, and only when there's something to show:

  • A line or two from the librarian on where the thread is up to.
  • Needs you: what the agent's last reply asked you to do, each with a box to tick off as you go. Ticking one here ticks it in the thread too.
  • The thread's projects, each under its icon and name with its links, such as a live site or an admin page, and its task board if it has one (see Projects). The ⓘ beside a project's name says who put the thread there and why ("Shortlists photos for the calendar entry"). If the librarian guessed wrong, press Take out there and it won't put it back; Keep stops it ever taking the thread out. The librarian also renames a project whose name has gone out of date (a tool it's about was renamed, say), but never one you named or renamed yourself.
  • Scheduled: messages booked to come to this thread. Click one to change it.
  • Sub-agents: helpers the agent started, with how each is getting on. Click one to read what it did.
  • Threads it started: other threads its agent started, and any it's waiting on, each with where it's up to: the ones that need you first, then failed, working, hibernating, done and archived. Click one to open it. Their questions still come to your inbox like any thread's.
  • Pinned: what the agent pinned for you (below).
  • Files: documents, pages, pictures and videos the thread wrote, opened or mentioned, each with a small preview: the picture itself, a frame of a video or a PDF's first page, or a document's first lines. Dotfiles, hidden folders in your home folder (~/.convex, ~/.ssh) and files named like they hold a key show their icon instead, as the previews are on screen whenever Highlights is. Another Mac's files show their icon.
  • Links: web pages and pull requests it opened or mentioned.
  • Changes: its commits, and a line such as "4 files edited" that opens to the code it changed.

Click a heading to fold that section away, and again to bring it back. A folded heading shows how many rows it's hiding. Threadbear remembers what you've folded, between launches and for every thread: fold Sub-agents once and it stays folded everywhere. A project's heading folds for that project.

Click a file and it opens in the panel, with Back to return to the list (code and text open there ready to type in). A link opens in your browser, unless you change Default in its right-click menu to open pages in the panel. A Tandem project opens in Tandem, here and in a reply. Right-click any of them for more, such as Reveal in Finder, or Remove to take it off the list. You can drag files out of Highlights into other apps.

Pins

An agent can pin a file or link to Highlights, under Pinned, with its pin tool and a short note on why you should look at it: a mockup it made for you to check, a preview address, a pull request. It can also open the pin in the panel beside the thread: straight away if you're looking at that thread, or else when you next open it. Files it writes and links it mentions show up by themselves, so pins are for the few things that matter most. To have something pinned, ask the thread ("pin the mockup for me").

Projects

When a project update needs your approval, its details show the current project name and ID alongside the proposed changes.

A project gathers the threads about one thing, whatever folder they ran in: an app you're building, a trip, a house move. Each has goals, a few lines on where it's up to, notes for later threads (decisions and gotchas), links (its live site, an admin page) and folders, the repos its work lives in. The Projects view lists them, with New project at the top; click one for its page, with its threads, state and notes. The search at the top of the Projects page looks through their names, state, goals, notes and folders: Return opens the top result and Escape clears it.

To start a thread in a project, press New Thread at the top of its page (or New thread… by its Threads). The message box opens with the project's folder picked and an "In" chip naming the project (its x starts the thread outside it instead). The thread is in the project from its first message, so its agent starts with the project's goals, state and notes; it shows in your Inbox like any other, and under the project's Threads.

A thread also gets into a project when the librarian files it (below), when its agent joins one, or when you put it there, from Projects in its right-click menu. A thread can be in more than one. Its agent is told a little about each project it's in, and gets the panels and Patches from the projects' folders. If one is wrong, Take out in its Highlights keeps it out for good.

A project can be a part of a bigger one, for one body of work with separate strands: an app, its desktop port and its Android version, each with its own goals, state and notes. Right-click a project in Projects (or use the ... menu on its page) and pick Make a Part of, then the project it belongs to; Make Its Own Project undoes it. A part sits under its parent in the Projects view and inside its card on the Projects page, and the parent's page lists its parts. A thread in a part is told the parent's goals as well as the part's own; a thread in the parent is told which parts there are. One level only: a part can't have parts. Agents can do the same with update_project. The phone and the website list parts as projects of their own for now.

A project can show a task board from Notion. Give it a Notion page with a Tasks database on it (a board grouped by Status): Add Notion page… under Tasks on its page, Notion Page… when you right-click it in Projects, or ask an agent to. The page shows the board, read every few minutes, with a column per status and who and when on each card. Cards are moved in Notion, by you, anyone you share the page with, or the agents, who see the open cards and are told to keep them moving. A card whose Thread column names a thread links to it. A thread's Highlights shows each of its projects' boards too, under the project: what's under way first, then what's to do, with Done folded to a strip you can click open. If the columns don't fit, drag the bar under them, use its arrows, or scroll sideways, or drag the panel wider. Click a card to mention it in your message: it shows as a chip with the card's title, and the agent gets a link it can read the card from. Mentioning the same card again keeps one copy in the draft. Each column starts with four cards; More and Show fewer change how many are shown. Click the chip in a sent message to open the card; the arrow on a card, or its right-click menu, opens it in Notion. The menu also offers Copy Link and, when another thread is working on the card, Open the Thread Working on It. Boards are read through a Connectors gateway (see Connectors); without one, the project's page says so and nothing is read.

The librarian

The librarian reads your threads as they go and keeps your projects tidy. It files each thread in a project, making one when none fits, keeps each project's state up to date, adds a repo to a project's folders once its threads work there, and renames threads that have wandered off from their title (never one you named). It also looks after the Pocket cards threads filed. Its picture, and the one on the Scheduled page, say something if you poke them.

It looks after a thread's first message and when a turn ends, then catches up at most every 20 minutes while the thread keeps going. A catch-up after only a quick reply is skipped without asking anything.

Each look is one short call to Haiku, Claude's small, cheap model, rather than the model your threads run on. When it wants to file a thread in a project the thread hasn't touched the folders of, one more short call, to Opus, checks the thread is really working on that project and doesn't just share a subject with it. They run on one of your own Claude logins: the one the pool would pick next in the pool chosen under Runs on (the same pool that writes thread titles, also in Settings › Models), and they count towards that login's usage like any other call. When every login in the pool is out of room it waits, and with only Codex logins it doesn't run at all. Threads in a private folder (Settings › Models) are never sent to it.

The Librarian view lists what it did and what it will look at next. Click a project name in its log to open that project's page. Hover a row to see why it filed a thread where it did. Turn off Look at threads there to pause it; what's queued waits until you turn it back on. If it files a thread wrongly, take the thread out of the project and it won't put it back.

Schedules

A schedule sends a message at a set time, once or over and over: to a thread, or to a new thread each time (a morning summary, say). Make one in the Scheduled view (⌘2), or ask an agent ("look at this again every weekday at 9"). The Scheduled view lists them under Active, Paused and Done, with when each runs next. One that starts a new thread each time keeps the pool the composer was on when you made it, so each run starts on whichever of that pool's logins it would pick then; ask an agent to put it on another pool or one login. Its model and effort start as the composer's too, and you can change them in the schedule's editor (click it in the list). Click a heading to fold it away (Done starts folded); a folded one shows how many are under it. Its page says what's coming up next with a few numbers: how many are on, due in the next day, repeating, set by threads, paused, and how often they've run.

With Convex sync on, schedules need a connection to your backend. If the first connection fails after a restart, the runner tries again after a second, then waits longer between attempts, up to a minute. Try saving again once the connection is back.

A schedule's message brings an archived thread out of the archive while it runs. If the run ends with nothing for you, the thread goes back into the archive, so a watcher you've put away only lands in your inbox when it has something you need to act on.

A reminder due while an agent is working waits until that turn ends. A newer run from the same schedule replaces its older queued reminder, so repeated check-ins don't pile up. Your messages and other threads' messages can still reach the agent while the reminder waits. Repeated Run now requests also replace a pending reminder from that schedule. Runner notifications also wait behind your messages and other threads' messages. If the agent answers a later message by archiving or hibernating the thread, older queued reminders wait with it. They don't start another turn immediately. New inputs arriving after the agent receives that later message still need handling.

Pausing, deleting or editing a schedule doesn't take back a reminder already queued. Ordinary messages go ahead of reminders. Reminders carrying check output are kept separately so new items found by a check aren't lost.

If an update leaves a thread on the old runner while a command finishes, its scheduled messages can still start turns there. An old runner from before this feature was added may have to finish moving the thread before its next scheduled message arrives.

A schedule can have a check: a shell command that runs first, in its folder, each time it's due. If the check prints nothing, that run is skipped and no agent starts, so a schedule that looks for new Sentry issues every five minutes only uses a login when there's something to look at. What it prints is added to the message. If the check itself fails, the run goes ahead with the error, so you hear about it. A check has a minute to finish, or up to five if its schedule says so, for one that reads something slow like Slack. What a check prints is kept until a run carrying it has been sent, so a runner restart in between doesn't lose it. A runner update keeps the check in its thread's folder; during handover, it waits until that folder is known. Ask a thread to "only run when there's something new" and it writes the check. Run now skips it. It's bound to what it runs: if a script it reaches changes, or you move the schedule to another folder, it doesn't run until the same check is passed to the schedule again (ask a thread to pass it), and the thread is told once. Changing a schedule's words, time or folder in the app never approves its check.

If you run Threadbear on more than one Mac (or on a Linux server as well, INSTALL.md section 6), a schedule that starts a new thread can run on any of them: pick the Mac under Runs on. A new thread can too: Runs on under the box lists the Macs, and its Folder lists that Mac's folders, with Other… to type a full path there. It runs there even while this one is asleep, in that Mac's folder (leave the folder empty for its default). Its threads show on your phone and the website, and threads made on another Mac show in your sidebar too, with that Mac's icon in the row. Open one and this Mac reads it from your Convex backend and sends what you do there (messages, approvals, Stop, archive) for that Mac to pick up, the way your phone does, so there's no network link between the two Macs to set up. Pictures you paste into a message, or into a new thread there, go with it (up to 6, 10 MB each), held in Convex only until that Mac has fetched them. You see its messages, with the pictures pasted into them, and a line for each tool it used; the tool output, diffs and tools' pictures stay on that Mac for now, and a tool row says so. A pasted picture shows a moment after its message, once that Mac has sent it up (not at all with "sync": { "pastedPictures": false } there, or for one over 10 MB). Editing a message, its highlights and patches, and changing its login or model are done on that Mac. Agents see them the same way: list_threads lists and searches them (each row says which Mac), read_thread reads them, send_message messages them, and they can stop, snooze or archive them. A Mac that's off shows its threads but can't take a message until it's back. Its archived threads are in your Archived list with the rest, to reopen or unarchive. To add a Mac, give it a key of its own from this one: tb runner add <name> --ssh <that Mac> writes it there, and its runner uses it from its next restart. Set that Mac up with ./threadbear setup --existing, which leaves out the Convex login and deploy key (either could do anything to your backend) and ends by telling you to run that command, with that Mac's <user>@<name>.local. It needs Remote Login on there (System Settings > General > Sharing; setup says if it's off), and ssh from this Mac that asks nothing: trust its host key once by hand (setup says how to check its fingerprint) and ssh-copy-id it if it wants a password. If ssh fails, tb runner add says which of those it was. tb runner check there says if an older setup or an earlier npx convex login left a deploy key or Convex login behind. Revoke and remove them, then rotate the main key unless that Mac has only just joined, never had the main key and has run no threads yet. That key only reaches its own Mac's threads, schedules and Pocket cards: it can't pair a phone or put a schedule on another Mac, and that Mac's app doesn't list the other Macs' threads. Only the first Mac's key can. A new thread from your phone goes to your first Mac, and waits for it while it's asleep, unless you pick another Mac for it. Notifications from another Mac's threads start with that Mac's name. After moving a Mac onto its own key, tb runner rotate-owner on your first Mac changes the main key (it won't while another runner it has seen lately is still on the main key: it names each one with the tb runner add that gives it its own, or --lock-out cuts it off on purpose), and tb runner audit lists the phone tokens, schedules, cards and messages the old one could have made, to take out any you don't recognise. An agent on one of those other Macs can still ask for a thread on this one (to try something only your Mac can, say): a card in its thread shows who's asking, the folder, its access and the whole brief, and Start it starts it here, from this Mac. Answer it in the Mac app; the phone shows it but can't start it. The agent can't see this Mac's folders, so a guess like /home/mike/x or /Users/mike/x starts in x under your home here if that's a folder; if no such folder is here, the card says so, and Start it sends the request back for the agent to ask again with one that is. The new thread is told which thread asked, and can message it back. Agents on this Mac start threads on the other Macs without asking, and each reply such a thread ends a turn with comes back to the thread that started it as a message (the other Macs can't message this one's threads themselves). To start a thread on another Mac, pick it with the machine chip on the composer: the folder, account and model are then that Mac's. New threads start on the starred one: change it under Default in that chip's menu, or in Settings > Runners, which also lists your runners and whether they're online, in your order: drag one to change it. The phone has the same order, and a new thread from it starts on the first runner that's online in it. Adding or renaming a runner is done on its own machine, so ask an agent to do it for you. Schedules need your Convex backend: with no internet, they wait.

With the virtualRunners experiment on and a virtual runner set up in your backend (docs/virtual-runners.md), Runs on also lists it after the Macs, for example "Cloud (Fly)": the thread gets a machine of its own in the cloud, made from the folder's git repo on this Mac and your Claude login. Its row says "Starting a machine" while it boots, "Asleep" once it's been idle a while, and "Waking" when a message brings it back. The first time a login runs there, the thread asks for a cloud token in a card on its message box: Make one runs claude setup-token for that login and opens claude.ai to approve it (not on Windows, where you run it in a terminal and paste what it prints), Paste a token takes one you made, and Use this Mac's token appears when that login already has a year-long token here. The message waits and goes once it's set. If Claude later refuses the token, the same card comes back.

With more than one runner, Runners (the rack icon near the bottom of the left-hand rail) opens a panel with each one: whether it's online and for how long, or when it was last heard from, the commit it runs, and the threads running there, which open with a click. A grey dot on the icon means one is offline or updating. Click a runner's name to see its CPU, memory and disk, what machine it is and how long that machine has been up. A bar turns orange when memory is 90% used or disk is under 10 GB free. The figures come every 10 seconds while the details are open and the window can be seen; a runner too old to send them says so. The runners are in your order, the same as in Settings > Runners and on the phone: drag one to change it.

A thread can move to another of your machines whole: the same thread, with its whole conversation, its pictures and Highlights, and the git work in its own worktree (commits and uncommitted changes alike). Once you have more than one machine, the machine a thread is on shows under its message box, by name; click it and pick Move to a machine. You can also right-click the thread (or use its ... menu) and pick Move to, then the machine. Offline ones are greyed. While it moves, the machine chip spins and its menu offers Cancel Move. It waits for the turn it's on to end, and its message box and any open card are locked until it lands or you cancel; a message sent from your phone meanwhile goes with it. It goes straight away, to the folder and login that machine guesses. If it can't go, something won't come (background jobs, changes in a checkout other threads share), or that machine has no copy of the repo and would clone it (it says from where and to where), a small window shows the folder and login with why; change either and press Return to check again (pressing Move after a change checks it too, and shows what it found), then press Move. The machine it goes to picks the folder: its own copy of the repo, a new clone beside one of its repos, or the same folder in its home, never anywhere else, and never its home itself, a hidden folder or one tools load from, such as ~/Library or a node_modules, unless you type it in. A machine whose Threadbear is from before moves were checked this way says so and takes no move until it updates. If the thread or where it would go changes between that look and the move, it stays where it is and says so: move it again. The row says "Moving to" with a spinner, and the message box stays locked, until the other machine has it (a moment after it leaves the first), then the thread is listed under the other machine, in the same place and still open, and its next message carries on in the same Claude session there. If anything goes wrong before it lands, it stays where it was: the bar at the top of the window says where it was going and why, and the row says "Couldn't move" for a minute. Its schedules come too, but not a schedule's shell check or the thread's "Always allow" answers: set those again on the new machine. A thread moved to your main Mac arrives asking before tools run, even if it had Full access or Auto there. Agents can do the same with move_thread and a runner, and tb move <thread> --to <machine> (--preview to see where it would go). Moves are started from your first Mac and need Threadbear's backend.

Accounts, pools and Usage

Threadbear uses the Claude Code and Codex logins already on your Mac: the Claude Code login in ~/.claude and the Codex login in ~/.codex. It never reads their passwords or tokens. The account and model a thread runs on are small menus on the composer. Whatever you picked last is what the next thread starts on.

Once a thread has run a turn, a small ring beside the send button shows how full its context is: how much of the model's window the conversation takes up. It turns orange when it's nearly full, as Claude and Codex compact the conversation by themselves soon after. Click it for the tokens used out of the window, the model and login the thread really ran on, and what it has cost so far. On a Claude thread it also shows what fills the context, as Claude's /context counts it: the conversation, memory files, skills, tools, the system prompt, MCP servers, the room Claude keeps for compacting and what's free, with the tool definitions it loads only when needed listed below. Claude is asked when you open it and when you click its refresh button. Once a thread has sat idle for half an hour its Claude has stopped, so it shows the last breakdown and how old it is until your next message.

A Claude thread keeps its conversation in the provider's prompt cache for about an hour after its last model call. Wake a long thread after that (your message the next morning, a schedule, a report from a thread it started) and the whole conversation has to be read in again, which on a thread past 200k tokens costs about three times a warm turn. So a Claude thread with 200k tokens or more of context that has been idle for over an hour and five minutes compacts first: Claude Code summarises the conversation, asked to keep what was decided, what you asked for that isn't done, what's still running or waited on, the files, branches and threads involved, and how you said you want the work done. Then your message runs on the summary, in the same turn. It takes a minute or so before the turn starts, and a quiet line in the thread says it happened and why. A thread that's still warm, a shorter one, a slash command and Codex threads are left alone.

To add another login, such as a second Claude subscription, give it a folder of its own under accounts in Threadbear's data folder, named claude-1 (then claude-2 and so on, or codex-1 for Codex), and sign in there in Terminal:

CLAUDE_CONFIG_DIR=~/Library/Application\ Support/Threadbear/accounts/claude-1 claude

then type /login (for Codex, CODEX_HOME=<the folder> codex login). It shows up in the account menu within a few seconds.

To drop a login you no longer use, such as one whose plan has lapsed, add its id to hiddenLogins in runner.json ("hiddenLogins": ["claude-main"]) and restart the runner. It goes from the Usage panel and the account menu, and its sign-in stops putting a dot on the Usage button. Take it out of any pool first.

If a login stops working (you signed out, or its sign-in ended), the thread's turn fails and a line above its messages says so, naming the login and its email ("claude-1 (you@example.com) is signed out."). Sign in… opens Terminal on that login's own sign-in, and Send again sends your last message again once you're done. A thread in a pool doesn't wait for you: it moves to another login in the pool and carries on, and the pool leaves the signed-out login alone until you sign it back in. A schedule pinned to a signed-out login runs on another login in a pool that login is in, and its thread says which. If no pool has another login for it (a login kept apart for work, say), the run fails once with the sign-in line, and later runs wait, rather than adding a failed thread each day, until you sign it in or archive that thread.

From Claude Code 2.1.325 a Claude sign-in only lasts 28 days and can't be renewed by itself. Three days before one ends, its row in the Usage panel says "Sign-in ends" with the day, the Usage button gets a dot, and its tooltip names the login; a signed-out login shows "Signed out" there. Either way the row has Sign in…, so a scheduled job on that login doesn't fail overnight. Once it's signed back in, confetti pops from its row (or from the thread's sign-in line) if you're looking at it. Threadbear learns this from each login's own claude auth status. For a thread on another Mac the line says which Mac to sign in on, as Terminal here would only sign in this Mac.

To stop signing in every month, a Claude login's row in Usage has Year-long token…. It opens Terminal on claude setup-token for that login: sign in once, and from then on the login runs on a token that lasts a year. Threadbear keeps it in a file in that login's own folder (threadbear-token.json, which only you can read) and gives it to that login's Claude Code and nothing else. The row then says "Year-long token until" the day, with a burst of confetti if Usage is open, and three days before that it warns as a sign-in does, with New token…. A token can only run models, so claude.ai's own connectors and Remote Control don't work on that login; MCP servers you set up yourself still do, and so do the usage numbers. To go back to signing in, delete that file.

A login on another of your machines (a second Mac, a Linux box, a Windows PC) gets one from the Runners panel: open that machine's card, and its Claude logins are listed under its figures, each with Year-long token…. Your browser opens on claude.ai's page for it; click Authorize, then Copy code on the page it ends on, and Paste code back in the panel. That machine makes the token and keeps it, and it never leaves there. It needs python3 on that machine, and your main Mac's app (it goes through your Convex backend).

The sign-in command comes from the runner's provider list, so Cursor opens agent login, for example. Sign in… is offered only when the login's own details can be read.

A Claude login whose paid plan has run out (it's back on the free plan, which has no Claude Code) shows faded with "Plan ended" in the Usage panel, with no numbers, reset or Sign in…, and pools pass it over. Threadbear learns this from the plan the CLI last saw for that login, which it checks about once a day while it runs there. If a runner sends an unreadable thread field or row, readable threads still appear. An empty or partly unreadable local list keeps the previous rows and their Terminal shells until a complete list arrives.

If Claude stops with a safeguards refusal, a small box above the message field offers Continue with Codex Sol, when Sol is available on a Codex login with room. Clicking it moves this thread to GPT-6.1-Sol and asks it to continue, with the conversation carried across. It pins the thread to that Codex login. Anything you've typed in the message field stays there. The switch happens only when you click.

OpenCode, Cursor and Grok, and other agent CLIs that speak the Agent Client Protocol, get threads of their own too. If one is installed and logged in it turns up as a login and a pool, with its models in the picker. A pool with logins of several kinds lists each one's models under its name. OpenCode's free models work with no login; Cursor needs agent login first, and Grok grok login. Gemini on a Google AI plan (Pro or Ultra) runs through Google's own Antigravity agent, the way T3 Code does: download agy_acp_server.par for your Mac from the ACP Registry (version 1.4.5 works; 1.5.0 didn't start sessions on a Mac on 20 Nov 2026), set its path as antigravityPath in runner.json, and sign it in once with your Google account. Threadbear can't sign it in for you yet: the login shows up once ~/.gemini/antigravity-acp/acp_token.json exists, which signing in from an ACP client that uses that folder makes. It then shows as a Gemini login with your plan's models. Google's FAQ says using an Antigravity login from other software can get the account suspended, so that risk is yours. Every tool it uses asks Threadbear first, and reads inside the thread's folder go ahead. Everything the agent wants to do comes through Threadbear first: on Ask and Plan first you get the usual cards, Auto behaves like Ask, and Full access goes ahead without them. A folder's own OpenCode config and plugins aren't read in these threads. Cursor can't be told to always ask, so its Ask, Auto and Plan first threads run in its read-only modes and can't change anything; to let Cursor change files, use Full access. Grok's own settings (including your ~/.claude/settings.json, which it reads) can tell it to go ahead by itself, so Threadbear starts it with a hook of its own that sends every write, command, web search and MCP tool call to you first, whatever those say; reading files inside the thread's folder goes ahead, and reading outside it asks. If Grok didn't load that hook (a folder's .grok/config.toml can turn plugins off), the thread stops before Grok can do anything. A folder you've trusted in Grok runs its own Grok hooks, which could act before anything asks you, so there (and in your home folder, which Grok always trusts) Grok threads need Full access; take the folder out of Grok's trusted folders (/hooks-untrust) to use Ask or Auto. Denying a card ends Grok's turn, as it does in Grok's own app. Grok's models each list their effort levels (low to extra high), and the effort you pick is the one it runs at. Small jobs (titles and summaries) stay on Claude unless you pick a pool of only OpenCode or Grok logins for them in Settings. There are no usage readings, sandbox or going back to an earlier message for these yet, and Threadbear only updates their CLIs when you press Update in the Updates panel.

Titles, the librarian and Wake when… run on a Claude login, so with only Codex they don't happen: threads keep the first line of their first message as their title.

Logins are grouped into pools, one for Claude and one for Codex to begin with (Settings > Pools). A new thread in a pool starts on the login with room whose weekly limit resets soonest, so a week's leftover gets spent before it's lost rather than draining the login with the most room. A login is used until it's all but out (under 1% left), so none of a week goes to waste. When the one it's on runs out, before a turn or partway through one, it moves to another login in the pool with room, and carries on from where it was. A quiet line in the conversation says so each time: the login it moved to, the one that ran out, and when that one is back (for a thread on another of your machines too, and on the phone and the website). When none has room, the thread waits and carries on by itself once a limit resets, and the line says when that is. With only one login, that means it waits for that login's limit to reset. A thread pinned to one login does the same on that login. Either way, the box at the top of the message field says what happened and offers Switch to another login now; set its Carry on by itself to No and the thread waits for your next message instead. When a Codex login it would carry on with has a usage reset left (Codex gives out free ones, listed under Usage limit resets in its settings), the box also offers Use a reset: it restores that login's 5-hour and weekly limits at once, spending the reset that expires soonest, and the thread carries on. Threadbear never uses one by itself. A Codex login that reads as used up is asked for its limits again every 10 minutes (free, no turn), so a reset you use in Codex itself shows up here within minutes and that login is used again. Picking a model on another login from the model menu after a limit stop (a Codex one when Claude is out, say) carries on straight away too, on the model you picked. When the thread is idle otherwise, it says the new model takes over from your next message, as nothing runs until then. The first time a pool has a second login, a card by the composer says what pools do.

With more than one machine, they all share the same pools, so you set them up once from Settings > Pools on any of them. A pool knows its logins by email, and each machine uses the ones it's signed in to: a pool of three Claude logins is just one on a server signed in to one of them, and a pool none of its logins are in doesn't show there. Two logins on one machine signed in to the same account (two config folders, say) are told apart there by which login you picked, and Settings > Pools shows the login's note or id beside the email; other machines still match them by email. tb accounts says when two logins share an email, and tb accounts --json gives every login with the room it has left (each limit's percent and reset, merged from all your machines' readings), for a script to check. A login signed in on several machines is one subscription, so each machine shows the newest reading of its room from your first Mac, and one that hit its limit there waits on the others too. A Mac with a key of its own gets your first Mac's readings of only the logins you list for it there: tb runner logins shows each one's list beside the logins it says it has, and tb runner logins <runnerId> claude:you@example.com sets it. Your first Mac goes by its own readings, never that Mac's.

Usage, the honey pot near the bottom of the left-hand rail (it's filled to the room left on the login your next new thread would use), shows how much room each login has left before it hits its limits: the weekly one, and the 5-hour one for logins that still have it (Claude Team does, Max plans don't any more). Threadbear learns these numbers from the threads it runs, so a login's bars fill in once it has run something.

At the top it shows what you've spent: tokens today (and what a usual day had spent by this time), in the last hour and over the last 7 days, with a chart by the hour or by the day, each login in its own colour. Hover a bar to see who spent what. The tokens are read from the Claude and Codex transcripts on your Mac, so work done outside Threadbear counts too; the first read takes a minute or so after the runner updates.

Below that, each pool has a card with a row for each login in it: a ring with how much of its week is left, the provider's logo and the login, and one line saying how it stands: in red, that it's used up and when it's back; in orange, when it runs out and how long before the reset; in green, how much of the week will go unused, so it's worth leaning on that login; otherwise that it's on track, or when it resets. At the right is what it's spent today.

Click a row to open it. Under it is a small chart of the last seven days, rolling, with the days along the bottom: last week's readings stay on it after a reset, and your current pace is dashed on to the next reset. Then the 5-hour window as a small chip, where the login has one, and the login's buttons. Hover the ring, the chart or the chip for its rate. A sign-in that's ending or has ended shows under its row even when it's shut.

A login with no number yet says why on its row, with a dashed ring: a Claude or Codex login that hasn't run a turn here yet; Grok, which shows its plan's limit only through its own background service; or OpenCode, whose own models spend a balance rather than a weekly limit.

A Claude login with a limit of its own on Fable shows that week too, "Weekly Fable", with its own chart beside the others, as Claude Code's /usage does. Running out of it only stops Fable: the login can still run other models, so it never makes a login look full. If you don't use Fable, turn off "Show models' own weeks" in Settings › General › Usage.

When a login's week will go partly unused (the green line), its open row has Find work for it. It starts a thread on that login that looks through your projects and threads, suggests 2 to 4 jobs worth spending the rest of the week on (a deep review, the tests a report said were missing, rough options for something you're exploring), and asks before starting any. Each one you say yes to starts on that login, so it spends the week that would otherwise go to waste. Pressing it again while that thread is still open takes you back to it.

Threadbear also does this by itself, with "Tell me when a week's about to go unused" in Settings › General › Usage (on to begin with). A day before a login's week resets, if at the rate it's going 30% or more of it would be left, the same thread turns up in your inbox, and once more 8 hours before the reset as a last call if 20% or more would still be left. It never starts the jobs without asking.

Review by another lab

When a thread changes code (five lines or more, not counting docs) and finishes with nothing for you to do, Threadbear has another lab try to break the change: Codex reviews a Claude thread's change, and Claude a Codex one's, to begin with. Settings › General › Code review has two lists. Every change lists who reviews, in order: drag them into the order you want, add any other provider you have a login for (Grok, say), and pick each one's model and effort. The first that isn't the thread's own provider and has a login with room does the review, so when one runs out for the week, the next takes over. You can list a provider more than once on different models. Gemini reviews through the Gemini login on a Google plan (above), or through OpenCode: give OpenCode a Google AI Studio key (opencode auth login google) and its Gemini models show up under OpenCode once the runner restarts.

For a big change (150 lines of code or more) or one to code about sign-ins, passwords, secrets or payments, a review panel can look at it instead: the reviewers under Big or risky changes, each on its own model and effort, review at once, each in a thread of its own. A provider can be in both lists, and one only on the panel (Gemini, say, which is paid for every token it reads) never reviews a small change. Your thread waits for all of them and gets their findings in one numbered list, each saying who found it, and the round only passes if none of them found anything. Smaller changes still get the one reviewer, so the panel's cost goes where it pays. With fewer than two of the panel able to review, the one reviewer does. "labPanelLines" in runner.json changes the 150. The review runs in a thread of its own in the same folder, with the same permissions as the thread it reviews, and is told not to edit anything. Your thread says who is reviewing and waits. The reviewer gives a verdict: a list of concrete findings, or nothing that holds up. Then your thread wakes with them numbered, and it can't finish until it has answered each one: fixed, disputed (saying why), or left for you to decide, which comes to you as a question. Anything it fixed gets reviewed again, just the new change, until a round finds nothing. A quiet line in the thread, over the reply, shows who reviewed and how it came out. It folds like the agent's work: click it for each finding and what was done about it, and the review thread's link under them. Findings still open (left for you, or not answered) show under it even while it's folded. It stays off the done card, as it happens in the background. The review thread is archived when it's done, so it stays out of your inbox. That holds however the review ends: if it gives no verdict, asks you something or stops with an error, your thread still wakes with whatever it said, and carries on. A thread gets at most three reviews between your messages, and if the last one's fixes weren't looked at, the card says so. For now the findings only show on the Mac whose runner ran the thread; the phone, the website and your other Macs see the agent's reply, which says the same in words.

With no login of another provider, a fresh session of the same one reviews, and the note says it isn't another lab. A folder a pool is kept for is only ever reviewed on that pool's logins. Reviews cost tokens on the reviewing login, so if you'd rather not have them, turn off Settings > General > Code review ("labReview": false in runner.json).

Claude threads run through Claude Code's Agent SDK, and Anthropic's 5-hour meter seems to count that traffic as more per token than the same work typed into claude in a terminal. People have measured anywhere from about 1.6 to 2.9 times as much (anthropics/claude-code#97074), while weekly limits come out about the same in most of their tests. Some apps change the label the SDK sends to get around it. Threadbear leaves the label as it is for now.

Standing instructions

Settings > General > Instructions is for what every agent should always keep in mind: who you are, how you like things written, what you build with. Every new session gets it, on every login, Claude and Codex alike, and a chat that's already going hears a change before your next message, with a line in the thread saying so. It saves as you type; empty is none. A login's own CLAUDE.md or AGENTS.md still applies, and is the place for what's particular to that login or provider: this box is for what goes for all of them, without keeping several files in step.

Only what you save in Settings counts. If anything else changes the file (an agent, say), no agent is given it, Threadbear warns you, and the box shows what the file holds so you can keep it or clear it. Agents can't change it for you, so ask one to draft some and paste them in yourself. On Full access an agent that goes after the runner's own key could still get past this, as it could with anything on your Mac.

Open Anything

In the new desktop app (the gpuiApp experiment), ⌘K or ⌘P (or Go > Open Anything…) from anywhere in the main window puts a box over it, with the rest dimmed. Type part of a name and it finds threads, panels, projects and the app's own pages, in that order of groups: Panels, Threads, Projects and App. Letters in order are enough ("ytcm" finds yt-channel-manager).

  • Threads are found the way the sidebar's search finds them (the title, the last reply, the librarian's search words), archived and hibernating ones too, and it says so on the right.
  • A panel shows its count and the folder or project it comes from. If the open thread hasn't got it, it opens on the project's page when its folder is in a project, otherwise on the newest thread in that folder.
  • App has Inbox, Scheduled, Projects, Librarian, Usage, Updates, Connectors, Runners and each section of Settings ("keyboard" finds Settings › Keyboard).
  • What Return opens is the first one named for what you typed, even below others: "usage" opens Usage, not a thread that only mentions usage.

With nothing typed it shows Recent (what you've opened lately, through the box or not) and Go to (the pages, with their keys). ↑ and ↓ move, Return opens, and ⌘Return opens beside: a thread in a panel of its own, or a panel next to the main one. Esc or a click outside puts it away, and ⌘K again does too. The Mac app hasn't got it.

Keyboard shortcuts

Hold ⌘ to see the keys beside the buttons that have them. Settings (⌘,) > Keyboard lists every command in the menus that can have a key, and you can change any of them there. Click a command's key and press the new one. Esc cancels, and Delete removes the key. A command with no key has an Add button, and one you've changed has Reset beside it.

A key has to include ⌘ or ⌃, or be a function key, otherwise it would type instead. If another command already has the key, it asks whether to give it to this one, which leaves the other with no key. Keys that something else needs, like ⌘C for Copy or ⌘← for moving the cursor, can't be used.

The keys you've changed are in shortcuts.json in Threadbear's data folder, so you can ask an agent to change them too, and a change to the file shows straight away. It holds only what you've changed, by the names below, and null means no key:

{
  "nextInboxThread": "ctrl+j",
  "archive": null
}
  • New Thread: newThread, ⌘N
  • Archive: archive, ⌘E
  • Hibernate (opens Pick a time): hibernate, no key
  • Stop: stop, ⌘.
  • Copy Transcript as Markdown: copyTranscript, ⇧⌘C
  • Back: back, ⌘[
  • Forward: forward, ⌘]
  • Next Inbox Thread: nextInboxThread, ⌥⌘↓
  • Open Anything (the new desktop app only): openAnything, ⌘K, and openAnythingAlso, ⌘P
  • Show Inbox: showInbox, ⌘1
  • Show Scheduled: showScheduled, ⌘2
  • Show Projects: showProjects, ⌘3
  • Show Librarian: showLibrarian, ⌘4
  • Show Hibernating: showHibernating, no key
  • Show Archived: showArchived, no key
  • Settings: settings, ⌘,
  • Quit Threadbear: quit, ⌘Q
  • Zoom In: zoomIn, ⌘=
  • Zoom Out: zoomOut, ⌘-
  • Actual Size: actualSize, ⌘0
  • Show Threads: toggleThreads, ⌃⌘S
  • Collapse Threads: collapseThreads, ⌘/
  • Show Panels: togglePanels, ⌥⌘P
  • Show Terminal: toggleTerminal, ⌘J
  • Reset Panel Layout: resetPanelLayout, no key

In the file, a key is its modifiers and then the key, joined with +: cmd, ctrl, opt and shift, then a character, or down, up, left, right, return, tab, space, delete, home, end, pageup, pagedown or f1 to f20.

The rest are every Mac app's own and can't be changed: the Edit menu's (⌘Z, ⇧⌘Z, ⌘X, ⌘C, ⌘V, ⌥⇧⌘V, ⌘A, with Start Dictation and Emoji & Symbols under them), ⌘W to close the window in front, ⌘M to minimize it, ⌃⌘F for full screen, and ⌘H and ⌥⌘H to hide. In Settings, the up and down arrows move through its sections.

Experiments

Some new features start as experiments: off unless you turn them on, while they're tried out. Turn one on or off in Settings > General > Experiments (the ⓘ beside each says what it does), with nothing to restart. The switches are kept under experiments in runner.json in Threadbear's data folder, read at every turn, so an agent can set them there too:

"experiments": { "keepAwake": true }

Once an experiment has proved itself it becomes a standard part of Threadbear, and its switch goes.

The ones there are now, and what each does, are in docs/experiments.md, which is made from the experiments themselves so it stays true.

Connectors

Agents get services like Notion, Sentry and Cloudflare from your Connectors gateway, and Gmail, Drive and the like from claude.ai's connectors on each login. Now and then one needs signing in again.

The gateway is optional: it's a small server of your own (plugbear) that signs in to each service once for all your logins and Macs. Without one, agents use claude.ai's connectors alone, and Notion boards on projects aren't read.

Once there's a gateway, the Connectors icon (the plug) near the bottom of the left-hand rail opens a panel listing the gateway's services and whether each is signed in. A blue dot on the icon means one is signed out: click Connect beside it, and its sign-in page opens in your browser. A grey dot means something's off that usually sorts itself out, such as the gateway not answering for a moment. The arrow in the panel checks again, and the ⓘ says more. If the gateway can't be reached at all, the panel says so.

When an agent runs into a service that needs signing in, it asks you in its reply, with a button that opens the page to do it on. That's only when the gateway itself says the service is signed out (or claude.ai's own sign-in error comes back), never because an email or a page the agent read says so: those are anyone's words, so a "sign in again" in them asks nothing. claude.ai's own connectors are signed in on claude.ai (Settings > Connectors), on the login the thread runs on.

The prompts macOS shows you

  • Notifications. The first time the app opens, macOS asks whether Threadbear may send notifications. Either answer is fine: with them on, the app tells you when a thread needs you and you aren't looking at it, which helps most when your threads run on Full access and you've wandered off. You can change it later in System Settings > Notifications.
  • Folder access. When an agent reaches into a protected folder, such as Desktop, Documents, Downloads or Dropbox, macOS asks whether to allow it. Click Allow if you want agents working there, or Don't Allow if not. You can change your mind later in System Settings > Privacy & Security > Files and Folders. iCloud Drive and removable drives ask too. The prompt names Threadbear Runner when an agent asked, and Threadbear when the app itself opens something there for you, such as a pinned picture on your Desktop. Starting threads in ~/ThreadbearThreads keeps these prompts away until you choose a folder that needs them.
  • A Mac nobody's sitting at. The agent waits for that answer, so on a second Mac a folder prompt can hold a thread up with nobody there to click. Give Threadbear Runner Full Disk Access on that Mac, in System Settings > Privacy & Security, and the prompts stop. Do this when you set the Mac up: a waiting prompt can also hold up other apps using the same drive until someone answers it. The trade-off is that agents there can read everything your account can. If a thread does get stuck like this, it says so after a minute or two and goes in Needs you. Five minutes later Threadbear stops the turn, and your next message carries on from there.
  • A thread called "... needs someone at its screen". Threadbear starts one when a macOS dialog has been waiting on a Mac for 5 minutes, or when a Mac without the Threadbear app doesn't have Full Disk Access yet. Open Screen Sharing to that Mac and answer the dialog, or turn on Threadbear Runner in Full Disk Access there. When the dialog's gone or the access is on, the thread says so within a couple of minutes and archives itself, unless you've written in it.

Your phone and a browser

The Threadbear iPhone app is for when you're away from the Mac: ask a thread a question, steer it, answer the ones that need you, start new ones, and see how they're all getting on. Its inbox sorts threads the way the Mac's does, into Starred, Inbox, Running, Hibernating and Archived. A thread that finished saying it needs nothing from you is done there too: it doesn't rise to the top or count towards what needs you, though it shows as unread until you open it. To star a thread, swipe its row to the right, or use the menu when you press and hold it or the ... menu inside it. All but Starred and Inbox start folded, showing how many they hold; tap a heading to open or fold it, and the phone remembers. Each heading stays at the top while you scroll through its threads, and a thread that changes heading travels there, so one finishing rises from Running into the Inbox. A folded Archived isn't loaded at all, nor the hibernated threads in a folded Hibernating, so the phone fetches less. A thread's finished turns fold into one Worked line above the reply, as on the Mac; tap it to see the work. Swipe right on a thread's messages to go back, and left to go forward again to the thread you just left, with the Mac's card saying where letting go lands. A code block or table that can still scroll keeps the swipe. The search at the top of the inbox finds any thread, hibernating and archived ones too, by its title, last reply, project, the librarian's search words for it, or a word said anywhere in it. What a thread needs from you shows under its reply with the likely answers as buttons (type in the box to say something else; the one you tap spins until the runner has it, and the card comes back if it's refused), and a thread that's done offers its suggested next steps and Archive, which takes you back to the inbox as its row slides away. Hibernate from a thread's ... menu does the same, with its row sinking towards the Hibernating heading. Clear the last thread from the inbox and the bear waves at you, the once. Pull the inbox down and let go to reconnect to your Mac's mirror, if the list ever looks stuck. A new thread from the phone starts in your default folder; pick its model and effort under the message, or leave them on Default. With more than one runner it starts on the first one that's online in your order, so a sleeping Mac doesn't hold it up; pick another under Runner, or change the order in Settings > Runners > Change the order. The sheet closes as soon as you tap Start, and a row at the top of the inbox says Starting until that Mac has made the thread, which then opens. If it couldn't start, the row says why; tap it to open it again as you left it, photos and choices too. While a thread is working and nothing's typed, Send turns into Stop, as on the Mac, here and on the website; it spins until the turn has stopped. Anything typed while it works goes into that turn instead. Paste a photo straight into any message box, or add one with the photo button: it goes in where the cursor is as a chip, "Picture 1", as on the Mac, and pictures in your messages show as chips too. The photos you sent show over your message, where the Mac uploaded them for your website (on unless "sync": { "pastedPictures": false }); one that stayed on the Mac leaves a "[1 picture]" line instead. Pictures an agent puts in its reply or pins show in the thread, and animated GIFs play; tap one to see it full screen and pinch to zoom. An MP4 or MOV video an agent pins shows its first frame with a play button, and plays when you tap it. Anything over 10 MB, or from a thread that's been quiet for over two weeks, says it's on your Mac. Rename a thread from its ... menu or the menu when you press and hold its row: the new title shows straight away, and goes back with the error if your Mac can't take it. To point one thread at another, use Copy Thread ID in the same menus, and paste it into a message, here or on the Mac: it goes in as a link to that thread, with its title. When the Mac a thread runs on is asleep or offline, its message box says so, and what you send waits for it: each message shows faded with a Cancel under it until that Mac takes it, and Cancel puts its words back in the box. It can send notifications too, though you don't need them for any of that. It pairs with your Mac by scanning a QR code: on the Mac, Settings (⌘,) > Phone & browser > Show the code, then scan it with Scan the code in the iPhone or Android app (not the Camera app: the code isn't a link, so the Camera only shows it as text). Keep the code to yourself: it works once, for ten minutes, and whoever scans it first can run your agents. To pair a phone that's paired already, Unpair it in its Settings first. The same tab lists each paired phone and browser with when it was paired and until when (90 days), and Revoke signs one out and stops its notifications; Settings > Unpair this phone on the iPhone forgets it from that side. The terminal command setup used to print still works too:

swift ios/scripts/pair-qr.swift --prod --url <your deployment URL>

If you have them on, notifications reach your phone only while you're away from the Mac by default. Threadbear counts you as at the Mac when the app is open and you've used the keyboard or mouse in the last two minutes, and as away when the Mac is asleep. On the iPhone, Settings > Notify me changes it to Always or Never.

Ask on the iPhone: press the Action button, say a question, and hear the answer from an archive server of your own, one that knows your past threads. Mike's is Agent Archive, which isn't public yet: he'll be talking about it soon and releasing it then. Until then, any server that speaks Ask's small protocol works. Set it up in the iPhone's Settings > Ask: Scan the code reads a setup code your server shows (Agent Archive's npm run phone-token -- issue --bruce --qr), or type in the server's address and a token from it. The phone has to be able to reach the server, over Tailscale for one on your own Mac. Then set the Action button to Threadbear's Ask shortcut. The waveform button in the inbox does the same. Each answer is kept as a thread in your default folder, with the question, the answer and a note that Ask answered it. It shows as done and already read. Once it's kept, the phone opens that thread with a big mic at the bottom: tap it and say a follow-up, which goes to the agent as an ordinary reply on a small fast model (Haiku, or GPT-6-Luna with no Claude login; change it in the thread if it needs more), and its answer is read out when it's done. The keyboard button beside the mic brings back the text box. The agent is told the thread started with Ask and picks up from there.

The Pocket is for what you'll want while you're out. Tell a thread you're heading to the post office and its agent can file a card with the address and what to take; the wallet button at the top of the inbox opens the deck, and its badge says how many cards there are, in colour when one's been filed or changed since you last opened it. The cards are saved on the phone, so they open straight away with no signal. Tap a card to bring it forward, then tap it again to fill the screen, black on white, for reading out or holding up at a counter. Swipe a card left to remove it, with a few seconds to Undo, or press and hold to copy it, open its thread or remove it. Each card has its own icon and colour, chosen by whoever filed it. A card can name a place: while the app's open the phone checks where you are, marks that card "here" and brings it to the front (it asks first, and only the phone and Apple's map search see your location). Agents replace or remove cards too, and the pencil starts a thread to add one. The librarian looks after them as well: it updates a thread's card when the facts change, takes it out once the thread says it's done, and files one when you say you're going somewhere and the agent didn't. It only touches cards from the thread it's looking at, adds at most one per thread, and won't put an address or code on a card unless the thread said it. The Librarian view lists what it did.

Your threads also have a website, on your own Convex deployment. To sign a browser in, Settings > Phone & browser > Open signed in opens it in your browser (or run npm run web:sign-in from your Threadbear folder). Each thread has its own link. Open on the web in a thread's ... menu on the Mac takes you there, and the Copy link button on the website copies it. It works anywhere you're signed in. Its sidebar works like the Mac's: drag its edge to resize it (double-click to reset), click a heading to fold it, sort the Inbox from the arrows on its heading, and search or filter from the top. The filter is only on the website: it picks threads that need you, unread or shared ones, or one project or folder. The rail down its left edge opens your schedules, projects, runners and each login's usage. A schedule can be paused or run from there, and a runner shows how busy its machine is, with an orange dot on its tile while it's low on memory or disk. Other changes are done on the Mac or by asking an agent. The gear has the appearance and Sign out. Pictures you paste show there too: they go to your Convex deployment as they are, so nothing can scrub a secret from one, and "sync": { "pastedPictures": false } in runner.json keeps them on the Mac. A tool line opens to what the tool did if its runner has full sync on (it starts off; tb settings full on|off changes it, and docs/on-your-mac.md says what it sends), and its screenshots show when you tap them. The pencil beside the search starts a new thread on a runner's default folder and login. On your Mac, threadbear://thread/<id> opens a thread in the app instead (the Open thread button on a tab BrowserBear has marked for an agent uses it). With the new desktop app installed beside the Mac app, those links open the new one; desktop/scripts/thread-links.sh swift sends them back to the Mac app.

To let someone else read a thread, click the share button beside a thread's ... menu (or Share with others in that menu's Share submenu) and pick Anyone with the link, then Copy link. It's a read-only page anybody can open, which follows the thread as it carries on. It reads like a short write-up: each of your messages, the work folded into one "Worked for" line (open it for one line per step), the answer, and the pictures, but not tool output, the folder or the cost. Pasted into Slack, X or Messages, the link shows the thread's title, the start of its last reply and its first picture. Only you stops the link working (sharing again brings the same link back), and the arrows beside the link make a new one, which stops the old. The same Share button is on the website, on your thread's page and on the shared page while you're signed in.

The Mac app also draws a picture an agent writes into its reply with a path on your Mac (![a chart](/path/to/chart.png)), rather than showing a link. A picture written as a web address (![a chart](https://example.com/c.png)) is a link everywhere, on the Mac, the phone and the website: tap or click it to open it in your browser. Threadbear never fetches one by itself, so whoever runs that site can't tell you're reading. On the phone a reply draws its first 10 pictures; any past that show as their names.

The website also has a Machines page, at /machines on your website's address, for whoever's signed in there: it draws each of the backend's state machines (so far, how a message or request from your phone or the Mac travels to a runner: waiting, taken, done or failed, and lapsed when a runner never says how it went; and how a thread moves to another Mac, from asking through packing and unpacking to done; and another Mac's request for a new thread, waiting for you, being started, allowed, denied or closed; and a deleted thread's old messages being cleared away), with how many are in each state right now, and any one's history. It's for looking into something that seems stuck; it changes nothing.

On Android

There's an Android app too, for the same things: your inbox, answering threads, starting new ones and notifications. It isn't on Google Play yet, so you install it yourself from GitHub, where each Threadbear release puts a new copy:

  1. On your Android phone, download the latest Threadbear APK.
  2. Open it from your downloads. The first time, Android asks whether your browser may install apps: allow it, then tap Install.
  3. Open Threadbear and pair it with Scan the code, as above.

After that it looks for new releases itself. When one's out, its inbox menu and Settings show "Update to" and the release's date, and tapping it downloads the new APK to install over the top, still paired. Notifications come through Google's Firebase, so a phone without Google Play services gets everything but those.

Self-hosting your backend

We recommend Convex cloud, which is what setup uses unless you ask for something else. Your threads go to a Convex project in your own account, which keeps working while your Mac is asleep, sends your phone notifications, and needs nothing else installed. The free plan is enough for one Mac's ordinary use.

If you'd rather keep everything on your own machine, setup can run Convex's open source backend in Docker on your Mac instead, and reach it over Tailscale (or your own way, below). It's the same backend and the same features, with these limits:

  • No phone notifications. The push relay only works with Convex cloud. The iPhone app shows what needs you when you open it, and its Settings say why nothing arrives.
  • Your phone needs Tailscale on, as the backend is only on your tailnet.
  • Nothing works while your Mac sleeps or Docker is stopped: the phone and the website can't reach the backend until it's back.
  • Share links only open for people on your tailnet, so "Anyone with the link" means anyone on your tailnet.

You need Docker Desktop (or OrbStack), set to start when you log in, and Tailscale, logged in, with MagicDNS and HTTPS certificates on for your tailnet. Then run setup with --self-hosted, or ask your agent to (INSTALL.md says how):

./threadbear setup --self-hosted --yes

It starts the backend and its dashboard in Docker, on this Mac only, and puts them on your tailnet with tailscale serve: your threads' API on port 3210, your website on 3211 and the dashboard on 6791, all at https://<your Mac>.<your tailnet>.ts.net. Then it deploys Threadbear's backend and website there as it would to Convex cloud, and keeps them up to date the same way. Pair your phone and open the website from Settings › Phone & browser as usual.

The dashboard's sign-in asks for the admin key, which is in secrets/convex-self-hosted.env in Threadbear's data folder. Keep it to yourself: it can do anything to your backend. If the phone or the website can't reach it after a restart, run ./threadbear setup again: it starts the backend, or makes it again on the same data. docs/self-hosting.md in the repo has how it's put together, backing up, upgrading and taking it out.

On this Mac only, without Tailscale

If you won't use the phone, or you can't use Tailscale (your work keeps you on its tailnet, and Tailscale only has one on at a time), add --local:

./threadbear setup --self-hosted --local --yes

It's the same backend in Docker, on this Mac's 127.0.0.1 only: nothing on your network or any tailnet can reach it, and Tailscale isn't needed at all. That leaves out more:

  • No iPhone app. Nothing off this Mac can reach the backend, so Settings › Phone & browser says why rather than showing a code, and there are no notifications.
  • No second Mac joining this one.
  • The website and share links only open on this Mac, at http://127.0.0.1:13211. "Anyone with the link" means anyone using this Mac.
  • Nothing works while your Mac sleeps or Docker is stopped, as with the tailnet one.

The dashboard is at http://127.0.0.1:16791, with the same admin key. Running setup again keeps it local. If you get Tailscale later and want the phone, run ./threadbear setup --self-hosted --tailnet: it moves the backend onto your tailnet and your threads stay. --local moves it back.

At your own address

If your phone already reaches your Mac your own way (Caddy, nginx, cloudflared, your own Tailscale or a VPN), give setup the two https addresses your proxy answers on, and Threadbear leaves the rest to you:

./threadbear setup --self-hosted --yes \
  --url https://threadbear.example.com \
  --site-url https://threadbear-site.example.com

The backend stays on this Mac's 127.0.0.1, and your proxy points --url at 127.0.0.1:13210 and --site-url at 127.0.0.1:13211 (your website and share links). Setup checks both work, from this Mac and from inside Docker, before it carries on, and says which one didn't. Then pair your phone from Settings › Phone & browser as usual. That needs iPhone 1.0.5 or later.

The limits are the tailnet way's, except that Tailscale isn't needed: no phone notifications, nothing works while your Mac sleeps, Docker is stopped or your proxy is down, and share links open for whoever can reach your address. --local or --tailnet move it off your address, and your threads stay. Take your proxy's rules for both addresses down first: setup can't do that for you, and it stops, naming the address, while either still reaches the backend from this Mac.

Patches: your own buttons and panels

A patch adds buttons and panels (beside the thread) for the threads in a folder. A button can run a command, like your tests, send the agent a message you use a lot, or open a web page in your browser (App Store Connect, say), without adding anything to the thread. The web page buttons show on the iPhone too, over the message box, and open there. A panel can show a web page, such as your app running on localhost, or a list. A link in a panel's page to another site opens where your web links' Default says (the browser, or over the panel with a Back), so the patch's page stays put; if the page moves on to another of its own pages, a Back shows in the panel's bar, and Reload goes back to where it started. Closing a panel, or picking another thread, pauses anything it's playing. A panel's address can carry the thread it's beside, as {threadId} (docs/protocol/patches.md, "Patches"), and an agent that has changed a panel's page can have it load afresh as it shows you (show_panel with reload). The new desktop app shows a panel's page, and the Convex dashboard, with the same Chromium it draws diagrams with: until that's installed the panel asks for it (Install web runtime, or Not now) and has Open in browser, and there a link to another site always opens in your browser.

On a Mac, click a Simulator picture panel to open Simulator. A patch can use an application's icon, an icns file or a PDF for its buttons and panels too.

Buttons sit on shelves along the top edge of the message box, one shelf for each place they came from, starting with the same badge the panels wear (below). Buttons that don't fit go under a "+2" (or however many) at the end, which lists them.

Each panel has a button on the right-hand rail, with a small badge in its bottom corner (and on the panel's tab) saying where it came from: the project's own icon when it came from one of the thread's projects' folders, a folder for the thread's own folder, a house for ~/.threadbear, a wrench for a tool patch (one that's there because of a file, like a video's .tandem) and a box for one built into Threadbear. Hover over the button to see it in words.

A thread in a Convex project gets a built-in Convex panel: the deployment's own dashboard (data, functions, logs and so on), with a menu to switch between Development and Production. It uses the Convex CLI on the thread's Mac, signed in to your Convex account. If that isn't signed in, the panel says so and has a Sign in to Convex button: your browser opens Convex's page to approve it (for a thread on another of your Macs, it opens on the Mac you're at), and the dashboard loads by itself once you have. If the signed-in account can't reach the project, Sign in as someone else switches to one that can.

A patch can also show in only some of a folder's threads: those in a project, or with a word in their title. Ask for that when you ask for the panel ("only in my acceptance testing threads").

You don't need to write one yourself. In a thread in that folder, ask "add a button that runs the tests" or "add a panel showing localhost:3000", and the agent writes the patch into the folder's .threadbear/patches/ (the format is under "Patches" in docs/protocol/patches.md, in your Threadbear folder). It shows up within a few seconds. A patch is code that runs on your Mac, so keep only the ones you'd be happy to run.

Patches only run once you've trusted them. One the agent writes for you in that folder is trusted as it wrote it (in a Claude thread on Full access; one written in Ask before edits or Auto, or by Codex, waits for you), though not if you turn the edit down, not a change made to it afterwards some other way, and not other files it uses that changed some other way. A small edit to a patch you hadn't trusted yet (one from a repo you cloned, or a pull) doesn't trust it either: the rest of it isn't the agent's. One that arrives some other way, in a repo you've cloned or with a git pull, waits: a "patch to trust" chip shows above the composer, and Patches lists it as "Not run yet" (or "Changed since you trusted it") with a Trust button. Open its file to read it first, and any files it imports or runs (a setup script, say), which Patches lists under it: a change to one of those asks again too. When it changed since you trusted it, Patches says which files changed, in which commits (or that it isn't committed), and shows the changed lines, so a re-ask after your own merge reads differently from code you've never seen. In a folder last trusted before Threadbear changed how it checks patches (on 6 Nov), it says it can't tell what changed. A patch that loads code by a name it works out as it runs (import(name)) can't be checked, so it never runs and Patches says why: import its files by a plain path instead. The same goes for a command a patch runs by itself, a worktree's setup or teardown, or a hook: it has to be one script in the repo with plain words after it, like ./scripts/setup.sh --fast, so trusting the patch covers what runs. One like cd scripts && ./setup.sh or npm run setup never runs, and Patches says to put the steps in a script. What that script runs in turn (another script, a package.json script by name, a Makefile) is covered too, so a change to any of them asks again. A script that runs something worked out as it runs (eval, bash -c "$x", curl ... | sh, a command in a variable) can't be covered, so a setup or hook naming it never runs, and Patches says which line. So does a chip's command: a patch with an action that can't be followed all the way (or a python3 one) never runs, and pressing a chip checks the files again first, so one that's changed since you trusted it doesn't run and asks in Patches. A patch's badges and list panels run their commands from the folder holding its .threadbear/, and only while it's the version you trusted, with only the files trusting it covered. A thread's worktree counts as its repo, and patches that were already in your folders when this arrived are trusted for you. Patches you trusted before 6 Nov 2026 are asked about once more: the way their trust is worked out changed, so the old yes can't carry over.

A repo's own Claude Code settings are asked about the same way. When its .claude/settings.json or .claude/settings.local.json has hooks, a status line or another command Claude runs by itself, or environment settings (env, which can change where Claude sends your messages and login, like ANTHROPIC_BASE_URL, or which keys it uses), or its .mcp.json starts an MCP server, or one of its agents, skills or slash commands has hooks or MCP servers of its own, Claude starts without those until you trust them: the chip says "Hooks to trust", Patches lists "claude-settings" with the files and the scripts they run, and the thread says they were skipped. In a thread set to "Ask before edits" or Auto, its permission rules that let tools run without asking (allow rules, extra folders, a default mode, the sandbox, a skill's allowed-tools) wait too, and Patches lists what they'd allow; in Full they change nothing, so they don't ask there. The rest of the folder's settings (deny rules, a model) and its CLAUDE.md still apply; its own skills, agents and slash commands, and CLAUDE.md files in the folders above it, wait too. Trust them and your next message starts Claude afresh with all of it, carrying on the same conversation. A change to them, or to a script they run, asks again; ones the agent writes for you on Full access are trusted as it wrote them, as patches are. Ones that run something Threadbear can't check (a package by name with npx, python -m, a formatter or test runner that loads its own config and tests, a script that imports code by a name worked out as it runs), or allow Threadbear's own tools, can't be trusted at all, and Patches says why. Settings with none of this in them never ask.

A project's page has its own panels and Patches on the right-hand rail: the ones its folders give its threads.

Changing Threadbear itself

You can change Threadbear by asking a thread to. Start one in your Threadbear folder (your fork, the copy setup ran from) and say what you'd like different. If a setting or a patch would do it, the agent uses that rather than changing Threadbear's own code, so Mike's updates come in cleanly later. A thread there gets its own copy of the code to work in, and when the change is ready and its checks pass, the agent lands it on your main branch. When several threads are ready together, their landings wait for one another and can be checked together against the latest landed work. The landing's progress message says when it is already being checked with its group, with a rough estimate of the time left in that check or a note that it is taking longer than usual. If the group has landed and the command is still waiting for the landing lock, the message says it has already landed.

If a check of several landings fails, the command that ran it shows the end of its output straight away, then runs only what failed on each landing by itself to find the one that broke it. That one is told at once and left out, and the rest are checked again together. When that can't tell, it checks smaller groups instead. The agent can read any logs named there while those checks run, but must wait for the command to finish before editing the worktree it's using.

The same goes for settings. The Settings window (⌘,) shows what's set and has controls for only a few common things, and the ⓘ beside each section says what it is. Click it to read it, or hover for a quick look. The bear with a plus at the end of each section's heading (and Start a thread about this, under the ⓘ's words) opens a new thread with the section named in its box, so you can ask an agent to change it or explain it. Most settings live in runner.json in Threadbear's data folder, and an agent can change them or set up anything more involved, so ask one first. If you edit it by hand and leave it broken (a trailing comma, say), the runner won't start until it's fixed, and never writes over it: tb logs names the file and what's wrong.

Settings has its sections down a sidebar on the left, like System Settings, and each one scrolls when it's taller than the window. Drag the window wider or taller for more room.

When something goes wrong, the app says so in an orange bar at the top of the thread, and the runner's own warnings show there too (a message it couldn't start, an update to main that failed). Investigate on that bar starts a thread in your Threadbear folder with the error, the thread it came up in, what you were doing and which versions you're on, and asks it to find the cause and fix it. The new thread opens and the bar goes once it's made.

Updates then arrive by themselves. Within a few minutes of a change landing on main, the runner builds it and switches over without cutting off any thread that's partway through a turn, and the app builds its new version in the background. The app swaps in the new version when you next quit it, when you choose Restart to Update in the Threadbear menu, or by itself when you've left it alone for a few seconds. The window stays where it is while it does: the new version opens the same thread underneath and takes over, so you shouldn't see it go.

Whatever's typed in a message box and not sent is kept through a quit or a restart, and so are your own answers in a card's Something else boxes, so neither holds the new version back: it swaps in and puts them back in their boxes. A few things still hold it: a picture still being copied into a box, an earlier message you're editing, a message still on its way, and words on the new-thread page (its folder and account choices aren't kept). When something else typed does (a title being renamed, say), the Updates panel names the box and the thread, with a button that opens the thread. While a runner restart waits for threads to finish, a quiet line at the top says how many it's waiting for, and hovering it names them. A message you send while the runner is restarting waits under its bubble and goes once the new one is up. If one can't be sent, its words go back in that thread's box and a note above the thread says which thread, until you dismiss it.

A runner update lets a job a thread left running in the background finish, for up to about 4 hours after the thread's last turn. If one goes on longer it's stopped, and the thread gets told and wakes by itself to check on it, so you'll see it pick back up rather than go quiet.

The new desktop app follows main too, from the checkout you installed it from. Its build takes every core of a Mac for minutes. It waits for ten minutes with no changes to the desktop app before asking for a build, so several landings close together become one update. If the build Mac is busy or has tests or timings queued, it tries again later, trying the other Macs on your build list first. While changes keep landing or those Macs stay busy, the update keeps waiting. A build already running finishes before anything else uses that Mac. It builds on another Mac you name for it (updateBuildHosts in runner.json, a list of ssh hosts) and only the finished app comes back. That Mac's build is what yours runs next, so name one you trust as much as this one: a check host (checkHosts) only runs tests and never builds the app by being one. With neither set it builds on this Mac in the background. With check hosts set but no update build host it builds nothing, and its Updates panel says to name one. With update build hosts set but none answering, the panel says it's waiting for a Mac and it tries again later. A new version waiting to go in that a Mac off that list built is thrown away. An app installed before 12 Nov 2026 built its updates on a check host, so it can't update itself past then: install it again once (desktop/scripts/install-app.sh, with --build-on <host> to build on a Mac you choose). The new version goes in when you quit it, when you choose Restart to Update in its app menu or Updates panel, or by itself once nothing's typed and nothing's open that a restart would close (a menu, a dialog, a drag, a field you're typing in another of its windows, a Terminal shell running something or with words at its prompt, a web panel you've used in the last minute): straight away while you're in another app, and with it in front once you haven't touched the Mac for five seconds. "Typed" is any box: a message, a card's own answer, a project's goals being edited, a picture still coming in. It opens again on the list and the thread you had, behind the app you're in if that's where you were, with every thread you'd scrolled up in where you left it rather than at its end. On a Mac its window stays where it is: the new version opens the same thread underneath and takes over, as the Swift app's does.

The Updates icon on the left-hand rail shows what's on its way for the app, the runner and the Claude Code and Codex tools. While the app's next version (or a runner release) is building, a short arc goes round the icon; once the app's next version is ready to restart into, the icon turns green. A grey dot means something else is in progress and will sort itself out, and a coloured dot means it needs you. Right-click it for a quick Restart to Update.

A few parts of the runner (the program that keeps it going, and the small Threadbear Runner app macOS names in its privacy prompts) don't come with its updates. When one of them is behind, the runner updates it by itself, in the background. That stops nothing: the new ones are put in place and take over the next time your Mac restarts or you log in again, and until then the Updates panel says they're waiting for that. If it doesn't work, the panel says why, with Try again and the log. A failed one isn't tried again by itself until a newer version comes along.

Mike's updates

Your copy is a fork of Mike's, and it doesn't change unless you say so. About once a day Mike publishes a release. Your runner checks for new ones every few hours, and only trusts a release signed with the key setup saved and already on Mike's main (not one signed on a side branch). Mike can replace that key through a signed release: a new key counts a week after a release signed with the old one names it, and a key he revokes stops counting at once. When there's one your copy doesn't have, the Updates icon gets a coloured dot, and its From Mike section shows what's new: the biggest changes as cards from the What's new page, each with its picture or clip (hover one for what it does, click it to see it on the page), how many things were added, changed and fixed, with See all for the whole page, and how many important fixes there are (hover for which). A release the page doesn't have yet, or any release when the page can't be reached, is listed in plain words instead, and older releases without notes show their commit subjects. Bring Them In starts a thread that works out how Mike's changes merge with your own, without checking anything out, tells you what they bring and how it would settle any clashes, and asks. Nothing from the release runs until you say go: then it merges, runs the checks and lands. Let's Discuss starts one that talks the release through first, what's in it and what it means for your own changes, and changes nothing until you say. From a thread, tb updates says the same, and tb updates check looks again now. Once a release is in, the thread offers to send Mike a short check-up: which release came in, how far behind you were, and how often Threadbear's own errors came up, with anything of yours only counted. You see the whole draft first, and it goes as a comment on a public Discussion on Mike's repo, under your GitHub login, only if you say Send. Never ask turns it off ("releases": { "checkup": false } in runner.json).

You don't have to remember to look. Every 5 days, if Mike has a release your copy doesn't have, Threadbear starts that thread for you: it reaches your inbox with what's new and one question, whether to go ahead, and runs nothing from the release before you answer. There's only ever one; if you leave it open, a newer release goes into the same thread. A release Mike marks important (a security or data fix) starts one straight away. Change how often, or turn it off, in Settings (⌘,) > General > Updates from Mike.

Moving to the new desktop app

A new install gets the new desktop app straight away: ./threadbear setup builds and installs it (~/Applications/Threadbear GPUI.app), never the old Mac app. This part is for a Mac that already has the old one.

The Mac app is being replaced by a new desktop app that looks and works the same and runs on Windows and Linux too. The Mac app is frozen now: it no longer gets new features, and everything new goes into the new app. There's no date yet for when it stops being updated; once there is, the window and the card below say it too.

The Mac app tells you about it once when it starts, in a window with Not now and Start using the new app, and keeps a card at the top of the sidebar until you start or press Later (which hides it for a week); the card's Start using it brings the window back. Start using the new app starts a thread, "Switch to the new Threadbear app", in your checkout, and the window closes once it's made. The card then shows that thread, what it's doing and Open the thread. The thread builds the new app on your Mac from your checkout's main with desktop/scripts/switch-from-swift.sh, at background priority, which takes 20 to 40 minutes the first time and installs Rust first if there's no rustup (docs/on-your-mac.md says what that puts where). It needs about 5 GB free with Rust to install, 4 without, and says so before it starts if there isn't that much. If something stops it (Xcode's command line tools, Rust, disk space, a build error) the thread works out why and fixes it, or asks you. When the app's installed it asks whether to switch now, with Switch now and Later, and only switches when you say: it makes the new app the one threadbear:// links open, and opens it. If your runner.json has check hosts, it builds on a Mac named in updateBuildHosts instead, as its updates do. The Mac app stays installed and keeps working, and desktop/scripts/thread-links.sh swift gives the links back to it. A few things still only work in the Mac app: docs/gpui-port/PARITY.md lists them. Neither the window nor the card shows once the new app is installed, except the card for a switch thread that isn't archived yet.

The first time the new desktop app opens, it brings across what the Mac app remembers: the zoom, folded sections, the Inbox's order, the appearance, the panel layout, where the window was, the ding, Ask before quitting, the activity log switch, what a click on a link does, how files and folders show, and anything typed in a message box and not sent. It only fills in what it hasn't got of its own, does it once, and a note at the top says what came across. It also brings across whether you finished the Mac app's tour, which of its pages have shown you their intro, and whether you hid Finish setting up, so you only get the tour there if you never finished it.

If your copy has changes of your own to the old Mac app (commits to app/ or dock/ that Mike's copy doesn't have), they can't come across by themselves: the new app is different code, so each has to be rebuilt in it. The first time the new app connects, Threadbear looks for them, and if there are any it starts one thread that tells you in plain words what you changed and asks whether to rebuild them. It changes nothing until you say yes, then rebuilds each one in desktop/ and shows you the new app before and after. Whatever's still to do is in the Updates panel under Not in the new app yet: Port this starts a thread for that one change, and Dismiss leaves it out. A change leaves the list once a commit that rebuilds it says so with a Ports: <commit> line at the end of its message (the threads add one), or once you dismiss it. A change you made in both apps at once (its commit changed desktop/ too) is already in the new app, so it isn't listed. In a copy with no changes of its own there's nothing to see.

Light and dark, accent, spacing and font

Settings (⌘,) > General > Appearance is how Threadbear looks, for Threadbear alone. Each change shows straight away and stays picked the next time the app opens.

  • Light or dark: three pictures. Same as the Mac (Same as Windows on Windows) follows the system's own setting: System Settings > Appearance, or Settings > Personalization > Colors > Choose your mode on Windows.
  • Accent: the colour of buttons, ticks, the outline of a card that needs you and the tint behind your own messages. The first dot is the Mac's accent (blue elsewhere); the rest are bear colours (Fur, Honey, Berry, Rose, Plum, Sky, Moss and Slate), from Wayne Sutton's fork.
  • Spacing: Roomy, or Compact for shorter sidebar rows and less room around each of your messages, so more fits.
  • Text size: Smaller, Normal or Larger, the same as View > Zoom (⌘= and ⌘-), which goes further either way.
  • Font: Allo (the default, a free font that comes with the app), System, Serif or Monospaced for everything but code, which keeps its own.

On Mac, Increase Contrast in System Settings > Accessibility > Display also strengthens text and borders. It is read at launch and when you return to Threadbear.

A ding when a thread is done

To hear when a thread finishes, turn on Play a sound when a thread finishes in Settings (⌘,) > General > Notifications. It's off until you do. A soft ding then plays whenever a thread on this Mac stops working: its reply is done, it's waiting for your answer, or it hit an error. It plays wherever you are, in Threadbear or another app, and stays quiet for a thread you stopped yourself. Several threads finishing at once make one ding. Pick Chime, Bell or Droplet (each plays as you pick it), set the volume, and press Play to hear it again.

The activity log

Turn on Keep an activity log in Settings (⌘,) > General and the app notes down what you do in it, so the agents working on Threadbear can see how you really use it: what you click, which threads and pages you open, the menu items and shortcuts you use, the tooltips you stop to read, and when you send a message or answer a prompt. It never notes what you type or the words of a message, only which button, row or item it was, by its tooltip or its name in the menu (so clicking a thread's row puts that thread's title in it). An agent reads it with tb activity, or tb activity --summary for what's used most.

It's off until you turn it on. It's kept in the activity folder of Threadbear's data folder, a file a day, and each file is deleted after 30 days. Threadbear never sends it anywhere, though once an agent has read some of it, that's part of its thread like anything else it reads. The new desktop app keeps the same log in the same files, with its own switch in its Settings, and marks its lines as its own.

Keeping the Mac awake

While any thread is working, and for three minutes after, your Mac won't go to sleep on its own, so a long turn, or one you started from your phone, isn't cut off halfway. The screen still dims and locks as usual. It stops below 15% battery when you're not plugged in, and closing the lid on battery still puts the Mac to sleep. It's on unless you turn off Keep the Mac awake while threads work in Settings (⌘,) > General > Sleep.

Privacy

Your threads are mirrored to a Convex deployment in your own Convex account, which setup made: the thread list, the text of each message, one line for each thing an agent did, and your logins' emails and usage. Anything that looks like a secret is scrubbed out of the text on the way up, which helps but isn't a guarantee. Full sync is off to start. Turned on, your phone, the website and your other machines can show each tool's output and diffs too, even when your Mac's asleep: its output, its input and diffs go up, after the same scrubbing, and are kept 30 days; output from files and commands that usually hold secrets stays on your Mac, and so do tool screenshots. Send tool output to Convex in Settings (⌘,) > General > Full sync, or tb settings full on|off, sets it any time, from the runner's next start. tb status estimates how much of Convex's Free plan you're using and warns before you get near its limits. Pictures you paste into a message go up as they are, so your website can show them, and nothing can scrub a secret out of a picture: "sync": { "pastedPictures": false } in runner.json keeps them on your Mac. A photo you send from your phone passes through that deployment on its way to the Mac and is deleted once the Mac has it; one you picked and never sent goes after a day. A message from the phone waits up to two weeks for its Mac to take it. A thread you share can be read by anyone with its link, pictures included, and only that thread. The pictures are uploaded only while it's shared, and only real pictures from its own media folder: your attachments, the screenshots its tools took, and pictures the agent copies in there on purpose (it's told where, as THREADBEAR_MEDIA_DIR). One an agent points at anywhere else, the thread's own folder or a temp folder included, stays on your Mac and the page shows its caption instead. Notifications to your phone go through a small relay Mike runs, because Apple only delivers notifications for his app through his key. The text is locked with a key only your phone and your deployment have, so the relay never sees what a notification says. The activity log (see Changing Threadbear itself) is off unless you turn it on, and it stays on your Mac.

Getting help

  • Ask a thread. Its agent knows where this guide is and can read it, or look at the code and tell you how something works.
  • Ask a thread to run tb status, which says what the runner is doing: its version, the threads that are busy, and any restart or update on the way.
  • threadbear in Terminal opens the app, and quitting it with ⌘Q is always safe, since your threads keep running without it. Closing its window (⌘W or the red button) quits it too, without asking. Quit asks first, with a Don't ask again box; Settings > General > Quitting turns asking back on. If the app says it can't reach the runner, click Start runner.
  • Threadbear > About Threadbear says which commit your copy was built from, along with a few numbers about your threads.

The tour and Finish setting up

The first time the new desktop app opens, a few small cards come up before the app, one decision each. Return goes on, and each card has Back and Skip; Esc puts them all away:

  • Your agents lists the Claude Code and Codex logins it found on this Mac. One that isn't signed in has Sign in…, which opens Terminal on its own sign-in. Add makes room for another Claude login (a second subscription, say) and opens its sign-in the same way; the row spins until it's signed in. A thread moves to it when the first runs low. For a Claude login, the same Terminal window then makes a year-long token (Year-long token…, below), so you sign in once a year rather than every 28 days.
  • Where threads start shows the folder new threads open in, with Change…, and whether GitHub's CLI (gh) is signed in.
  • Check in from anywhere shows a code to scan with the iPhone app, and ticks itself once your phone's paired. It only comes up when your Threadbear has a Convex deployment for a phone to reach.
  • A few things worth turning on: review by another lab, keeping the Mac awake while threads work, Connectors (opened once you're done) and the app's look. Done opens a new thread, ready for your first message.

Help > Set Up Threadbear brings the cards back. Help > Take the Tour shows you round the window, one part at a time: the window dims, one part lights up, and a card beside it says what it is, with an ⓘ that opens its page of these docs. A few made-up sample threads give it something to point at: a sample's row with its star, moon and box out, your views down the left, Highlights, moving a panel, and an example patch's button, Roll a die (it lives in ~/ThreadbearThreads/Welcome). The samples are deleted when the tour ends. A Mac that joined a Threadbear you already use (setup's --existing) skips both, as does one that finished the tour in the Mac app.

While that first thread works, Finish setting up shows what's left after setup:

  • Start your first thread, which shows your Claude Code or Codex login works. If there's no login on the Mac yet, it says how to add one.
  • Pair your iPhone, so you can ask questions and steer your threads while you're out (see Your phone and a browser).
  • Open your website, to check on your threads from any browser.

Each item ticks itself off once it's done, and the list's icon on the left-hand rail goes once they all have, with confetti if the list is open when the last one ticks. Hide this list puts it away, and Help > Finish Setting Up brings it back. The phone and website items only show when your Threadbear has a Convex deployment for them to use.