agentleFS
santree-aisantree-ai/santree/AGENTS.md

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.

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
  1. Distinctive:

    Views: all of them — Triage, Issues, Trees, Reviews, Settings, Terminal — are backed by real data.

    line 16
  2. Distinctive:

    Correctness over cleverness: No hacky things that break later.

    line 52
  3. Very specific:

    No mock data: When a backend isn't connected the command returns an empty result (e.g.

    line 119
  4. Distinctive:

    Run-in-background, the graph node's menu, Launch, and the workspace's own "Start a task".

    line 455
  5. Very specific:

    Data: every read is a hook in lib/queries.ts.

    line 622
  6. Very specific:

    Errors & background events: every failed read and write is logged under its key and surfaces as a red toast — one policy, …

    line 625
  7. Very specific:

    Colors: never hardcode hex in components — use theme/colors.ts (successColor, LINEAR_BRAND, JIRA_BRAND, alpha(), statusColor) or a CSS …

    line 662
  8. Very specific:

    Before finishing a change: run the /verify skill (or at minimum its static gates: cargo fmt --all --check, cargo check/clippy, pnpm …

    line 714
  9. Distinctive:

    Don't grow them back. A new test must protect something a reader can't see from the code.

    line 727
  10. Very specific:

    The beta manifest is rolling: Every release — stable included — re-uploads latest.json to the fixed updater-beta pre-release.

    line 782
  11. Very specific:

    External CLI contracts: verify vendor flags against --help, don't guess.

    line 892

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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)

  1. 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.
  2. Correctness over cleverness. No hacky things that break later. When something non-obvious is necessary, leave a short comment explaining why (not what).
  3. Clean, legible code. Reuse shared primitives/hooks; don't duplicate logic. Match the surrounding style. Avoid comments that just restate the code.
  4. The typed bridge is sacred. The frontend never calls invoke or hardcodes data — it goes through query hooks → generated bindings.ts → #[tauri::command].

Tech stack

  • Rust: Tauri 2.11, tauri-specta =2.0.0-rc.25 (pinned with specta/ 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 bundled santree-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: the AgentKind enum, re-exported by santree_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); its REVISION (1 shipped in 0.1.19-beta.1; 2 in 0.1.19-beta.2) is pinned by revision.lock: when its code or linked crates change, bump it if a release carries it, then run UPDATE_REVISION_LOCK=1 cargo test -p santree-server revision; docs/server.md "Versions and draining").
  • Crates the daedalus engine consumes: santree-pty, santree-remote-proto, santree-remote-tls and santree-agent-kind are depended on by git rev from the daedalus engine repo, so their public API and their dependency list are a contract. None may depend on santree-core, Tauri, or (by default) specta — AgentKind's specta::Type sits behind the specta feature, which only santree-core turns on. santree-remote-tls uses 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 than rust-toolchain.toml pins, so they declare rust-version = "1.95" and must keep building on it. They are the only code that runs on Linux (the engine's box): ci.yml's engine-linux job 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-host is 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 in santree-pty and santree-host mark this workspace's sanctioned PTY sites; they are inert in the engine, which has no such clippy.toml. santree-pty's OpenOpts gained base_env and its sinks are now Send + Sync: the engine's session host must move to santree-host in 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.rs holds 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 fixed InProgress/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 the invoke boundary 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 swaps bindings.ts for a shim that lays typed overrides over commands for demo repos only, so everything else, Daedalus included, reaches the real backend. CI's pnpm check:no-demo fails a build whose dist/ carries either world.
  • Domain types live in crates/core/src/domain.rs and derive specta::Type — that's how their shapes reach bindings.ts. Never hand-edit bindings.ts (it's generated; run pnpm gen:bindings after changing a command or Type).
  • Presentation is the frontend's job. Rust ships plain enums; src/theme/colors.ts maps 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 maps

Key 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 by routes/__root.tsx outside 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 pr and aiWork panes (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 through reviews/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) is reviews/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 the pr-fix template (review_ai::fix_prompt renders 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, PrFileBody and the draft/thread cards take their host's callbacks as props (see useStartWork.ts for 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 a git pull is 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 by every_slot_is_an_empty_block_in_its_default) where project-specific knowledge belongs; the editor fills those as fields (SlotEditor, promptLayers.ts is 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 in src-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 through safe_path.
  • Triage is a sidebar section, not a destination. shell/TriageSection is 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 in shell/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 the triage_teams setting (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.rs scope_of over cached TeamFacts, 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), and filterTriageQueue applies both without a refetch. The grouping is shell/triageTeams. Scoped to useTriageOrgRepo'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). useTriageQueue is 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 with TRACKER_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's shell/TrackerConnectPrompt (off useTrackerConnected, null until 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's jira_triage_jql setting matches (Settings → Repo → Ticket tracker; unset is jira::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, and triage_snooze refuses 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 own triage_repo:<id>, else triage_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 through triage/TriageRepoGate (the promise-resolving pattern reviews/WorktreeGate established) and every action goes through one withRepo. Nothing here creates a worktree, and the backend agrees: validate_agent_cwd refuses a triage: 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), else ProjectPickerDialog over just those projects, with a save-as-default switch. The provider is mounted in routes/__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 one navigate(), 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) and useTriageOrgRepo. 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, and CreateWorktreeVars.repo (a var, not a hook argument — the answer arrives at click time).
  • A repo reads one tracker, resolved in one place. repos.connection holds 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 in 0038, recounted in 0039), connection::adopt_sole does 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_id are dead columns. Anything that groups repos "by tracker" (the Tickets fold, the Work gate's candidates) keys on Repo.connection, never on the tracker display label. That answer ships as Repo.provider, read through useTicketProvider(repo). Every provider-neutral command — issues, triage, detail, state, comments, pr_tickets, the work and investigate prompts — dispatches through tracker::*; calling linear:: or jira:: 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's trackerOf(trackerName)). What a connection can do — snooze, threaded replies, which Triage team rules apply — is lib/tracker trackerFeatures (read through useTrackerFeatures), never a view's own provider === "Jira" or via === "Mcp". A Linear org connected through its hosted MCP server (LinearStatus.via) is still TicketProvider::Linear; tracker::repo_tracker sends it to linear_mcp (docs/linear-mcp.md). A list that spans projects hands its selection over with the row's project (issues/model openTicket): 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_id is the guard before any request path; no :, which tree:<id>:tab: splits on). People see the handle tt-<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 its ticktick_lists setting (unset = all open).
  • One right panel, four hosts. components/SidePanel is 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; distinct cssVars, 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 +N for 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 in issues/model.tsx. Collapsed, a rail draws nothing and its host's top strip takes the PanelToggle over at the same right edge (Trees' tab bar, the Tickets header).
  • One main tab strip, three hosts. components/TabStrip is 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 a worktree_tabs row, 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 — ephemeral MainTab literals, never rows, closable), or a session that hangs off the view's own surface rather than a row (an AI review on ai-review:<pr>, a triage investigation on triage:<ticket> — one per provider). A row's owner (worktree_id) is a worktree id, or a triage ticket's triage:<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 from trees/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 a TabStrip over 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: normalize fits 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)); active is 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 (RemoteTerminals over a unix socket); a Daedalus pane is the same RemoteTerminals over the agent's link. sessions::Terminals is the one handle commands hold, and it dispatches by id (one IdRegistry counter; each host answers whether it holds(id)) — new panes name a Route (Local | Daedalus, the caller knows whether a cwd is a Daedalus project's). Which local backend runs is sessions::server_mode(), decided once: Signed (a release whose own signature matches the baked SANTREE_TEAM_ID), OptIn (SANTREE_SERVER=1, uid-only) or Off. Never branch on the backend anywhere else — a match on Mode, Local or 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 with terminal::input's IPC-born types, and opened, attached, adopted and closed only by terminal.rs and the facade's arms (clippy.toml disallowed-methods, its exceptions pinned by compliance.rs). Liveness is Liveness { live, complete }: an incomplete answer keeps agents as they were and refuses a resume. A lost agent tab's Resume is useLostTabResume, 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/conversation draws the live session from Claude's own transcript (conversation_read, incremental by cursor) plus the hooks and status line; santree runs no claude -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.ts pins 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 passes browser::address::checked.
  • One place renders a diff. features/trees/DiffPane picks the source with prDiffModeFor: 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.rs journals retries in worktree_moves; git/split.rs keeps 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 of Worktree.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 through useUnwrappedQuery; raw-value commands use plain useQuery. Writes use useOptimisticMutation (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 in main.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 by gql::send before it fails; a write never is. Raise green toasts with toast.success(...) from state/toast.tsx.
  • Feature state: ephemeral view state lives in features/<view>/model.tsx (a context); shared cross-view state in AppContext; 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 is set_experimental (the generic set_setting refuses those keys: the Daedalus switch starts and stops the link as it is written). Readers are settings::experimental and useExperimental(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 read useOfferedRepos() (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 to ExperimentalFeature and EXPERIMENTAL_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: primitives ContextMenu wraps a region (a row, a card) and opens PositionedMenu at the pointer or from Shift-F10; the graph opens PositionedMenu itself from React Flow's onNodeContextMenu. 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 from components/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 declarative ContextMenuItems — 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) — no text-[Npx]. Radius: rounded-xs… rounded-2xl (3 · 4 · 6 · 8 · 10 · 12) — controls md, cards xl, menus and popovers xl, dialogs 2xl. Elevation: shadow-popover / shadow-dialog, nothing else. Buttons are primitives Button at 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 git argv: paths/ids through git.rs safe_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 — never Path::join or shell them raw. A ticket id bound for Jira passes jira::is_issue_key before it reaches JQL or a request path, and one bound for TickTick passes santree_core::ticktick::split_id before it reaches a request path.
  • Match hosts/URLs by parse at the sink, never by string prefix — url.host_str() == Some("uploads.linear.app"), not starts_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::publish is 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 a github.rs write is the line this feature exists to hold.

Commands

pnpm devRun the app with HMR (regenerates bindings.ts on startup)
pnpm buildtsc --noEmit + production Vite build
pnpm gen:bindingsRegenerate bindings.ts from Rust
pnpm lint / pnpm formatBiome check / autoformat
pnpm test / cargo testVitest / Rust tests
cargo clippyRust 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.mjs signs santree-hook and santree-server from beforeBundleCommand — after staging (pnpm bundle:binaries), before the bundler seals them — and no-ops without APPLE_SIGNING_IDENTITY so keyless builds keep working (with one, a missing binary is an error). The server is signed with identifier com.santree.server and no entitlements. A new resource binary must be added there.
  • santree-server is a bundle resource, declared in tauri.macos.conf.json (merged over tauri.conf.json by JSON merge patch, so bundle.resources keys add up). tauri-build fails on a declared resource that doesn't exist, so every cargo build of src-tauri needs target/bundle-resources/santree-server staged first — pnpm bundle:binaries does 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_ID is 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-variables on 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.sh asserts 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's version --json against, and pgrep -x santree-server after 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.
  • createUpdaterArtifacts is passed via --config in 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=true in the release env re-enables the Finder AppleScript that paints the DMG background and places the icons — with CI=true the bundler otherwise passes --skip-jenkins and ships a default-looking DMG (background.png present but no .DS_Store to use it).
  • TickTick's OAuth client secret is compiled in by option_env! from the release environment's TICKTICK_CLIENT_SECRET (the build step's env), not committed. Drop it from release.yml and the release still builds, but ships without "Sign in with TickTick" (oauthAvailable false; the token path stays). Locally it comes from a cargo [env] outside the repo.
  • The version-free santree-macos.dmg asset exists for the website's releases/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 touching commands.rs, git.rs, terminal.rs, crates/pty, crates/host or crates/server.
  • Hook: editing commands.rs/lib.rs/domain.rs triggers 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.ts and routeTree.gen.ts are generated but committed — don't edit by hand; Biome ignores them.
  • tauri.dev.conf.json carries the whole window entry, not just its title: a --config overlay merges by JSON merge-patch, so an app.windows array replaces the base one — a one-field entry silently dropped titleBarStyle: Overlay and gave the dev build a native title bar, shifting every capture. Keep it a mirror of tauri.conf.json's entry plus the title, and remember tauri dev reads 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 (@theme in src/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 close a session — it detaches, and the session is caught up from its ring on the way back. Only close(key) on a tab ends a process. Read docs/terminals.md before touching crates/pty, terminal.rs, or src/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 in terminal.rs, the root clippy.toml): a new call outside a sanctioned site fails cargo clippy -- -D warnings, and a new #[allow(clippy::disallowed_methods)] fails the_lint_exceptions_are_exactly_the_sanctioned_sites.
  • External CLI contracts: verify vendor flags against --help, don't guess. Claude --model takes dash-form ids or aliases (sonnet/opus/haiku) — dotted (claude-sonnet-4.5) is invalid and fails launch.
  • Codex fires SessionStart on the first turn, not at launch (0.151.0, measured). So a Codex tab that hasn't been prompted has no session_state row and no terminal_sessions binding — 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's AgentTabIdentity), not the hook. Which agent is running has one ordered arbiter — session row → process table → launch record — and what it is doing still has only lib/attention.ts; never let the first answer the second. See docs/terminals.md "Agent state" and "Agent identity".
  • A santree-hook write 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, never cond && <C/> — remount re-fires them.
  • A11y baseline: new interactive elements need keyboard focus + an accessible name; never outline:none without a :focus-visible ring.

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).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.