FAQ & Troubleshooting

  1. Why a separate worktree per branch instead of just git checkout?
  2. Why do I need the shell integration?
  3. My dashboard is empty
  4. st --version shows a different version than my repo
  5. Diff overlay shows no syntax highlighting
  6. Diff overlay text is wrapping weirdly / cut in half
  7. Claude says “I don’t have permission to read /tmp/santree-images-…”
  8. cmux’s sendCommand doesn’t work
  9. My terminal theme switched but the dashboard didn’t follow
  10. Where do tokens live?
  11. How do I stop the auto-refresh?
  12. I want a different prompt

Why a separate worktree per branch instead of just git checkout?

Switching branches with git checkout overwrites your working tree. If you have an in-progress feature, you stash, switch, do the other thing, switch back, pop, and hope nothing collided. Worktrees skip all of that — every branch has its own directory, so your editor, terminal, and Claude session stay where you left them.

The trade-off is disk space (one checkout per active branch) and a bit of structure (.santree/worktrees/<TICKET-ID>/). For most workflows it’s a net win.

Why do I need the shell integration?

Commands like worktree create and worktree switch need to change the directory of the parent shell. A child process can’t do that on its own — when santree exits, the shell’s cwd is unchanged. The wrapper reads marker lines from santree’s stdout (SANTREE_CD:<path>, SANTREE_WORK:<mode>) and cds on your behalf.

Without the shell integration, you can still use santree, but you’ll have to cd manually after each command.

My dashboard is empty

Some possibilities:

  • No tracker authed: run santree linear auth or santree github auth. The dashboard speaks to whichever tracker is active for the repo.
  • Tracker mismatch: maybe the repo’s _tracker.kind is set to one backend but you’re authed for the other. Check with santree doctor, or set explicitly with santree issue switch <linear|github>.
  • GitHub Issues — no assignees: gh search issues --assignee=@me returns nothing if your team uses Projects without assignees. Self-assign the issues you’re working on.
  • Cross-repo issues: only current-repo issues are surfaced today.

st --version shows a different version than my repo

You probably have both a globally-installed santree and an npm linked dev copy. which st will tell you which binary is winning. Re-link with npm link from the repo, or uninstall the global version.

Diff overlay shows no syntax highlighting

You haven’t set SANTREE_DIFF_TOOL. Install delta (brew install git-delta on macOS) and:

export SANTREE_DIFF_TOOL=delta

Both the worktree diff ([v] on a worktree row) and the Reviews-tab diff ([v] on a PR with no local worktree) honor this.

Diff overlay text is wrapping weirdly / cut in half

Ink’s built-in wrap="truncate" measures by string length and counts ANSI escape bytes as visible characters, which makes color-heavy lines wrap very early. Santree works around this with its own truncator (truncateVisible()) and SGR-splitter (splitCombinedSgr()). If you still see wrapping, file an issue with a screenshot — there may be an escape pattern we haven’t seen yet.

Claude says “I don’t have permission to read /tmp/santree-images-…”

This was a known bug fixed by passing --allowedTools Read to the Claude CLI when running the PR-fill flow, so the agent can read locally-downloaded ticket images. If you see this on a recent santree, file an issue.

cmux’s sendCommand doesn’t work

That’s manaflow-ai/cmux#1472 — programmatically created cmux workspaces have dead PTYs. tmux is the recommended backend until that’s fixed. santree doctor flags this when cmux is active.

My terminal theme switched but the dashboard didn’t follow

SANTREE_THEME=auto polls the terminal background via OSC 11 on each refresh (every ~30s). If your terminal doesn’t respond to OSC 11 — some legacy terminals don’t — set the theme explicitly:

export SANTREE_THEME=light    # or dark

Where do tokens live?

~/.config/santree/auth.json (or $XDG_CONFIG_HOME/santree/auth.json). The file is versioned — v1 (Linear-flat) is migrated to v2 ({version:2, linear, github}) on first read. The github namespace is reserved — gh owns its own token, santree never writes one.

How do I stop the auto-refresh?

You can’t, but it’s cheap. The dashboard fetches issues + worktree status + PR info + checks + reviews every 30s in parallel. Force a refresh anytime with R.

I want a different prompt

Edit the templates in prompts/. They’re Nunjucks, get rendered with the issue + diff + PR context, and passed to Claude. Most behavior (style, scope, what to ask for) lives in those templates — change them, rebuild, run.