The treacle reference.
Everything treacle does, how to turn it on and what it will refuse. The source is closed, so this page is the reference. The homepage has the tour, and treacle doctor on your Mac says where your own setup stands.
Install
curl -fsSL https://treacle.dev/install | sh
macOS on Apple silicon, or Linux on x64 or arm64 (a 64-bit OS; on a Raspberry Pi, the 64-bit Raspberry Pi OS). The installer picks the build from uname, puts one binary in ~/.treacle/bin and links it into /usr/local/bin when it can. Otherwise it adds ~/.treacle/bin to your shell's PATH between marked lines, once. Before anything lands it checks two things: the download's SHA-256 against the release manifest, and its signature. On macOS that is treacle's Developer ID (app.treacle, team GXD2K5H977). On Linux it is treacle's Ed25519 release key over the file, the build and that SHA-256, checked with openssl. If either fails, nothing is installed. Read the installer before you pipe it.
You need tmux, git and at least one agent you already use: Claude Code, Codex, or anything that runs in a terminal. Nothing else is needed to reach it from your phone: setup offers your own Cloudflare domain, a temporary address, or Tailscale if you already use it.
Setup and devices
treacle setup
Run it on the machine that stays on. It installs the server as a service (launchd on macOS; a systemd user unit on Linux, with linger so it starts at boot and outlives your login: if setup says otherwise, run sudo loginctl enable-linger $USER), sets up your phone's way in, and ends with a QR code for the phone. Run it again at any time; it only does what is missing. treacle qr makes a fresh QR.
- Your phone's way in. The phone pairs with the host the way a second machine does: the QR carries a one-time code and a fingerprint of the host's key. After that the app runs over one WebSocket sealed end to end (X25519 and AES-256-GCM). Only the host's pairing listener is public; the app, its API and its token stay on the machine. Setup offers three routes, in this order:
- Your own Cloudflare domain. A free Cloudflare account with a domain on it. Setup runs
cloudflared tunnel login(pick the domain in the browser), creates a tunnel namedtreacle-<machine>, points the name you choose, such astreacle.example.com, at it, and records it inconfig.jsonassatellites.tunnel. The address never changes. - A temporary address. A Cloudflare quick tunnel on
trycloudflare.com, with nothing to sign up for. Its address changes when cloudflared or the host restarts, and the phone then needs a new QR.treacle doctorsays so while it is in use. - Tailscale, if the host and phone are already on a tailnet. Setup serves the app there with
tailscale serve, and the QR carries the token.
- Your own Cloudflare domain. A free Cloudflare account with a domain on it. Setup runs
- Desktop. Open the address in Chrome and install it as an app. It gets its own window, a Dock badge counting the inbox, and a Dock menu. Or install Treacle for Mac, a signed and notarized app that pairs like a phone: paste the link from Host → add a device.
- Phone. Scan the QR with the camera. It pairs and opens the app; then Share → Add to Home Screen. Push needs iOS 16.4 or later and the home-screen app. The Host page lists paired devices, with + add a device for another and remove to cut one off. A laptop or desktop pairs the same way: open the link under the QR in Chrome.
- iPad. The same app, with the terminal view and a key bar.
- Folders. Register repos with
+ folderin the app ortreacle repo add <path>. Board work is only ever cut from registered repos.
The inbox carries a getting-started guide until you finish it: add a folder, send a test push, install the plugin, start a first session.
treacle permissions asks macOS for everything agents tend to need in one sitting: Full Disk Access, Accessibility, Screen Recording and Automation. --check only reports. Linux has no such grants, so there it says so and does nothing.
On Linux with Tailscale, its daemon runs as root. Run sudo tailscale set --operator=$USER once so setup may bring it up and serve treacle over HTTPS.
Claude Code plugin
treacle install
Writes one Claude Code plugin to ~/.claude/skills/treacle, which every new session loads as treacle@skills-dir. It carries the status hooks, the MCP server and the treacle mod. Its hooks and MCP run the installed binary, so moving a checkout or updating cannot break them. Installing again is safe, and it removes anything older versions registered, so no hook fires twice. treacle doctor checks it. The server brings the mod up to date when it starts on a new build.
- Status hooks (Notification, Stop, UserPromptSubmit, SessionStart) flip a session's lamp to needs you the moment Claude waits on you. Without them, sessions still get working and idle from what the pane shows.
- The mod reports turns from inside Claude Code and submits your messages directly instead of typing them into the pane. If a submit is refused, for example while Claude Code is stopped mid-turn, the message is typed in instead. It also holds pasted keys out of the chat (see Secrets), and forwards Claude Code's You should know notices as notifications.
Commands
| command | what it does |
|---|---|
treacle setup | Installs and starts the server, sets up your phone's way in (your Cloudflare domain, a temporary address, or Tailscale), prints a QR. Idempotent. |
treacle install | Installs or refreshes the Claude Code plugin. |
treacle doctor | Reports every setup step, including whether the tailnet has HTTPS and whether a device has reached the host. |
treacle qr | A QR that pairs a phone over your route (on a tailnet, the address and token). |
treacle status | Whether the token is set, whether the local server answers, and which clients are connected. |
treacle permissions [--check] | Asks macOS for the grants agents need, or only reports them. Nothing to do on Linux. |
treacle repo add|remove <path>, treacle repo list | Registers a git repo, or stops managing one. Removing leaves the checkout untouched. |
treacle voice install | Downloads the whisper.cpp base model (about 148MB) for on-host dictation. |
treacle slack connect [--channel <name>] [--anyone] | Wires a Slack channel to the desk. Also slack status and slack disconnect [<channel>]. |
treacle secret set <NAME>, treacle secret forget <NAME> | Stores a secret in the Keychain (on Linux, ~/.treacle/secrets), typed unseen or read from stdin. Used by webhooks. |
treacle memory seed|list [kind]|search <words>|contexts | Fills, lists and searches the memory vault. |
treacle hosts, treacle hosts add, treacle hosts remove <host> | On the host: lists the machines joined to its desk, makes a one-time join command, or removes one. |
treacle join <address> <code>, treacle leave | On another machine: sets it up if needed and joins it to a desk, or forgets the desk. |
treacle update [--check | --rollback] | Installs a newer build, verified, or puts the previous one back. |
treacle --version | Version and build id. |
Sessions and the feed
Every tab is a tmux session on a tmux server treacle runs for itself, so shells survive restarts and can be attached from any terminal. The app shows a Claude Code or Codex tab as a feed: tool calls as one-line rows, edits as diffs, replies as rendered Markdown, questions as cards. The raw pane is behind term in the session header, and it is the same pane.
- Home opens on the inbox of sessions that need you, then every repo and worktree. Session rows show what changed: unread turns, files touched, commits not on main, today's spend. Home can also group sessions by state: needs you, working, ready to review, idle.
- Lamps: working, needs you, idle, starting, asleep, stuck. The first time a less obvious lamp appears, it explains itself in one line.
- Compose types into the session, or submits through the mod. While a dialog is on the session's screen, a message waits until it is answered. Send becomes stop while the agent works. A queued message can be sent now without cancelling the running command.
- One-tap replies. A command Claude suggests runs with one tap. A finished turn that hands a decision back offers its options as replies. Multi-part questions are answered part by part.
- Fork. Every message has a fork button. The conversation up to that message becomes a new tab, in the same worktree or a new one cut from main. The original transcript is only read.
- Changes. The changes sheet lists files against base. A hunk opens its whole file with the added lines marked. Tapping a line adds a review comment, and the comments go to the session as one message, each naming its file and line.
- Documents and media. Plans and docs the agent writes or shows open in a reader that copies or saves. Images, HTML reviews (with their screenshots), audio and video the agent links render in place.
- Workflow runs. A Claude Code Workflow gets a screen of its own: phases, the agents under each with duration, calls and tokens, and each agent's transcript as a read-only feed.
- Spend. The session info screen shows spend for this conversation, today across the worktree, and the worktree in all.
- Subject lines. Each active worktree carries one line about what is happening in it, written by the small model on your host. It is refreshed at most every half hour.
- Tickets and PRs. A branch named the Linear way (
hbr-212-…) links its ticket whenlinearWorkspaceis set. AddlinearApiKeyand the pill also shows the ticket's title and status. The PR comes fromgh, with its checks and review state. PRs, tickets and worktrees named in a chat are links.
MCP tools
Every Claude Code session in a treacle tab gets these tools. Panels are labelled with the worktree and tab they came from, and land in the session's timeline, so they survive reconnects and restarts.
| tool | what you see |
|---|---|
show_document | Markdown in the reader, from content or a path. |
show_diff | A unified diff, coloured. |
ask_choice | Option cards. Blocks until you answer or it times out. Dismissing reports a dismissal, not an answer. |
ask_approval | A Markdown proposal with Approve and Reject. Blocks; a typed reply comes back as revision feedback. |
update_plan | A live checklist pinned to the session screen. |
show_preview | A dev server on the host, proxied into the feed behind your auth, or a folder of files Treacle serves itself, with byte ranges so audio and video play and seek. Lasts about six hours. |
notify | A toast, or a push when the app is closed. |
work_task, work_report | The board task this session runs, and evidence back to it (see The board). |
memory_search, memory_read, memory_list, memory_propose | The memory vault, limited to the contexts the session's repo can see (see Memory). |
The desk gets its own tools on top (desk_board, desk_sessions, desk_send, desk_action, desk_jobs, desk_host, desk_loose_ends and others). The server refuses them to any caller that is not the desk.
Permission cards
TREACLE_REMOTE_PERMISSIONS=1 claude
Per session. Bash calls that would prompt become Allow or Deny cards in treacle, with the full command. A permission prompt that nothing announced still reaches the phone as a card. After a timeout, a dismissal, or with no treacle client connected, the normal terminal prompt takes over. Nothing is ever auto-approved. Without the variable the hook does nothing.
Worktrees and tabs
- New worktree. A branch name and a base, which defaults to main. The worktree is cut from the remote's state, not from wherever the checkout last fetched. A Linear-style name links its ticket. By default worktrees live in
~/.treacle/worktrees/<repo>/<branch>. SetworktreeRootto"{repo}/.treacle/worktrees"to keep them under each repo, where asdf, mise or nvm still see its tool pins. - New tab. Terminal, Claude, Codex, or any launcher you define, with an account if you have several. On a desktop, "+ term" opens a shell in the same worktree beside the session, side by side or stacked, and every pane boundary drags.
- Apply back. "→ main" on a branch worktree lists the commits main lacks and cherry-picks the ones you pick onto main, after a slide-to-arm confirm. The repo's checkout must be on main and clean. A conflict aborts and leaves main as it was. Nothing is pushed.
- Delete. Refused while anything runs in the worktree or it has uncommitted changes, and it says which. Type CLOSE to override.
- Resume. A worktree with no tabs left offers to resume its last conversation.
- Moving repos. A repo can move on or off an external drive without breaking its worktrees. A registered repo that has gone missing says so, with relink and forget. Codex history follows a move.
- Quiet folders. Folders with nothing going on for a day fold away behind one row.
Accounts and presets
Each Claude profile is a separate login. The account picker shows each one's 5-hour and 7-day usage and marks the one with the most room left. A start that names no account takes that one. When Claude Code reports Usage limit reached, or a window passes 95% while a session works, a card offers the other accounts with their headroom. One tap resumes the conversation on the one you pick. A session stopped at its limit shows as waiting, with the reset time.
Presets name a launcher, an account and Claude Code's --model, --effort and --permission-mode. Edit them in Settings or on any launch sheet, where they sit on top. The server expands a preset name into its launcher and flags, so nothing typed on a phone reaches a shell. The session panel shows what an agent was actually started with, read off its process. Sleep and restart keep those flags.
"presets": [
{ "name": "deep", "launcher": "Claude", "model": "opus", "effort": "high", "permissionMode": "plan" },
{ "name": "quick", "launcher": "Claude", "model": "sonnet", "permissionMode": "acceptEdits" }
]
Sleeping sessions
An agent nobody has used for two hours quits to free its memory, and the tab and its conversation stay. It only sleeps when it is idle: not mid-turn, nothing waiting on you, nothing half-typed, no command running under it, and nothing uncommitted in its worktree. The three most recently active sessions and the desk stay up. Opening it, sending it a message, or a board action aimed at it resumes it with claude --resume or codex resume. Sleep now in the session sheet does it straight away, with the same checks, and says why when it will not.
"sleep": { "afterMinutes": 120, "keepWarm": 3 } // afterMinutes: 0 never sleeps anything
Voice and files
- On-host dictation.
brew install whisper-cpp ffmpeg(on Linux, ffmpeg from your distro andwhisper-clibuilt from whisper.cpp), thentreacle voice install. Hold the mic, speak, release, and the text lands in the compose box for a glance before you send. Audio stays on your machines. - Streaming dictation. Enter a Deepgram key in the app's settings, and words appear as they are heard. The host relays the audio to Deepgram's live API. The key is checked with Deepgram, then kept in the host's config; devices only learn whether one is set.
- iOS dictation works in the compose box with no setup.
- Files. + uploads photos, files and videos up to 2GB to
~/.treacle/uploads, streamed to disk, and sends them with your message. In the terminal view the path is typed and you press Enter.
Secrets
Paste an API key or token into a message, from the app or in Claude Code itself. The treacle mod stores it in the macOS Keychain (on Linux, a file in ~/.treacle/secrets that only your user can read, as with an SSH key) and passes Claude a placeholder such as ‹secret:CLOUDFLARE_API_TOKEN_3FA2›. Claude runs commands with it through the use_secret tool, which hands the value over on stdin or in an environment variable. Tool output is scrubbed of held values, and Bash may not read the stored entries back. A key sent from the phone never reaches tmux or the feed.
Claude Code still writes the raw prompt into a local queue row of its transcript before plugins run. That row stays on your machine and is not sent to the model.
The board
A task is work that has to be finished, not a conversation. It has a title, a done when, an intent, ideally a check command, an agent, a model, and a base ref. It can also carry screenshots, grant global skills, wait on other tasks, and be blocked with a reason.
- Lanes, left to right: proposed, next up, in progress, needs you, blocked, done today. On a phone, one list, most urgent first. A scheduled fold holds the desk's jobs.
- Start cuts a worktree from the base, writes the brief to
.treacle/task.md, launches the agent and sends the opening message. - Evidence. The agent reports with
work_report: a note, links, ordone. Done runs the check in the worktree and moves the task to review with the result. - Attempts. The task view lists each attempt: its session, whether that session ever talked, and its worktree's tabs, or that they are gone.
- Stalls show under needs you. A branch rebased through a conflict before landing still reads as merged.
- Finishing. Accepting a task whose work has landed offers to remove its worktree.
Review and second opinion
In review, the task shows the evidence, the check's result and the changes against base. The base is whichever of the local and remote base branch is newer, so a stale local main never inflates the diff. Accept it, or send it back with a reason.
When an attempt enters review, a headless reviewer reads its diff, read-only in its worktree, and pins its concerns to the card: reviewing, N concerns, unavailable, or failed. The task screen lists each concern by severity, file and line, and a location opens the diff there, with a GitHub link when there is a PR. Set the reviewer per project: auto (the default: the other agent from the one that built it), Codex, Claude, or off. "ask again" re-runs it. Nothing waits on it, and a reviewer that is missing or signed out shows as unavailable instead of passing silently.
Concerns go back to the session that wrote the change, as a message listing each one, so it can fix them with its context intact and record what it changed. They are sent only while the task is still in review on that run, in the same conversation, with the agent in its pane and no dialog up, and not to a session on a joined machine; otherwise the card notes why they stayed there.
Delegate
⌘⇧D (Ctrl+Shift+D off a Mac) turns the selection or the clipboard into a task. It opens one prefilled confirm sheet, then drafts, promotes and starts the task, cut from the branch of the worktree on screen. An installed Chrome app cannot hold a system-wide hotkey, so the shortcut works inside the app. The Dock menu's Delegate from clipboard uses the worktree you last had on screen.
The desk
One Claude Code session treacle keeps for itself in ~/.treacle/desk, outside every worktree. It reads the board and the live sessions, says what matters, and drafts tasks for work that is missing. It starts nothing, types into nothing, and changes no task without a card you answer. Asking it in chat counts as that answer; an idea of its own still gets a card. It uses the same paths and guards as the app's own buttons, and it gets no way into a pane that you do not have.
- Digests lead with one next action and at most three more, carry only what is new or changed, and send nothing while nothing moves. They back off while things stay quiet. Snooze holds an item until Monday; known holds it until it changes.
- Loose ends: review tasks whose PR merged, runs with nothing new for days, clean merged worktrees of finished tasks, needs-you flags that are only notices, and old drafts. They come on one card with a tick per item. Standing rules can close some kinds without a tap; each is off by default and logged.
- Budget. Automatic wakes stop once the desk has used a daily token ceiling (400k output tokens by default,
desk.dailyTokens). It runs on Sonnet by default (desk.model). - Where. The desk is one view. On a desktop its chat sits on the right, and the pane beside it switches between overview, board and host; the split and the pane are remembered. On a phone the desk tab has the same switch, with chat as one of its choices.
Turn it on by adding a "desk": {} block to config.json, or let treacle slack connect add it. Once it is on, start it from its card on the board.
Scheduled jobs
A job is an instruction to the desk plus a daily time (optionally on some weekdays) or an interval. When it falls due, the server gives the desk the instruction with a picture of the board and the sessions. The desk does the job and reports with desk_job_report, to the phone, into the next digest, or both. Manage jobs from the board's scheduled fold (add, edit, pause, run now, delete) or by asking the desk. A job may start the desk but never types into it mid-turn: it retries for 30 minutes, then tells you it gave up. A run missed by more than an hour while treacle was down is skipped. Jobs live in ~/.treacle/jobs.json.
Slack
treacle slack connect
Your Mac has no public address, so treacle reads the channel with Slack's API instead of receiving events. It needs one bot token, with no event subscription and no socket-mode token. connect opens a prefilled app manifest, takes the bot token after you approve the install, picks and joins a channel, then waits for you to say something there. From then on only you reach the desk, unless you passed --anyone. It offers to turn the desk on if it is off. No restart needed.
- Messages go in like the compose bar's. The desk's reply goes back to the channel that asked.
- Digests post the single most blocking item, with reply words that act on it:
accept,close,remove,snooze,known,more. Details only appear in its thread, onmore. - Quiet hours default to 22:00–08:00, and posts are rate-limited per hour (
slack.quietHours,slack.postsPerHour). Memory notes about a client never go where Slack can hear them.
Webhooks
Linear and GitHub events can draft board tasks or tell the desk. Store each signing secret with treacle secret set, add a trigger to config.json, and restart the server. The /hooks/ routes need no bearer token, but every call must carry a valid signature or it is refused with a 401. They need a public route to your host, such as tailscale funnel.
Linear
treacle secret set LINEAR_WEBHOOK
"webhooks": [
{ "id": "linear", "source": "linear", "secretName": "LINEAR_WEBHOOK",
"project": "harbour", "teams": ["HBR"], "labels": ["treacle"], "then": "draft" }
]
Point a Linear webhook for Issues at https://<host>/hooks/linear. Each call needs a valid Linear-Signature and a webhookTimestamp within a minute. A new issue matching teams and labels drafts a task titled with its ticket id, so its branch links the ticket. "then": "start" also starts it, with the trigger's agent and profile. Redeliveries are ignored.
GitHub
{ "id": "github", "source": "github", "secretName": "GITHUB_WEBHOOK",
"routes": [
{ "repo": "harbour-co/harbour", "on": ["issue_opened"], "to": "task", "project": "harbour", "labels": ["treacle"] },
{ "repo": "harbour-co/harbour", "on": ["review_requested"], "to": "desk", "reviewers": ["tidepool"] },
{ "repo": "harbour-co/*", "on": ["ci_failed"], "to": "desk" }
] }
Point a JSON webhook at https://<host>/hooks/github with Issues, Pull requests and Workflow runs. Store the same secret with treacle secret set GITHUB_WEBHOOK; a GitHub trigger only takes a secretName. The first route whose repo (exact, or owner/*), on and filters match takes the event; anything else gets a 200 and is ignored. Replays are caught by delivery id for 30 days. A task is never drafted twice for the same issue, review or failed commit, and the desk hears about the same thing at most once in 12 hours.
Event text is untrusted. A task's brief quotes it under a line saying it came from GitHub and is not instructions. The desk gets it as one shell-inert line, recorded as treacle's turn, not yours.
Memory
A vault of Markdown notes with wikilinks in ~/.treacle/memory. It is Obsidian-compatible, so you can open it there too. Each folder has a context: general, personal, work, client/<name>, or unclassified. The server works out each caller's context from its worktree's repo and filters every search by it, so one client's notes never reach another client's session.
- Sessions and the desk search, read and list it, and propose notes. Nothing is saved without a card or your own quoted words. Secrets are refused.
treacle memory seedfills it from the board, your registered repos,~/.claude/CLAUDE.md, Claude Code's per-project memory and the desk's notes. Projects are placed by the rules incontexts.json; the rest stay unclassified until you place them.
Host monitor
Every minute, without extra privileges, treacle samples memory, swap, CPU load and disk on the Mac and keeps eight days of history. Processes are grouped into agent sessions, browsers, build tools and other, and each is attributed to the session whose pane started it. Only a scrubbed program name is ever stored.
- Episodes. Two samples over a threshold open an episode and push once, again only if it goes from tight to critical, and once more when five samples are back to ok.
- The Host page shows the level, four tiles, hour/day/week charts, and the lists of worktree sizes and large caches. Those are measured every three hours at the lowest priority.
- Suggestions (browser tabs eating memory, spare worktrees, caches with a proper clear command, idle heavy sessions) each raise a card on the desk and are checked again before acting.
Ratings fit the machine. Each reading is judged against the machine's own size, so a big laptop and a small VM are rated by the same rules:
- Memory is the kernel's own "memory free" level. At 25% or less, memory is short (tight); at 12% or less, critical.
- Swap counts only while memory is short. macOS keeps swap it no longer needs, so swap with memory free is history, not pressure. While memory is short, swap is tight at 15% of RAM and critical at 30%, or tight when it grew 0.5 GB in the last five minutes and critical at 1.5 GB.
- CPU is the five-minute load per core: tight at 1.5, critical at 2.5.
- Disk is short below the smaller of a fixed amount and a share of the disk: tight under 30 GB or 15%, critical under 15 GB or 7%, whichever is less. A 28 GB VM with 25 GB free is fine; a 2 TB disk with 20 GB free is not.
Alerts, the desk's digests and the lamp all use this rating. A joined machine still on older rules is re-rated by the host from its latest reading, and its alerts for a metric that rates ok here are dropped. An old swapUsedGb setting is ignored.
"health": { "thresholds": {
"memFreePct": { "tight": 25, "critical": 12 },
"swapRamPct": { "tight": 15, "critical": 30 },
"swapClimbGb": { "tight": 0.5, "critical": 1.5 },
"loadPerCore": { "tight": 1.5, "critical": 2.5 },
"diskFreeGb": { "tight": 30, "critical": 15 },
"diskFreePct": { "tight": 15, "critical": 7 } } } // the defaults
More machines on one desk
A laptop that is not always on can join the host's desk. Its sessions show on the same board, sessions list and inbox, labelled with the machine, and you start, message, answer and sleep them from the phone or the host as if they were local. treacle hosts add on the host, or + add a machine on the Host page, prints a command with a one-time code that lasts ten minutes:
treacle join https://mini.tail0000.ts.net:8443 BKPF-54E8-CV0G-EHSX-VXHM-BCBX
The laptop needs treacle and nothing else. It never listens; it holds one outbound WebSocket to the host, sealed end to end with X25519 keys that the code pins, so whatever carries it sees ciphertext. It takes the same route as your phone: your Cloudflare tunnel when setup made one, so the laptop needs no tailnet and its address never changes. Without one, the route is tailscale serve on port 8443, reachable from your tailnet only, and for a laptop off the tailnet treacle hosts add --public turns on Tailscale Funnel for the same address when the tailnet allows it, or a cloudflared quick tunnel that treacle fetches, checks against GitHub's checksum and its signature, and runs itself. Every route is fetched through before its join command is printed. Only a listener that answers pairing and the link is exposed; the app is never on it.
A closed lid or a dropped network marks the laptop offline within a minute; its sessions stay on the board marked offline, and it rejoins on its own. The desk, digests and scheduled jobs cover every joined machine. Each machine watches its own memory and disk, but only the host speaks: a laptop's alerts are pushed from it, its clean-up cards are asked on its desk, and the Host page switches to any machine's full readings. A satellite session's raw terminal is not carried over the link yet.
A project can live on a joined machine. Pick the machine when you create or edit the project and give the repo's path there; it must be registered on that machine. Its board tasks are then cut, briefed, started and checked there, the card names the machine, and the agent's report reaches the host's board through the link. A task whose machine is offline will not start, and says why.
Notifications
Tap the bell in the app's header to turn on Web Push. It needs the HTTPS setup, and on iOS the home-screen app. Pushes fire only while the app is not open: when a session needs you, a decision opens, the host gets tight, or an agent calls notify. Tapping one opens that session. While the app is open, it chimes and raises a system banner instead; the speaker button mutes the chime. The ✕ on an inbox row means dealt with: the session goes back to idle, and a waiting question is told it was dismissed.
Updates
treacle update fetches the release manifest from treacle.dev and installs a newer build after checking its hash and signature. The previous binary is kept for treacle update --rollback. The app shows a banner when a newer build exists. "updates" in config.json is "ask" (the default: tell you and wait), "auto" (install and restart, but only when no agent is mid-turn) or "off". The check is a plain GET for a public file and carries no token or identifier.
config.json
~/.treacle/config.json. Setup writes the first few keys; the app's settings write most of the rest.
| key | what it sets |
|---|---|
port, host, token | Where the server listens, and the bearer token every request needs. |
phoneUrl | The tailnet address setup printed, reused by treacle qr when Tailscale is your route. |
nativeRepos | Registered repos (treacle repo add). |
repoScanRoots | Where + folder looks for repos. |
worktreeRoot | Where worktrees are cut; {repo} stands for the repo's directory. |
launchers | What + tab offers: a label and a command. |
presets | Named launcher, account, model, effort and permission mode. |
models | The models the session panel offers. |
linearWorkspace, linearApiKey | Ticket links, and their title and status. |
updates | ask, auto or off. |
desk | Present means the desk is on: launcher, model, profile, dailyTokens, standing rules. |
slack | Written by treacle slack connect; digests, quietHours, postsPerHour. |
voice | provider (deepgram or whisper) and deepgramKey. |
webhooks | Linear and GitHub triggers. |
sleep | afterMinutes and keepWarm. |
health | Host monitor thresholds. |
satellites | How phones and joined machines reach this one: tunnel (id, hostname, credentials; the named tunnel setup made on your Cloudflare account, used first), route (auto, named, tailnet, funnel, cloudflared or off), url for an address you route yourself, port for the listener they reach. |
Files on the host
Everything lives in ~/.treacle. Delete it and treacle forgets you; your repos, worktrees and tmux sessions are untouched.
| path | holds |
|---|---|
bin/treacle | The binary: server, CLI, MCP server and hooks in one. |
config.json | Settings (above). |
events.db | Every session's timeline, so the feed survives reconnects and restarts. |
work.db | The board. |
host.db | Eight days of host samples. |
subjects.db | Worktree subject lines. |
push.db, vapid.json | Push subscriptions and keys. |
desk/ | The desk's working directory and notes. |
memory/ | The memory vault. |
jobs.json | Scheduled jobs. |
asleep.json | Which sessions are asleep. |
uploads/ | Files sent from your devices. |
worktrees/ | Worktrees, unless worktreeRoot says otherwise. |
server.log | The server's log, including [sleep] lines. |
Limits
- Host: macOS on Apple silicon, or Linux on x64 or arm64. No Intel Mac build. Windows only inside WSL 2 with systemd turned on; WSL stops when Windows sleeps. On Linux there are no privacy grants to ask for, held keys live in a 0600 file rather than a keychain, and dictation needs a whisper.cpp you build yourself. Any browser that installs a web app works as a client.
- Source: closed. The binary is free to use, personal or commercial, on machines you own or administer, but may not be redistributed or rehosted.
- Only tabs with a live tmux session appear in the app. A shell started outside treacle (or with
TREACLE_NO_TMUX=1) shows as legacy and cannot be driven; close and reopen the tab. - Claude Code gets the richest integration. Codex gets a feed and question cards. Other agents run in a Terminal tab with the raw pane.
- The ⌘⇧D shortcut only works while the app is focused.
- Webhooks need a public route to your Mac. Everything else works inside your tailnet.