santree docs

Download santree for macOS. It’s a signed, notarized DMG. It keeps itself up to date after that. Prefer to see the machinery? Build from source instead.

First launch

santree asks you to add a project: pick any folder inside a git checkout. It appears in the sidebar with its own checkout as the first row, and the views light up as you connect things. Add more projects any time from the + beside Projects; every setting can be overridden per project.

What you need

• git. Worktrees, diffs, and branches are real git.
• At least one coding agent: Codex or Claude Code, installed and logged in. santree drives the CLI you already have, on your existing subscription. It never reads or stores either CLI’s credentials.
• GitHub CLI (gh), signed in. Optional; it powers Reviews, the PR panes and the checks.
• A Linear workspace or a Jira Cloud site. Optional; it powers Tickets and Triage, and each project picks which one it reads.

Nothing is required up front: without a connection a view shows its real, empty state. There is no sample data anywhere in santree.

The current list. Everything else on this site speaks of trackers, code hosts and agents in general, so this is the one place that names them.

• Ticket trackers: Linear and Jira Cloud, chosen per project.
• Code hosts: GitHub, through the gh CLI or a personal access token.
• Agents: Claude Code and Codex, the real CLIs, each picked per workflow.

Linear

Settings → General → Linear → Connect. You authorize in the browser; the token is stored in the OS keychain, never in plaintext. If you belong to several workspaces, each project picks which one it reads from.

GitHub

Run gh auth login in any terminal and santree picks it up. Prefer not to install gh? Paste a personal access token instead. It also lives in the keychain.

Agents

Settings → General shows Claude Code and Codex side by side: whether each is installed, logged in, and up to date. The Triage, Work and Reviews tabs pick a provider, a model, an effort and a permission mode per workflow, so an investigation can run on one agent and the work on another. A worktree can hold sessions from both.

Environment

Settings → Environment holds variables (or .env file references) injected into every terminal santree spawns, app-wide, with per-project overrides. A project’s .santree/init.sh runs when a worktree is created, so a fresh checkout arrives with its dependencies installed.

The sidebar is the app’s index and it never leaves. Top to bottom: Search (⌘K, the one search across tickets, worktrees, PRs and destinations), Tickets, the Triage section, then every project with its pull requests waiting on you, its own checkout, and its worktrees grouped the way Linear groups them: project, then milestone.

Under each worktree sit the agents running in it, and every one carries a dot: working, just finished, or needs you, which is a permission prompt or a question you haven’t answered. The status bar counts them across every project. A project’s header and a worktree’s row roll the most urgent dot up, so a red dot on a folded section is a reason to open it.

A worktree’s Linear and GitHub marks open the ticket and the pull request as tabs. Right-click a worktree, a ticket or a pull request for everything you can do to it, including deleting the tree once it has merged.

Your Linear queue, as a list grouped by project and milestone or as the dependency graph it is. Each row carries the ticket’s priority, status, cycle, estimate, due date and assignee, and one thing more: Ready when nothing blocks it, or the ticket that does. A ticket already started shows its worktree and its pull request.

Run starts a ticket: a new worktree, the agent configured for Work, and the ticket’s prompt already typed. ⌘Click queues tickets instead; the Queue pane in the right panel holds them with a per-ticket agent pick and notes, and Launch starts them all. A blocked ticket can chain its branch off its blocker’s, so stacked work stays stacked. When more than one project shares a ticket’s workspace, the first start asks which one and offers to remember it (Settings → Work).

Trees is where you’ll spend most of your time. Every task lives in its own git worktree, so five agents can run at once and never step on each other’s diff, and your own checkout stays clean. Pick a worktree in the sidebar and its workspace fills the window.

The main area is a tab strip: one tab per agent or shell the worktree has open, plus whatever you expand into it. ⌘T opens another Claude, Codex or terminal. Every terminal is a real PTY running the real CLI: interrupt it, answer it, run vim in it. Tabs survive a restart, and closing one ends its process.

The right panel (⌘L) is reference beside the work: the ticket, the files, the branch’s changes with staging and a commit box that can draft the message, and session history, where any past conversation resumes in a new tab, with what it cost. Once the branch has a pull request, two more panes appear: the PR and its work queue.

A PR you opened is worked on next to its worktree, not in the review inbox. Create PR sits above the changes and can draft the title and body from the branch. The PR pane shows its state, checks and conversation, and expands into the full page: Conversation, Commits, Checks with their logs, Files changed.

The AI work pane is the queue. A failing check, a reviewer’s comment, a draft from an AI review, or a line you flag in the diff each land in it as one item. Start work hands the open items to an agent in a new tab, with a prompt you can edit in Settings → Prompts.

Reviews is the inbox: other people’s pull requests, per project, ordered by what needs you. Each project’s Reviews row in the sidebar lists what was asked of you and what was asked of your teams; the number on it is what you haven’t answered since the author last pushed.

The Pull Request tab is the whole PR: the description and comments, the commits, the checks with logs inline, and the files with review threads anchored to GitHub’s own diff. Review with AI checks the branch out into a worktree and starts an agent that writes a brief (what changed, in what order to read it, what to watch out for) and draft comments on the diff. Drafts stay on your machine; you edit them, drop them, and publish the ones you keep into your pending review. Nothing an agent writes reaches GitHub without your click.

Your team’s triage queue lives in the sidebar: who is on rotation and until when, the tickets waiting with their SLA clock, soonest first, and a folded Snoozed group. Mine / All on the section’s title switches between your tickets and the whole team’s. Right-click a ticket to snooze it.

Opening a ticket gives it a workspace: the Linear tab with the ticket and its discussion, one tab per Investigate agent (⌘I), and a shell. Investigations run on a project you attach to the ticket, on that project’s main checkout; no worktree is created. The first thing that needs one asks which project, with a default you can set in Settings → Triage.

⌘, opens Settings as a page. General has the theme, updates, and the Linear, GitHub, Claude Code and Codex connections. Triage, Work and Reviews each pick an agent, a model, an effort and a permission mode. Prompts holds every prompt a launch renders (the investigation, the work prompt, the AI review, the work queue) as Jinja templates you can edit and preview against a real ticket. Environment, Terminal and Usage round it out. Each setting is app-wide with a per-project override.

The canonical list lives in the app. Press ⌘/ anywhere. The ones worth memorizing:

santree updates itself. Settings → General → Updates shows your version, checks on demand, and picks the release channel: Stable (the default) or Beta, which gets every release as soon as it builds.

Updates only move forward. Switching from Beta back to Stable takes effect once a stable release passes the beta you’re on.

• Your code stays on disk. Agents run locally, in worktrees of your repo. santree sends nothing anywhere on its own.
• Your agent’s login is its own. santree runs the unmodified CLI in a real terminal. It never reads, stores, or proxies the agent’s credentials, and never drives it unattended.
• Nothing an agent writes reaches GitHub without a click. An AI review’s drafts are rows on your machine until you publish them into your own pending review.
• Integration tokens live in the OS keychain, Linear OAuth and GitHub tokens alike, never plaintext.
• The only network traffic is the integrations you connect: Linear for tickets, GitHub for PRs, and whatever your agent CLI talks to.

The constraints around agent CLIs are written down and load-bearing: COMPLIANCE.md.

A view is empty

That’s the real state, not a bug. santree never fabricates data. No Linear connection means no tickets; no gh auth means no reviews. Connect the tool and refresh (⌘⇧R).

An agent shows as idle while it’s clearly working

The dot comes from the agent’s own hooks, which santree adds to every launch. An agent started outside santree, or a Codex tab that hasn’t been prompted yet, reports nothing until its first turn; the sidebar then reads the process itself. If a hook write failed, the reason is in ~/Library/Application Support/com.santree.desktop/santree-hook-errors.log.

Logs

Rust and webview logs land in ~/Library/Logs/com.santree.desktop/santree.log on macOS. Attach the tail when filing an issue.

Something else

Open an issue. Pre-release means fast-moving, and reports genuinely steer what gets fixed next.