Quickstart

Five-minute walkthrough — pick an issue, work on it, ship a PR. Assumes you’ve finished Installation.

  1. 1. Pick your tracker
  2. 2. Open the dashboard
  3. 3. Start working on a ticket
  4. 4. Iterate with the inline diff
  5. 5. Commit, push, and PR — without leaving the dashboard
  6. What just happened

1. Pick your tracker

If you set this during Installation via santree config, you already did this — skip to step 2.

Otherwise, from inside any repo where you want santree to surface issues, run:

santree config

Under This repo, select the Issue tracker row and pick Local (built-in, no account), Linear (opens the browser for OAuth right there if you’re not logged in), or GitHub (uses the existing gh CLI — run gh auth login first if it tells you to). It switches instantly and only needs doing once per repo. See Trackers for the full setup.

2. Open the dashboard 

santree dashboard

You’ll see a two-pane TUI: assigned issues on the left, detail on the right. Mouse + keyboard both work — click a row to select, drag the divider to resize, scroll wheel scrolls.

3. Start working on a ticket

Select an issue and press w. A mode-select overlay asks plan-vs-implement, then opens a context input where you can add custom instructions to the prompt (Ctrl+O to drop into your editor). Press Enter to launch.

What happens behind the scenes:

  1. A worktree is created at .santree/worktrees/<TICKET-ID>/ from the base branch.
  2. (Optional) .santree/init.sh runs to set up env files / dependencies.
  3. A new tmux/cmux window is opened in the worktree.
  4. Claude is launched with the rendered ticket + your context as input.

4. Iterate with the inline diff

Back in the dashboard, press [v] on the issue to open the diff overlay. Left pane is the file tree, right pane shows the diff content. Use j/k to move between files, J/K to scroll the diff.

The diff is branch-only — it uses git merge-base against the configured base, so upstream changes you haven’t pulled don’t leak in. Same scope as a GitHub PR diff.

Install delta (brew install git-delta) and set it as your diff tool in santree config (Global → Diff tool) to get syntax highlighting in the overlay. Works for both worktree diffs and Reviews-tab PR diffs. (SANTREE_DIFF_TOOL=delta also works as a one-off override.)

5. Commit, push, and PR — without leaving the dashboard

Key Action
[C] Stage + commit + push (inline message input or --fill from Claude)
[c] Create the PR (fill template via Claude with a draft/ready toggle, or open the new-PR page pre-filled in the browser)
[r] Self-review the PR with Claude
[f] Apply review comments / CI failures with Claude

Once the PR is merged, [d] removes the worktree, or santree worktree clean does it in bulk for any branch whose PR is merged or closed.

What just happened

You went from “pick an issue” to “open PR” without leaving the terminal. Each stage corresponds to a node in the Workflow diagram. The mental model behind it lives in Concepts.