santree
AGENTS.md14 starsChanged 4 months agoMITView on GitHub
Guidance for working in this repo. Keep it accurate as the code changes. santree — a macOS desktop app for managing AI coding agents across a repo's tickets. Tauri 2 + React 19, with a fully-typed Rust ↔ TypeScript bridge (tauri-specta). Shipped via GitHub Releases with a built-in updater, but with ~zero external users — prefer deleting dead/old code over keeping shims. The exceptions, now that installs update themselves: the updater contract (the pubkey and endpoints in tauri.conf.json, the update_channel…
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository6 other files it gives its agents.
- new-commandSkill
- production-reviewSkill
- verifySkill
- new-commandSkill
- production-reviewSkill
- verifySkill
The file
We split this AGENTS.md into the rules it gives an agent
11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Views: all of them — Triage, Issues, Trees, Reviews, Settings, Terminal — are backed by real data.
- Distinctive: line 52
Correctness over cleverness: No hacky things that break later.
- Very specific: line 119
No mock data: When a backend isn't connected the command returns an empty result (e.g.
- Distinctive: line 455
Run-in-background, the graph node's menu, Launch, and the workspace's own "Start a task".
- Very specific: line 622
Data: every read is a hook in lib/queries.ts.
- Very specific: line 625
Errors & background events: every failed read and write is logged under its key and surfaces as a red toast — one policy, …
- Very specific: line 662
Colors: never hardcode hex in components — use theme/colors.ts (successColor, LINEAR_BRAND, JIRA_BRAND, alpha(), statusColor) or a CSS …
- Very specific: line 714
Before finishing a change: run the /verify skill (or at minimum its static gates: cargo fmt --all --check, cargo check/clippy, pnpm …
- Distinctive: line 727
Don't grow them back. A new test must protect something a reader can't see from the code.
- Very specific: line 782
The beta manifest is rolling: Every release — stable included — re-uploads latest.json to the fixed updater-beta pre-release.
- Very specific: line 892
External CLI contracts: verify vendor flags against --help, don't guess.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
Guidance for working in this repo. Keep it accurate as the code changes.
What this is
santree — a macOS desktop app for managing AI coding
agents across a repo's tickets. Tauri 2 + React 19, with a fully-typed
Rust ↔ TypeScript bridge (tauri-specta). Shipped via GitHub Releases with a
built-in updater, but with ~zero external users — prefer deleting dead/old code
over keeping shims. The exceptions, now that installs update themselves: the
updater contract (the pubkey and endpoints in tauri.conf.json, the
update_channel setting) and the SQLite migrations are real compat surfaces —
an installed app will meet their future versions.
Views: all of them — Triage, Issues, Trees, Reviews, Settings, Terminal — are
backed by real data. No view ever renders sample data; when a backend isn't
connected (no Linear workspace or Jira site, no gh auth, no repo path) commands return real-but-empty
results and the view shows its empty state. The one sample lives outside the views:
prompts::preview renders a template against a built-in sample ticket so the prompt
editor can re-render on every keystroke without a fetch.
Trees is the workspace; Reviews is the inbox. A PR you opened is worked on in Trees, beside its worktree and its agents (the right panel's PR and AI-work panes). Reviews carries the PRs waiting on your review — other people's. That split is load-bearing for where new PR work goes; see "Key patterns".
Terminals outlive the app on a signed build. santree launches a detached
santree-server that owns this Mac's PTYs, so a quit, a crash or an update never
ends an agent or a setup script; unsigned and dev builds keep in-app PTYs
unless opted in (SANTREE_SERVER=1). terminal.rs runs on the
sessions::Terminals facade; liveness consumers honour Liveness.complete (an
unreachable server is "unknown", never "exited"), and agent hooks name a stable
<app_data>/bin/santree-hook copy. The tables santree-hook writes are a
compatibility surface: migrations on them are additive only. docs/server.md is
the source of truth, with the Status table and the Unverified list (nothing of it
has run on a signed build yet; the first release with it is a beta tag). Read it
before touching terminals, crates/host, crates/server, or src-tauri/src/{sessions,server}/.
The hidden Dev tab (dogfooding: build/install santree from inside santree, cut
a release, bug TODO list) was removed before the public release, along with the
cross-repo Agents landing view it sat beside. / now redirects to /trees, whose
empty state is the welcome surface. Its migration (0017_dev_todos) is still in
the directory on purpose — sqlx fails to start against a DB that recorded an
applied version the resolved set no longer has — and 0028 drops the table.
Goal & priorities (in order)
- Snappy, native-feeling UX. Optimistic updates + async execution everywhere a user acts — patch the cache/UI immediately, reconcile in the background, roll back on error. Never block the UI on a round-trip.
- Correctness over cleverness. No hacky things that break later. When something non-obvious is necessary, leave a short comment explaining why (not what).
- Clean, legible code. Reuse shared primitives/hooks; don't duplicate logic. Match the surrounding style. Avoid comments that just restate the code.
- The typed bridge is sacred. The frontend never calls
invokeor hardcodes data — it goes through query hooks → generatedbindings.ts→#[tauri::command].
Tech stack
- Rust: Tauri 2.11, tauri-specta
=2.0.0-rc.25(pinned withspecta/specta-typescript— bump all three together), sqlx + SQLite, portable-pty, tokio, reqwest, serde, anyhow,log+ tauri-plugin-log (file logging — Rust + JS console to~/Library/Logs/com.santree.desktop/santree.log). - Frontend: React 19, Vite 8, TanStack Router + Query v5, Tailwind v4 (CSS-first,
no
tailwind.config), xterm.js, react-markdown, refractor (Prism) for syntax highlighting, mermaid (dynamic-imported — never in the startup bundle). Biome for lint+format. Vitest. - Cargo workspace:
src-tauri(the backend: the Tauri adapter plus the integrations and services it drives) +crates/core(pure domain- static config, no Tauri dep) +
crates/pty(PTY manager, Tauri-agnostic) +crates/hook(the bundledsantree-hook: Claude hooks, status line, MCP server) crates/remote(santree-remote-client: the link to Daedalus through the local Daedalus agent's socket, Tauri-agnostic)crates/remote-proto(santree-remote-proto: protocol v1's types) +crates/remote-tls(santree-remote-tls: the session host's pinned TLS 1.3 profile — the engine's; santree itself doesn't depend on it) +crates/agent-kind(santree-agent-kind: theAgentKindenum, re-exported bysantree_core::domain) +crates/host(santree-host: protocol v1 served — the local server's and the test daemon's host; Daedalus's session host to adopt it) +crates/server(santree-server: the local server binary — santree-host on a unix socket, built with--profile server(panics unwind); itsREVISION(1 shipped in 0.1.19-beta.1; 2 in 0.1.19-beta.2) is pinned byrevision.lock: when its code or linked crates change, bump it if a release carries it, then runUPDATE_REVISION_LOCK=1 cargo test -p santree-server revision; docs/server.md "Versions and draining").
- static config, no Tauri dep) +
- Crates the daedalus engine consumes:
santree-pty,santree-remote-proto,santree-remote-tlsandsantree-agent-kindare depended on by git rev from the daedalus engine repo, so their public API and their dependency list are a contract. None may depend onsantree-core, Tauri, or (by default) specta —AgentKind'sspecta::Typesits behind thespectafeature, which onlysantree-coreturns on.santree-remote-tlsuses ring as its only crypto provider, passed explicitly (no aws-lc-rs in its tree, never the process default). The engine builds them with nix on an older rustc thanrust-toolchain.tomlpins, so they declarerust-version = "1.95"and must keep building on it. They are the only code that runs on Linux (the engine's box): ci.yml'sengine-linuxjob clippies and tests them there and checks them on rustc 1.95. The app itself is macOS-only — no Linux code or tests outside these crates.santree-hostis not consumed yet but carries the same contract (rust-version = "1.95"; no santree-core, Tauri, specta, transport or crypto). The#[allow(clippy::disallowed_methods)]attributes insantree-ptyandsantree-hostmark this workspace's sanctioned PTY sites; they are inert in the engine, which has no suchclippy.toml.santree-pty'sOpenOptsgainedbase_envand its sinks are nowSend + Sync: the engine's session host must move tosantree-hostin the same rev bump.
Architecture & data flow
React view → query hook (src/lib/queries.ts) → bindings.ts (generated)
→ #[tauri::command] (src-tauri/src/commands.rs)
→ live backend (tracker.rs → linear.rs | jira.rs / db.rs / repo.rs /
settings.rs / terminal.rs / github.rs / reviews.rs)
└─ when not connected: return real-but-empty (no sample data)- No mock data. When a backend isn't connected the command returns an empty
result (e.g.
live.unwrap_or_default(),Ok(vec![])) and the view renders its empty state.crates/core/src/config.rsholds the only static data — real canonical config, not samples: the agent catalog, stage metadata, default settings. This also bans hardcoded placeholder field values: if a struct field isn't wired to a real source, derive it or don't render it — never ship a constant (e.g. a fixedInProgress/Idle) that the UI shows as live data. The one sanctioned exception is the screenshot fixture mode (src/dev/fixtures/,VITE_SANTREE_FIXTURES=1 pnpm dev:alt): a fake company answered at theinvokeboundary through a Vite alias of@tauri-apps/api/core, for README and website captures. Dev-only by build-time constants, no view or hook knows it exists, and it never ships — see its README before touching it. Its sibling,VITE_SANTREE_FIXTURES=demo, is a stateful world for recording the product demo (src/dev/fixtures/demo/): a dev-only Vite plugin swapsbindings.tsfor a shim that lays typed overrides overcommandsfor demo repos only, so everything else, Daedalus included, reaches the real backend. CI'spnpm check:no-demofails a build whosedist/carries either world. - Domain types live in
crates/core/src/domain.rsand derivespecta::Type— that's how their shapes reachbindings.ts. Never hand-editbindings.ts(it's generated; runpnpm gen:bindingsafter changing a command orType). - Presentation is the frontend's job. Rust ships plain enums;
src/theme/colors.tsmaps them to colors/labels. The accent is a runtime CSS var so it re-themes live.
Repo structure
docs/terminals.md how terminal emulation works, end to end — the source of
truth for crates/pty, terminal.rs and features/terminal
docs/server.md the local santree server: modes, lifecycle, trust, revisions,
sessions, env, build/sign/release, and a built-vs-planned
Status table — the source of truth for crates/host,
crates/server and src-tauri/src/{sessions,server}/
docs/remote.md Daedalus projects, protocol v1, the link — the source of
truth for crates/remote{,-proto,-tls} and src-tauri/src/daedalus/
docs/web.md the Web tab: its page as a native WKWebView laid over the
app's webview, placement, overlays, keys and focus, and the
Daedalus plan — the source of truth for src-tauri/src/browser/,
src/features/web/ and src/lib/overlays.ts
docs/conversation.md the Conversation view: a Claude tab's live session drawn
from its own transcript, the reader, the journal and the
composer's bounds — the source of truth for
crates/core/src/conversation/, src-tauri/src/conversation* and
src/features/conversation/
crates/core/src/ domain.rs (types) · config.rs (static config/defaults) · linear.rs
+ jira.rs (tracker → domain mapping) · layout.rs (dagre-free graph helpers) · diff_index.rs
(a PR's commentable hunk spans; written by the app, read by the
AI review's MCP server) · conversation/ (the Conversation
view's journal: the contract, `journal.rs`, and `claude.rs`,
Claude's transcript mapped into it) · lib.rs
crates/pty/src/ lib.rs — PtyManager: spawn real process behind a PTY, stream bytes
· ring.rs (a session's recent output + the attach protocol, so
a reload costs the view and not the work)
crates/hook/src/ lib.rs — the bundled `santree-hook` (main.rs only calls `run`):
Claude's session-state hooks + statusLine, and `mcp` mode
(mcp.rs · review_tools.rs), the AI review's draft-comment
tools; `apply` is the same writes over the app's own pool,
for hooks relayed from Daedalus
crates/remote/src/ the client for Daedalus's session host (docs/remote.md):
agent (the Daedalus agent's santree socket, its first line)
· control (the agent's own socket: this Mac's settings)
· transport (the `Connector` seam, `ConnectError` states)
· client · host (reconnect, backoff, hook cursor) · fake
(test daemon — santree-host over an in-memory link — + fake
agent socket)
crates/host/src/ protocol v1 served (`santree-host`): lib.rs (Host, Caps,
Methods, Extension, HostOptions) · conn.rs (a connection: its
bounded queue, pacing, writer) · pty.rs (attach gates,
sessions, input threads) · exec.rs · fsops.rs · hooks.rs
crates/server/src/ the local santree server (`santree-server`): lib.rs (serve,
idle retirement, signals, flood limit, REVISION) ·
endpoint.rs (run dir, the flock that owns the socket and its
repair, the anonymous ready socketpair) · ext.rs
(`server.*`) · peer.rs (who may connect) · logging.rs
crates/remote-proto/src/ lib.rs — protocol v1 as types (re-exported as the
client's `proto`); its tests pin the exact wire text
crates/remote-tls/src/ lib.rs — the session-host link's TLS profile (identity,
pinning verifiers, configs, refusals) · cert.rs (the
self-signed ed25519 certificate)
crates/agent-kind/src/ lib.rs — `AgentKind` + `UnknownAgentKind`
src-tauri/src/ lib.rs (builder + command registration) · commands.rs (thin wrappers)
· tracker.rs (the `TicketTracker` trait: which tracker a repo
reads, and the dispatch every provider-neutral ticket read and
write goes through — see "A repo reads one tracker") · linear.rs
(GraphQL) · daedalus/ (the home server through the local
Daedalus agent: `host` — the live link and the hook relay —
`setup` — its setup scripts there — `agents` — Claude and
Codex there: hooks written on the box, launch resolution,
the box's CLIs and process table — `settings` — this Mac's
own settings through the agent's socket — `history` — its
session history, read from the box's transcripts — plus the
health check and the workspace list over the link)
· sessions/ (where a terminal's process lives and how a pane
reaches it — docs/server.md: `backend` — `Terminals`, the one
facade the commands hold, `Local::{InApp, Server}` + Daedalus —
`ids` — the id registry — `remote` — `RemoteTerminals`, the
remote panes of a local server AND Daedalus, as a `Profile` —
`env` — a pane's env and `baseEnv`; `mod` — `Mode`,
`server_mode()`)
· server/ (the local server's app side:
`LocalServers` ensure/spawn/adopt/respawn, the
signature-checking connector, the supervisor)
· git.rs + git/checkout.rs (`Checkout`: the one seam a repo's
git, reads and writes, and its file access go through, here
or on Daedalus;
`repo::checkout` resolves it — docs/remote.md)
· jira.rs (Jira Cloud REST: `search/jql`, ADF,
transitions, the per-repo triage query) · oauth.rs (the PKCE
flow, keychain token store and refresh both trackers share)
· linear_mcp/ (Linear through its hosted MCP server — the
last-resort connection: `auth` sign-in + refresh, `client`
JSON-RPC, `tracker` the reads, `wire` the tool → domain
mapping; design and fallbacks in docs/linear-mcp.md)
· conversation.rs + conversation/ (the Conversation view's
reader: locate a tab's or a listed session's transcript,
`cache` its parse, `watch` it — docs/conversation.md)
· db.rs (sqlx pool + migrations) · repo.rs · settings.rs · terminal.rs · stream.rs
(setup runs as panes on the terminal facade → read-only log
panes; on a server build a script outlives the app, untracked:
Settings → Terminal lists it and a second run waits for it)
· proc_table.rs (the one `ps` listing, cached 500ms) +
agent_procs.rs (which agent owns each pane's foreground —
identity, never status; see COMPLIANCE.md)
· hooks.rs (the `--settings` file EVERY santree `claude` launch
layers on: session-state hooks, statusLine, English tutor,
the Conversation view's live text while its switch is on; plus
the AI review's deny/allow variant and its `--mcp-config`)
· review_ai.rs (both review prompts + the AI-review launch)
· review_drafts.rs (the AI's drafts, and the ONE path that puts
them on GitHub — on a click, into the user's pending review)
· english_tutor.rs (opt-in writing coach: hook + practice log
+ on-demand analysis)
· accounts.rs (several Claude/Codex logins: a config folder
each, the shared-state links, the launch env — COMPLIANCE.md
"Agent accounts")
· prompts.rs (the prompt engine: embedded defaults, the four
layers, Jinja inheritance — see "Prompt layers") ·
santree_dir.rs (a managed repo's `.santree/`: what santree
owns there vs what the repo commits, and the nested
`.gitignore` that keeps them apart)
· browser/ (the Web tab's page, docs/web.md: `address` — what
a page may load — `keys` — who a ⌘-chord in a page belongs
to — `native` — the WKWebViews, their host view and slots,
the delegate — and the commands)
src-tauri/migrations/ 0001_init … (SQLite schema; applied on startup)
src/
main.tsx QueryClient (+ global mutation→toast) · providers · router ·
the fixture-mode boot hook (dev + `VITE_SANTREE_FIXTURES=1` only)
dev/fixtures/ the screenshot fixture world (see "No mock data") — its own
README says what is fake and what stays real
routes/ one file per destination → renders a feature view's CONTENT
(window chrome belongs to the shell, never to a view)
components/shell/ the one permanent frame: sidebar (search · destinations ·
triage → tickets → investigations · projects → worktrees →
agents · daedalus → the same tree, for projects on the home
server) · status bar · AppShell
features/<view>/ each owns a model.tsx (context) + presentational components
features/trees/ the worktree workspace. Right panel = 6 panes (Issue · Files ·
Changes · History · PR · AI work queue; the last two only when
the branch has one). The AI-work pane is the queue AND the AI's
brief, in that order — one destination, not two tabs. Main area
= the worktree's tabs (every agent and shell it has open, the
one a started task runs in included — each a `worktree_tabs`
row, so a restart reopens exactly what was open, and closing
the last leaves the welcome surface) · a picked file's diff ·
setup logs · a check's raw job log · the PR page and the
ticket page, each opened from its rail pane's expand
control (closable, and not a row)
features/reviews/ OTHER PEOPLE's PRs (the inbox). Main area = the same tab
strip Trees has (`ReviewTabBar`): a non-closable **Pull
Request** tab (its header, then Conversation — description
block, then the comments — · Commits · Checks · Files changed,
which carries the diffstat) · the PR checkout's own
`worktree_tabs` rows · the AI review sessions · the
ticket page when expanded from the rail. Beside it a
`ReviewSidePanel` rail of Issue + AI work queue. Also the PR
components both hosts share — `PrPage` (the whole PR view,
host-agnostic: Trees opens it too), checks, brief, queue list,
AI work pane, file body, cards
features/triage/ the ticket workspace at `/triage?ticket=` — a third tab-strip
host (`TriageTabBar`): a non-closable ticket tab (named for its tracker)
(`components/IssuePage`), one closable tab per investigation
agent (started from the ticket page's "Investigate with"
and its provider chooser, never from the "+"), and the
ticket's own tabs — sessions and shells, as many as you
like: `worktree_tabs` rows whose owner is the ticket's
surface key `triage:<ticket>`, keyed
`triage:<ticket>:tab:<id>` (`tabs::term_key` / `tabRefId`
branch on the prefix), launched on the Investigate surface
(`TriageTabPane`, `useAgentTab({ surface: "triage" })`)
because they run on the main checkout. Beside it a `TriageSidePanel` rail of
Files · Session history, both reading the attached project's
MAIN checkout and naming it (with its Change control) on
their header line; with nothing attached each pane is the
ask instead. `TriageRepoGate` is the modal that asks for
that project. The queue itself lives in the
sidebar's `TriageSection`.
lib/queries.ts ALL data hooks (useUnwrappedQuery, useOptimisticMutation, …)
lib/overlays.ts the app's open overlays (menus, modals, toasts, drop previews),
which a Web tab's native page gives way to — docs/web.md
features/conversation/ a Claude tab's other face: the live session drawn as a
conversation (turns, tool cards, diffs, subagents), its
composer, and the per-tab choice of face (⌘J)
features/web/ the Web tab: WebTabPane (toolbar + placeholder), useBrowserPage
(placement and overlays), the page-state store, the strips'
shared Web pieces, terminal links, the root event listeners
lib/attention.ts what needs a human: level ladder, seen-gating, tree ordering
state/ AppContext (theme, settings, cross-view UI) · AgentRuns (runs
that outlive their view) · WorkRepoGate (which project a
ticket starts in) · toast.tsx (notifications)
components/ shared chrome + primitives.tsx (Badge, EmptyState, ChevronSelect…)
· SidePanel (the one right-panel shell every view is built on)
· TabStrip (the one main-area tab strip every view draws)
· IssuePane (the ticket RAIL pane) + IssuePage (the
same ticket at reading width, for a tab) · IssueProperties
(the one Linear-style property strip — priority, points,
cycle, due, project, milestone, assignee, labels — every
ticket surface draws, from a row or from the detail) ·
WorkSignals (the shared marks: PriorityBars, StatusGlyph,
EstimateTag, CycleTag, the due-date signals, the headings)
· ProjectPickerDialog (pick a registered project, with a
default — what the triage repo gate asks through)
theme/colors.ts enum → color/label mapsKey patterns (reuse these)
- Layout: there is ONE window frame (
components/shell/AppShell) — a permanent sidebar and status bar around a swapping content area. A view renders content only: no navigation, no repo switcher, no window chrome of its own. Anything that must outlive a navigation (terminal layer, background agent runs, palette) is mounted byroutes/__root.tsxoutside the content slot, or it dies on the next click. - Attention: a status dot, an ordering, or a "needs you" count comes from
lib/attention.ts(levelOf·highest·compareAttention·useSeenAgents) on top of the agent registry's buckets — never from a second classification. - Your own PR lives in Trees, not Reviews. The right panel's
prandaiWorkpanes (features/trees/WorktreePrPane·reviews/AiWorkPane) are the whole own-PR surface: state, checks, conversation, AI brief, and the work queue that a failing check, a review comment, an AI draft or a highlighted diff line all feed. One "Start work" agent drains it, in the same main panel as every other agent. Everything that fills the queue goes throughreviews/QueueAction— one control, one spark glyph, one minted id — so the buttons and the tab read as one concept. The sidebar lists no own-PR rows: a worktree's PR is reached through the worktree. The full PR page (header + Conversation · Commits · Checks · Files changed) isreviews/PrPage, and the PR pane's expand control opens it as a closable Trees tab — so do the ticket and GitHub marks on a sidebar worktree row (TreeFocus.expand: the ticket page or the PR page, never the rail pane). The prompt "Start work" hands the agent is thepr-fixtemplate (review_ai::fix_promptrenders it over the open queue items), editable in Settings → Prompts under Reviews; its preview renders over a sample queue the editor builds and the backend turns into the agent's JSON through the same builder a real queue uses (sample_fix_tasks). Reviews is only other people's PRs — the inbox of what's waiting on you. The components are shared, not duplicated:PrPage,ChecksPane,ReviewBriefSection,ReviewWorklist,AiWorkPane,PrFileBodyand the draft/thread cards take their host's callbacks as props (seeuseStartWork.tsfor the one thing the two hosts really differ on — whether the PR's worktree has to be created first). - Prompt layers: a prompt resolves through four, most specific first —
the user's override for the repo (DB,
repo:<slug>), the repo's committed.santree/prompts/<name>.njk(read from the main checkout on every render, so agit pullis live on the next launch), the user's app-wide override (DB,app), the embedded default (src-tauri/prompts/<name>.njk,include_str!). The render env registers each prompt three times —santree/<name>(default),project/<name>(the repo's file, else the layer below it) and<name>(effective) — so a layer extends the one below with plain Jinja ({% extends "santree/triage" %}+{% block %}) or replaces it by not extending. Defaults declare empty slots ({% block sources %}{% endblock %};PromptDef.slots, pinned byevery_slot_is_an_empty_block_in_its_default) where project-specific knowledge belongs; the editor fills those as fields (SlotEditor,promptLayers.tsis the parse/build round trip) so a filled layer keeps receiving every other change to the default. "Take over" copies the default with a{# santree-default: <hash> #}mark, which is how the editor knows to say the default moved on. A shipped default must be generic: company facts (hosts, tool names, team prefixes, log fields) go in that company's.santree/prompts/, never insrc-tauri/prompts/— the triage prompt shipped a whole internal runbook that way once, in a public repo. A self-extending layer is refused at write (check_extends); the project file name is validated as one path component and joined throughsafe_path. - Triage is a sidebar section, not a destination.
shell/TriageSectionis organised by team: one folding row per team in the viewer's scope (the repo-header register — name, count, and at the trailing edge a chip for who has its rotation, which opens the whole schedule inshell/RotationDialog), the only team included: the row is what names it and folds it. The team's active tickets sit under it at the section's own gutter — no indent; folding is what makes them its — each ticket's investigation agents under the ticket, and a folded Snoozed group per team. Which teams is thetriage_teamssetting (Settings → Triage → Teams): three unioned rules — rotations the viewer is in (viewer_participates, not team membership), teams holding a triage ticket assigned to them, teams they are a member of (off by default) — plus per-team always/never picks. The backend applies the same rules (linear.rsscope_ofover cachedTeamFacts, shared by the queue and the schedules) and fetches every scoped team's whole inbox OR the viewer's own tickets (inbox_filter). Mine/All is per team: the header's menu sets the default (triage_good_citizen), each team's row carries a hover switch that writes its own entry (triage_team_scopes), andfilterTriageQueueapplies both without a refetch. The grouping isshell/triageTeams. Scoped touseTriageOrgRepo's project; the header menu's last row leads to the Teams card. A ticket opens/triage?ticket=<id>; selection lives in the route so the row lights from it, exactly as Reviews'?pr=does. There is no manual ordering: the order is the backend's (active first, soonest SLA).useTriageQueueis the one source for what the section shows. A row's right-click menu (shell/TriageTicketMenu) snoozes it — the one tracker write offered from the rail, gated like the status picker (disabled withTRACKER_READ_ONLY_HINT, refused by the backend regardless). With no tracker connected the section draws greyed out rather than as an empty queue, and the rail'sshell/TrackerConnectPrompt(offuseTrackerConnected,nulluntil both connection reads answer) links to Settings → Linear or Jira. Jira has no triage state, team inbox, rotation, SLA or snooze. Its queue is whatever the repo'sjira_triage_jqlsetting matches (Settings → Repo → Ticket tracker; unset isjira::DEFAULT_TRIAGE_JQL, the viewer's assigned To Do issues), a ticket's team is its project key, the Teams rules above are Linear's alone, andtriage_snoozerefuses a Jira repo rather than falling through to a Linear org. - A triage ticket runs on an attached project, never a worktree. Two repos,
deliberately: the queue and the ticket come from one tracker org or site
(
useTriageOrgRepo— the triage default, else the first registered project — read by both the section and the workspace so a row and the ticket it opens can't disagree), while anything that runs uses the ticket's attached project (useTriageRepo: its owntriage_repo:<id>, elsetriage_default_repo), on that project's MAIN checkout. An investigation, a terminal and the rail's file/history panes all need one, so the first such action asks for it once throughtriage/TriageRepoGate(the promise-resolving patternreviews/WorktreeGateestablished) and every action goes through onewithRepo. Nothing here creates a worktree, and the backend agrees:validate_agent_cwdrefuses atriage:session anywhere but the registered repo root. - Where a ticket starts is the Work gate's answer — for every start.
Several registered projects can share a ticket's tracker org, so the project is
resolved through
state/WorkRepoGate— the one project that carries the ticket (no question), else the Work default (work_default_repo, Settings → Work; distinct from triage's on purpose), elseProjectPickerDialogover just those projects, with a save-as-default switch. The provider is mounted inroutes/__root.tsx, not under a view, because every way to start a ticket goes through it: the Tickets list's Run and its queue, the rail's Run and Run-in-background, the graph node's menu, Launch, and the workspace's own "Start a task". A start that answers "where" for itself is the bug this exists to prevent — it is how a ticket came to run in whichever project was on screen. The menu's "Run in another project…" (always) is the one way past the gate's first two answers for a single run. - There is no "active project". A project is a coordinate of the thing on
screen, never a mode the app is in:
/trees?project=&tree=names the open workspace,/reviews?project=&pr=the open inbox,/triage?ticket=the open ticket. The permanent sidebar reads those params directly (ProjectTree), so one url is both what the view shows and what the rail lights — a sidebar click is onenavigate(), not a switch-then-focus-then-navigate handoff. Reads that need some project but are not scoped to one take a stable answer, never the screen:useWorkScopeRepo(Tickets — the Work default, else the first registered) anduseTriageOrgRepo.useOrgSiblings(repo)is what turns a read scope into the gate's candidate list. Anything that outlives the view that started it carries its project explicitly:PendingLaunch.repo,BackgroundLaunch.repo,QueuedLaunch.repo,TreeFocus.repo, andCreateWorktreeVars.repo(a var, not a hook argument — the answer arrives at click time). - A repo reads one tracker, resolved in one place.
repos.connectionholds it, as a provider-qualified id (linear:<org slug>,jira:<cloud id>,ticktick:me;connection.rs), and there is no fallback: a repo reads the connection it is linked to, or none. The database links the waiting repos when an install makes its first connection (triggers in0038, recounted in0039),connection::adopt_soledoes the same for a repo added while exactly one exists, and with several the user picks (Settings → Repo → Ticket tracker). Linking one clears the other provider's link by construction (one column).repos.linear_org_slug/jira_cloud_idare dead columns. Anything that groups repos "by tracker" (the Tickets fold, the Work gate's candidates) keys onRepo.connection, never on thetrackerdisplay label. That answer ships asRepo.provider, read throughuseTicketProvider(repo). Every provider-neutral command — issues, triage, detail, state, comments,pr_tickets, the work and investigate prompts — dispatches throughtracker::*; callinglinear::orjira::directly for one of those is how a Jira repo came to read a Linear org. Marks and labels follow the repo (TrackerLogo,RepoTrackerLogo, or a detail'strackerOf(trackerName)). What a connection can do — snooze, threaded replies, which Triage team rules apply — islib/trackertrackerFeatures(read throughuseTrackerFeatures), never a view's ownprovider === "Jira"orvia === "Mcp". A Linear org connected through its hosted MCP server (LinearStatus.via) is stillTicketProvider::Linear;tracker::repo_trackersends it tolinear_mcp(docs/linear-mcp.md). A list that spans projects hands its selection over with the row's project (issues/modelopenTicket): looking an id up in one project and falling back to its first ticket showed a different ticket. - TickTick has no ticket key. A task is reached only by (list, task), so its
ticket id is
<listId>.<taskId>(santree_core::ticktick::split_idis the guard before any request path; no:, whichtree:<id>:tab:splits on). People see the handlett-<last 6 of the task id>(ticketHandle), which also names the branch; the worktree id stays the full id. One account per install (ticktick:me: the API has no identity endpoint), OAuth with no refresh token or a pasted personal API token, both a keychain bearer. Subtasks block their parent; there are no states beyond Todo / Done / Won't do, no triage, no teams. Which lists a repo reads is itsticktick_listssetting (unset = all open). - One right panel, four hosts.
components/SidePanelis the chrome — icon strip, underline, dots, drag region, edge resize, collapse-to-nothing — and each view supplies its own panes, dots and model (trees/FilePickerPanel,reviews/ReviewSidePanel,triage/TriageSidePanel, and Tickets'issues/RightPanel; distinctcssVars, or they resize each other). What goes in a rail is reference beside the work, which is why Reviews has no PR pane and Triage no Issue pane: in each, the main area already is that thing. Tickets' rail has two: the whole ticket (issues/IssuePanel— run control, blockers, body, notes) and the launch queue (issues/QueuePane— one card per queued ticket with its agent pick and notes, and the one Launch button; its tab wears the accent dot while anything is queued and a+Nfor a beat after each add). The queue is in-memory and cross-project — each entry remembers the project the gate gave it, so Launch cannot send a ticket somewhere Run would not have; the per-ticket pick is the agent only — model and effort come from Settings for that agent, by the rule inissues/model.tsx. Collapsed, a rail draws nothing and its host's top strip takes thePanelToggleover at the same right edge (Trees' tab bar, the Tickets header). - One main tab strip, three hosts.
components/TabStripis the chrome — fitting and overflow, rename-in-place, the close ×, the "+" and its ⌘T, the drag region — and each host supplies its tabs, its menu rows and its trailing controls (trees/MainTabBar,reviews/ReviewTabBar,triage/TriageTabBar). A tab is aworktree_tabsrow, or one of three other things: the tab that is the view (Reviews' "Pull Request", Triage's ticket tab — always there, never closes), a transient view that appears with what it shows (a picked file, setup logs, a check log, the PR page, the ticket page — ephemeralMainTabliterals, never rows, closable), or a session that hangs off the view's own surface rather than a row (an AI review onai-review:<pr>, a triage investigation ontriage:<ticket>— one per provider). A row's owner (worktree_id) is a worktree id, or a triage ticket'striage:<ticket>— Triage has no worktree, and its "+" opens the same rows anyway. Closing a row tears its PTY down and a dead process closes its row — both fromtrees/useTabSessions, once, for every strip. - Every main area splits, for every kind of tab. Each host's bar renders a
components/split/SplitWorkspace: a binary tree of tab groups (VS Code's shape, not panes inside a tab), each aTabStripover its active tab. Drag a tab onto a strip to reorder or move it, onto a group's edge to split, into its middle to move it there — the drop is previewed before release (dropZone.ts). The layout is pure (layout.ts:normalizefits it to what the host has open; a group whose last tab leaves collapses) and persisted per surface — worktree, PR, ticket — in localStorage (useSplitLayout). The host still owns which tabs exist and what each renders (renderTab(tab, visible));activeis the focused group's tab, and ⌘T, ⌘F and the status bar follow it. Content is rendered flat beside the groups and positioned over them, so a moved tab never remounts — a non-idempotent effect in a tab survives a drag. Terminals stay in the terminal layer, one slot per session (docs/terminals.md). A "visible worktree" is now every row on screen (VisibleWorktree.tabs), one per group. - Terminals have two backends, one facade. A local pane's process is either
in this app (
PtyManager,Mode::Off) or in the detached santree server (RemoteTerminalsover a unix socket); a Daedalus pane is the sameRemoteTerminalsover the agent's link.sessions::Terminalsis the one handle commands hold, and it dispatches by id (oneIdRegistrycounter; each host answers whether itholds(id)) — new panes name aRoute(Local | Daedalus, the caller knows whether a cwd is a Daedalus project's). Which local backend runs issessions::server_mode(), decided once:Signed(a release whose own signature matches the bakedSANTREE_TEAM_ID),OptIn(SANTREE_SERVER=1, uid-only) orOff. Never branch on the backend anywhere else — amatchonMode,Localor a host in a command or view is how a pane ends up on the wrong host (a review rule: nothing checks it). What the compiler does hold: a pane is typed into only withterminal::input's IPC-born types, and opened, attached, adopted and closed only byterminal.rsand the facade's arms (clippy.tomldisallowed-methods, its exceptions pinned bycompliance.rs). Liveness isLiveness { live, complete }: an incomplete answer keeps agents as they were and refuses a resume. A lost agent tab's Resume isuseLostTabResume, one path for every tab that is a row. docs/server.md, "Sessions". - A Claude tab's Conversation face is built from its record, never from a
control channel. It is experimental (Settings → Experimental → Conversation
view).
features/conversationdraws the live session from Claude's own transcript (conversation_read, incremental by cursor) plus the hooks and status line; santree runs noclaude -p, SDK or other driver to get it (docs/conversation.md). It types only what the user could type, through the pane's own renderer and one queue per pane, on the user's click or key in the view: their message (at the prompt or while Claude works, never while a dialog on record is still open), the keys of an answer they pick on a dialog's card (only sequences probed on Claude Code's dialogs, once per dialog, never for a dialog that may not be the one on screen —stacked— or has closed, and anything but a lone digit or Esc only while nothing else has reached the pane), and Stop's one Esc. Every gate reads the hook record as stored — never the reconciled state the dot reads — written after the process now in the pane started. That is COMPLIANCE.md's bound;compliance.test.tspins what the view types and when. Anything it renders as markdown loads nothing remote: transcript text and hook payloads are attacker-influenceable. - A Web tab's page is drawn above the app. It is a native WKWebView, not
DOM (docs/web.md), so anything floating that can cross it must register in
lib/overlays.ts—Dropdown,PositionedMenu,useModalA11y, the toast viewport and the drop preview already do, so build overlays from them. A page never gets Tauri IPC, and every URL that reaches it from IPC or the DB passesbrowser::address::checked. - One place renders a diff.
features/trees/DiffPanepicks the source withprDiffModeFor: GitHub's own patch when the file is in the PR (its line numbers are what the comments anchor to), the local branch-vs-base diff otherwise, and the local diff with a notice when the branch has unpushed commits. Never overlay PR comments on a locally recomputed diff — that is how a comment lands on the wrong line. - Split branch… opens in the Changes panel from the worktree menu or Git
panel. A bottom-right disclosure expands its form; it starts collapsed on app
launch. A pending mutation supplies the sidebar’s nested “Creating…” placeholder
until the move and list reconciliation finish, including across form unmounts.
“Run setup” is opt-in and starts the child’s existing setup flow only after
the move succeeds. The form shares the existing commit controls and ChangesList
(icons, tree/list preference, staging, and file diffs in the main area). Commit the current part first; this action moves all remaining staged,
unstaged and untracked changes into one new child worktree at the source HEAD.
Creation requires a commit beyond the source's base and remaining changes.
The form keeps its branch/ticket inputs during the automatic post-commit preview
refresh, then closes after one child is created. Further splits start from the menu.
split_stack.rsjournals retries inworktree_moves;git/split.rskeeps a named recovery stash and restores the original staging state. Ignored files stay unless already tracked or staged. No commit or push is automatic. Worktree ids remain independent ofWorktree.ticketId/worktree_links.ticket_id: ids own paths and sessions, ticket associations drive tracker reads. The private index lives in the checkout's own git dir (git rev-parse --git-path), so a Daedalus project's split runs on the box like any other git, and its "Run setup" runs the child's setup script there. Sparse and submodule changes are unsupported. Old split-draft migrations remain for database compatibility. - Data: every read is a hook in
lib/queries.ts. Result-typed commands go throughuseUnwrappedQuery; raw-value commands use plainuseQuery. Writes useuseOptimisticMutation(cancel → patch → rollback-on-error → invalidate-on-settle). - Errors & background events: every failed read and write is logged under its
key and surfaces as a red toast — one policy,
lib/queryFailures.ts, wired inmain.tsx— except the first failed refresh of data still on screen, which only logs (a second in a row toasts). A read that meets a gateway failure (502/503/504) is sent once more bygql::sendbefore it fails; a write never is. Raise green toasts withtoast.success(...)fromstate/toast.tsx. - Feature state: ephemeral view state lives in
features/<view>/model.tsx(a context); shared cross-view state inAppContext; server data only via query hooks. - Experimental features sit behind Settings → Experimental. Daedalus, the
English tutor and the Conversation view each have one switch, an app-scope row
(
experimental_<name>) where no row, or anything but"true", is off. The one writer isset_experimental(the genericset_settingrefuses those keys: the Daedalus switch starts and stops the link as it is written). Readers aresettings::experimentalanduseExperimental(feature), and each feature asks in one place: the link (DaedalusHost::apply), the tutor (english_tutor::enabled, with its own toggle), the Conversation face (useConversationOffer). Lists, pickers and fallbacks that offer a project readuseOfferedRepos()(no Daedalus projects while that switch is off);useRepos()stays the whole registry, because where a project lives (a pane's trust, a launch's hooks) never depends on a switch. A new feature adds its key toExperimentalFeatureandEXPERIMENTAL_KEYS(the two tables must agree) and gates every surface through that one reader. - Shared UI:
primitives.tsx(Badge, Dot, Toggle, Tabs, Segmented, EmptyState, ChevronSelect),useEdgeResize(panel resizers),deriveIssueState(the single source for a ticket's running/ready/blocked/chainable flags). - Right-click menus:
primitivesContextMenuwraps a region (a row, a card) and opensPositionedMenuat the pointer or from Shift-F10; the graph opensPositionedMenuitself from React Flow'sonNodeContextMenu. Four objects have one: a worktree (shell/WorktreeMenu), a ticket (the Tickets list row and the graph node —tickets/TicketRow,issues/ticketMenu— and the triage row,shell/TriageTicketMenu), and a pull request in the sidebar (shell/ReviewPrMenu). A ticket's tracker rows (open, copy id, copy link) come fromcomponents/menuRows(ticketItems) so every host offers the same three; the url is built, never fetched (useTicketIssueUrl: Linear's org slug, or the Jira site's url +/browse/<key>). Rows are declarativeContextMenuItems — a menu is a fixed list of actions on one object, and a render prop is how two of them drift. - Colors: never hardcode hex in components — use
theme/colors.ts(successColor,LINEAR_BRAND,JIRA_BRAND,alpha(),statusColor) or a CSS token. Tinted-text/on-accent have dedicated tokens (--accent-text,--on-accent) so they flip in light mode. - Design system (
src/styles.css) — the scales are closed. Type: the system faces (SF Pro, SF Mono) on one scale,text-2xs…text-3xl(10 · 11 · 12 · 13 · 14 · 15 · 18 · 22 · 26px; 13 is body) — notext-[Npx]. Radius:rounded-xs…rounded-2xl(3 · 4 · 6 · 8 · 10 · 12) — controlsmd, cardsxl, menus and popoversxl, dialogs2xl. Elevation:shadow-popover/shadow-dialog, nothing else. Buttons areprimitivesButtonat fixed heights (24 · 28 · 32). The accent is the brand emerald and means interaction (primary action, a switch that's on, focus, links); selection is a neutral fill (--selection-fill), status keeps its own hues. Mono is only for what a person would copy as code (paths, branches, SHAs, commands, logs) — never labels, counts, times or ticket keys. Section labels are sentence case,text-xs font-semibold— no uppercase tracked eyebrows. No colored stripe down one side of a card or selected row, no outline on a chip, no ring around a text field: a field tints its own border, and a container that holds one is a.field.
Security & validation invariants (load-bearing)
- Every IPC value that becomes a path, id, or git arg is untrusted. Validate
before it touches the filesystem or a
gitargv: paths/ids throughgit.rssafe_path/safe_real_path(single normal component; reject.., absolute, symlink-escape); branch/ref names must not start with-(flag injection).issue_id,base, session ids all cross this line — neverPath::joinor shell them raw. A ticket id bound for Jira passesjira::is_issue_keybefore it reaches JQL or a request path, and one bound for TickTick passessantree_core::ticktick::split_idbefore it reaches a request path. - Match hosts/URLs by parse at the sink, never by string prefix —
url.host_str() == Some("uploads.linear.app"), notstarts_with("https://uploads.linear.app")(a prefix also matches…app.evil.com). Same for any allowlist. - App-owned secrets (Linear, Jira and TickTick tokens) belong in the OS keychain, not plaintext
SQLite. Don't add new plaintext-secret columns. (Distinct from
COMPLIANCE.md, which bars agent-CLI creds — this is our own OAuth.) - Nothing an agent writes reaches GitHub without a click. The AI review's MCP
tools write santree's own rows;
review_drafts::publishis the only path out, and it runs on a user action into their pending review. A new command that lets an agent-authored value reach agithub.rswrite is the line this feature exists to hold.
Commands
pnpm dev | Run the app with HMR (regenerates bindings.ts on startup) |
pnpm build | tsc --noEmit + production Vite build |
pnpm gen:bindings | Regenerate bindings.ts from Rust |
pnpm lint / pnpm format | Biome check / autoformat |
pnpm test / cargo test | Vitest / Rust tests |
cargo clippy | Rust linter |
Before finishing a change: run the /verify skill (or at minimum its static
gates: cargo fmt --all --check, cargo check/clippy, pnpm gen:bindings if
commands changed, npx tsc --noEmit, pnpm lint, both test suites — all green).
cargo fmt is first because it is the gate that keeps getting skipped: clippy
and the tests pass happily on unformatted code, and CI's backend-lint job runs
fmt before clippy, so the drift fails the build and masks clippy's verdict. For any new
command taking a path/id/branch, confirm it's validated (safe_path /
no-leading-dash) before it reaches fs or git.
Tests: what earns one
The suites were trimmed hard (2026-10-12: vitest ~1.7k → ~1.3k, app-core ~520 → ~400, integrations 315 → 211) because redundant tests slow CI and every change. Don't grow them back. A new test must protect something a reader can't see from the code; when a change touches tested behaviour, edit or merge the existing test rather than adding a neighbour. When in doubt, don't add it.
Write (and keep):
- security and validation gates (
safe_path, id/arg validation, the host/URL sinks), and the compliance invariants (COMPLIANCE.md); - wire and format pins: protocol text, the verbatim Claude/Codex hook payloads,
migration checksums,
santree-hook's DB writes, the updater channel rules; - data-loss, race and ordering cases that are hard to hit by hand;
- a regression for a real bug, named for the bug it pins;
- the path production takes. A test of a component's default doesn't cover the caller that overrides it, and a pure-logic test doesn't cover a render bug: when the bug was visible, render the component.
Don't write:
- a second test for a branch another already covers, or several that only vary an input (one table-driven test);
- tests that restate a constant, an enum's variants, a derive, or a library's own behaviour;
- tests whose fixture is a guess about a third-party tool's behaviour — they encode the same wrong guess as the code. Check one real captured instance;
- Linux-only branches or tests outside the engine-consumed crates (the app is macOS-only);
- slow tests (sleeps, real network, real git remotes) when a fake would do.
A test that simulates a missing CLI or box sets an explicit minimal PATH
instead of inheriting the developer's. A failure that only reproduces locally is
usually ambient-environment leakage, not flakiness.
Releasing & the self-updater
The app ships from CI only: a v* tag drives .github/workflows/release.yml
(universal macOS build → codesign → notarize → staple → spctl verify →
smoke-launch the signed .app → publish). No local machine signs anything — the
credentials live in the repo's release GitHub environment, restricted to v*
tags. README "Releasing" is the operator story; this is what an implementer
must not break.
Cutting a release is a version bump, a changelog entry and a tag, nothing
else: set the same version in package.json, src-tauri/tauri.conf.json and
Cargo.toml ([workspace.package], which Cargo.lock mirrors for the
workspace crates), add a ## X.Y.Z section to CHANGELOG.md, then
git tag vX.Y.Z && git push origin vX.Y.Z. The guard fails the tag unless the
three versions match it, and fails a stable tag without its changelog entry
— that section becomes the release body and the in-app "What's new", so write
it for users, in plain bullets (the app renders it as text). Betas without an
entry fall back to a commit-compare link.
The tag picks the channel. v0.2.0 = stable — GitHub's releases/latest
pointer, which is also what the website's download button resolves through.
v0.2.0-beta.N = beta, published as a pre-release so that pointer skips it.
Semver ordering is load-bearing: 0.2.0-beta.1 < 0.2.0 is what rolls a beta
user onto the next stable, and the updater never downgrades.
The beta manifest is rolling. Every release — stable included — re-uploads
latest.json to the fixed updater-beta pre-release. A release published
outside the workflow skips that and strands every beta user on their last
beta, silently.
The updater is tauri-plugin-updater; channels are ours. One binary
serves both: src-tauri/src/update.rs picks the endpoint per check from the
update_channel setting, because the endpoint list in tauri.conf.json is
baked in at build time. The pubkey there pairs with
TAURI_SIGNING_PRIVATE_KEY in CI — that key has no recovery path;
installed apps accept only updates it signed, so losing it strands every
install until users re-download by hand. useUpdateWatcher (mounted by the
app shell) checks 15s after launch and every 6h, announcing via one toast per
version.
Traps, each paid for once already:
- Tauri does not sign
bundle.resources, and notarization rejects any unsigned Mach-O in the bundle.scripts/sign-resources.mjssignssantree-hookandsantree-serverfrombeforeBundleCommand— after staging (pnpm bundle:binaries), before the bundler seals them — and no-ops withoutAPPLE_SIGNING_IDENTITYso keyless builds keep working (with one, a missing binary is an error). The server is signed with identifiercom.santree.serverand no entitlements. A new resource binary must be added there. santree-serveris a bundle resource, declared intauri.macos.conf.json(merged overtauri.conf.jsonby JSON merge patch, sobundle.resourceskeys add up). tauri-build fails on a declared resource that doesn't exist, so every cargo build ofsrc-taurineedstarget/bundle-resources/santree-serverstaged first —pnpm bundle:binariesdoes it, and ci.yml's cargo-only jobs stage both binaries by hand. Add the file to the conf only after it is staged.SANTREE_TEAM_IDis baked into the server at build time (option_env!; cargo rebuilds when it changes, no build script needed). The server refuses every peer unless its own signature carries that Team ID, so release.yml derives it from the signing identity (a throwaway test-signature, asserted to be 10 chars of[A-Z0-9]) and exports it to the build; unset, you get a dev server that goes by whatever signature it has. A build that bakes the wrong team ships a server that serves nobody — release.yml checks the shipped binary carries the team and that it equals the app's.- Hardened runtime, and no
get-task-allow/disable-library-validation/allow-dyld-environment-variableson the app or the server, is load-bearing: the server admits only santree.app by signature, which means nothing if an agent running as the same user can inject into either process.scripts/verify-bundle-signatures.shasserts it (and the server's identifier and Team ID) on the signed bundle. Never add an entitlements file to the build "to make something work" without reading that script's header. REVISION(crates/server/src/lib.rs) is what the smoke launch compares the bundled server'sversion --jsonagainst, andpgrep -x santree-serverafter it must find nothing — nothing may outlive a CI run.- The signing certificate is imported into a keychain in its own workflow step
before the build. Tauri's own import happens at its signing phase, which is
after
beforeBundleCommand— too late for the hook. That ordering was the first release's failure. createUpdaterArtifactsis passed via--configin the release workflow, not committed: generating updater artifacts requires the signing key, so committing it would break every keyless build, including CI's bundle smoke.TAURI_BUNDLER_DMG_IGNORE_CI=truein the release env re-enables the Finder AppleScript that paints the DMG background and places the icons — withCI=truethe bundler otherwise passes--skip-jenkinsand ships a default-looking DMG (background.png present but no.DS_Storeto use it).- TickTick's OAuth client secret is compiled in by
option_env!from thereleaseenvironment'sTICKTICK_CLIENT_SECRET(the build step's env), not committed. Drop it fromrelease.ymland the release still builds, but ships without "Sign in with TickTick" (oauthAvailablefalse; the token path stays). Locally it comes from a cargo[env]outside the repo. - The version-free
santree-macos.dmgasset exists for the website'sreleases/latest/download/…link. Stop uploading it and the download button 404s on the next release. SANTREE_SMOKE=1(lib.rs) is CI's launch probe — exit 0 once the window loads, watchdog exit 3 if it never does. It runs in ci.yml's bundle smoke and against the signed .app in the release job; it is the only thing that ever runs what ships.
Claude project config (committed in .claude/)
- Skills:
/verify(green checklist + real-app screenshot harness),/new-command(end-to-end Tauri command checklist incl. security gate),/production-review(multi-agent review + wave-pattern fix mode). - Agent:
ipc-security-auditor— run it on any diff touchingcommands.rs,git.rs,terminal.rs,crates/pty,crates/hostorcrates/server. - Hook: editing
commands.rs/lib.rs/domain.rstriggers a bindings-drift reminder (.claude/hooks/bindings-reminder.py). - Session/worktree state under
.claude/stays gitignored; only settings, hooks, skills, agents, and commands are versioned.
Gotchas
bindings.tsandrouteTree.gen.tsare generated but committed — don't edit by hand; Biome ignores them.tauri.dev.conf.jsoncarries the whole window entry, not just its title: a--configoverlay merges by JSON merge-patch, so anapp.windowsarray replaces the base one — a one-field entry silently droppedtitleBarStyle: Overlayand gave the dev build a native title bar, shifting every capture. Keep it a mirror oftauri.conf.json's entry plus the title, and remembertauri devreads the overlay once at launch: editing it triggers a rebuild but not a re-merge, so restart the dev stack to pick it up.- Tailwind v4 is CSS-first (
@themeinsrc/styles.css, which Biome is configured to skip). IDE "unknown at-rule" warnings are handled by.vscode/settings.json. - Terminals survive a reload, so a pane unmounting must never
closea session — it detaches, and the session is caught up from its ring on the way back. Onlyclose(key)on a tab ends a process. Readdocs/terminals.mdbefore touchingcrates/pty,terminal.rs, orsrc/features/terminal/. - Terminal compliance: the PTY runs the real, unmodified CLI — no credential
handling, no output-parsing-drives-input, no unattended loops. See
COMPLIANCE.md; these constraints are load-bearing. Who may write into or spawn a PTY is held by the compiler (the input types interminal.rs, the rootclippy.toml): a new call outside a sanctioned site failscargo clippy -- -D warnings, and a new#[allow(clippy::disallowed_methods)]failsthe_lint_exceptions_are_exactly_the_sanctioned_sites. - External CLI contracts: verify vendor flags against
--help, don't guess. Claude--modeltakes dash-form ids or aliases (sonnet/opus/haiku) — dotted (claude-sonnet-4.5) is invalid and fails launch. - Codex fires
SessionStarton the first turn, not at launch (0.151.0, measured). So a Codex tab that hasn't been prompted has nosession_staterow and noterminal_sessionsbinding — nothing hook-fed knows it exists. Anything that must show an agent promptly reads the process table (agent_procs.rs, the pane's foreground process group) or santree's own launch record (the terminal tab'sAgentTabIdentity), not the hook. Which agent is running has one ordered arbiter — session row → process table → launch record — and what it is doing still has onlylib/attention.ts; never let the first answer the second. Seedocs/terminals.md"Agent state" and "Agent identity". - A
santree-hookwrite that fails leaves a line in<app_data_dir>/santree-hook-errors.log. The binary is silent to the agent by contract, which used to mean silent full stop — check that file before concluding a hook never fired. - Non-idempotent effects (setup scripts, PTY spawn, worktree create) must stay
mounted with
display:none, nevercond && <C/>— remount re-fires them. - A11y baseline: new interactive elements need keyboard focus + an accessible
name; never
outline:nonewithout a:focus-visiblering.
Website: claims ahead of the code
The landing's Steer station (website/src/components/tree/agent-layer.ts)
presents three things as shipped: a live progress checklist, questions as
native popups, and plans rendered readably, all because santree starts the
agent and can add what an agent is never asked for. As of 2026-10-07 none of
them exists in the app (checked on every branch; the card on the page is a
redraw in the app's palette, not a capture). It is marketing ahead of code, by
the operator's decision. Before a release, verify each claim against the app,
or revert the page by setting AGENT_LAYER_SHIPPED = false in that one file.
What the code does back is the session-state dot ("needs you"), from the hooks
santree layers onto every agent launch (src-tauri/src/hooks.rs).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

