FAQ

General

Where is my data stored?

All Sidequest data lives in two locations:

• ~/.sidequest/ — worktrees, journals, handoffs, profiles, attachments, extensions, hooks, logs, sounds, the CLIs and the local socket
• Database — ~/Library/Application Support/com.sidequest.app/sidequest.db on macOS, ~/.config/com.sidequest.app/sidequest.db on Linux

See Data and Storage for the full map.

Does anything leave my machine?

Agents talk to their own providers as they always do. Sidequest itself contacts GitHub through gh (issues, PRs, clones), its release feed for updates, and a public pricing file for the cost estimator. There are no accounts and no telemetry.

What happens to my worktrees if I close the app?

Nothing. Worktrees are regular git worktrees on disk — they persist independently of Sidequest. Your quest branches, uncommitted changes, and file modifications are all preserved. When you reopen Sidequest, it reconnects to existing tmux sessions and worktrees.

What happens to running sessions if I close the app?

They keep running. Each agent session runs inside a tmux session, which is independent of the Sidequest process. When you reopen the app, Sidequest detects existing sq- prefixed tmux sessions and reattaches to them. Supervisors keep working too.

Can I use agents other than Claude Code?

Yes: Gemini CLI, Codex CLI, Copilot CLI and OpenCode can run quests. Some features — the smart router, effort levels, profiles, automatic journals, needs-attention status and token statistics — are Claude Code only. See Agents and Models.

Can I use Sidequest with multiple git remotes?

Yes. Sidequest works with whatever remotes your repository has configured. When creating a quest branch, the worktree inherits all remotes from the parent repo since they share the same git object store. GitHub features look for a remote named origin.

Can multiple quests edit the same files?

Technically yes, since each Worktree quest has its own worktree with its own copy of every file. Two quests can modify the same file independently without interfering with each other during development. When merging both branches back, you will encounter standard git merge conflicts. This is no different from two developers editing the same file on separate branches.

How does Sidequest interact with my existing git workflow?

Sidequest creates standard git worktrees and branches. Everything it does is visible to git and compatible with your existing workflow:

• Branches created by quests show up in git branch -a
• Worktrees show up in git worktree list
• You can push quest branches, open PRs, and merge them using any tool
• Sidequest never modifies your main branch or existing branches — it only creates new branches from the base you specify

Does Sidequest modify my tmux or git configuration?

Sidequest does not read or write ~/.tmux.conf or ~/.gitconfig. It sets three options on the running tmux server (escape time, focus events, default terminal) and per-session options (scrollback, mouse mode); none of these are written to disk. Git operations use standard commands without modifying your global or local git settings.

Can I use my own editors and terminals with Sidequest?

Yes. Sidequest has settings for preferred editor (VS Code, IntelliJ IDEA, Zed) and preferred terminal (Terminal.app, iTerm2, Warp, Ghostty, WezTerm, Rio). Right-click menus throughout the app offer “Open in Editor” and “Open in Terminal”; hold Option to pick a different app for one action.

Quest Management

Where did “Research” and “Changes” go?

They were renamed. Current Branch is the old Research type and Worktree is the old Changes type. Nothing else changed, and the CLI accepts both names.

How do I recover a quest that crashed?

If a session crashes or becomes unresponsive:

1. Check if the tmux session is still alive:

   tmux list-sessions | grep sq-

2. If the session exists, click the quest in Sidequest to reattach. Sidequest will detect the stale connection and create a fresh one.
3. If the session is gone, the quest shows (terminated) in the terminal header. Click Restart Session (also in the quest menu). The worktree still exists at ~/.sidequest/worktrees/<quest-id> and Claude Code resumes its previous conversation; other agents start a new one.
4. If the quest is stuck in a bad state, you can delete and recreate it. The branch will still exist in git and can be reused.

What happens when I complete or delete a quest?

Completing a quest interrupts the agent, ends the session and moves the quest to the Recently Completed section. The worktree and branch are kept for the Quest Retention period (default 2 hours) so you can Restore it; after that the worktree is removed and the quest row deleted. The Chronicler writes a journal entry for completed Claude Code quests unless you checked Skip Auto-Journal.

Deleting a quest cleans up in this order:

1. Kills the tmux session (if running)
2. Runs git worktree remove --force from the parent repository
3. Falls back to deleting the worktree directory directly if the git command fails
4. Prunes stale worktree references with git worktree prune
5. Removes the quest record from the database

The git branch itself is not deleted. If you want to remove it, do so manually with git branch -D <branch-name>.

Can I reorder quests in the backlog?

Yes. Drag quests within the backlog to set their order. A supervisor pulls from its own Up next queue on the Supervisors board, which you order the same way.

Why did my quest stop with “Token budget reached”?

You set a token budget on the quest and the session reached it at a turn boundary. The quest stays in Active with its session stopped; edit the quest to raise or clear the budget, then Restart Session.

A quest says “Routing model…” for a long time

The smart router asks Claude which model to use before the first session starts. It times out after 20 seconds and falls back to the Fallback model in Settings > Routing. If it is slow every time, check that the claude CLI works from a terminal, or turn routing off.

Supervisors

Why does the supervisor need --dangerously-skip-permissions?

The supervisor runs autonomously as a long-lived Claude Code session that monitors and manages other sessions. It needs to run sqlite3 and tmux commands without manual approval for each action. This flag is set only on supervisor sessions; regular quests use auto mode by default.

I don’t see a supervisor toggle on my project

Supervisors moved to their own board in 0.65. Click the robot in the bottom toolbar, create a supervisor, and drag quests (or whole projects) onto it. See Supervisors.

Can I run multiple supervisors?

Yes, as many as you like, each watching its own group of quests from any projects. A supervisor can also report to another supervisor. Sessions are named sq-supervisor-<supervisor-id>.

The supervisor stopped unexpectedly. What happened?

Common causes:

• No work left. A supervisor stops itself once all of its quests are completed or unassigned, unless it has recurring quests attached or is the parent of another supervisor.
• Claude API error. If the session hits a persistent API error, it may exit. Click the speech bubble on its sheet to read its terminal.
• tmux killed externally. If the sq-supervisor-<id> session is killed from the command line, the supervisor stops.

To restart: click Start on the sheet, or turn on Auto-start when work is waiting so it starts whenever it has quests.

The supervisor keeps starting on its own

Auto-start when work is waiting is on. Clicking Stop keeps it stopped until its work count drops to zero and new work arrives; turn the option off to stop it for good.

Journals

Why didn’t my completed quest get a journal entry?

The Chronicler skips quests that opted out (Skip Auto-Journal), quests spawned by a recurring quest without Journal each run, quests on agents other than Claude Code, conversations that are missing or very short, and work it judges routine (version bumps, typo fixes). It also only runs when Chronicle completed quests automatically is on; quests completed while it was off are never chronicled later. Entries usually appear within five minutes of completion.

How do agents find journals?

Each new quest is shown up to three entries matched to its title, and can search the rest with sidequest-journal search. See Journals and Sidequest CLI.

Troubleshooting

”tmux is not installed”

Sidequest requires tmux for session management. Install it:

# macOS
brew install tmux

# Debian/Ubuntu
sudo apt install tmux

# Fedora
sudo dnf install tmux

If tmux is installed in a non-standard location, set the path in Settings > Tools.

Claude binary not found

When launched from Finder, macOS apps inherit a minimal PATH that may not include Homebrew or nvm directories. Sidequest resolves the Claude binary path through your login shell, but if this fails:

1. Open Settings (Cmd+,) > Agent
2. Set the full path to claude (e.g., /Users/you/.nvm/versions/node/v22.x/bin/claude) and confirm the field shows Detected
3. Restart Sidequest

Find the path with:

which claude

The same applies to gemini, codex, copilot and opencode.

Quests show “Needs attention” but the agent is not waiting

The indicator is triggered by Claude Code’s Stop hook. If the hook fires but Claude has already continued (e.g., it paused briefly then resumed), the indicator may be stale. Click the quest to clear it. If this happens frequently, check that the hook script at ~/.sidequest/hooks/on-claude-stop.sh is current — disable and re-enable notifications in Settings to reinstall it.

Quests never show “Needs attention”

Notifications are off. Enable them in Settings > Notifications to install the Stop hook. Quests on agents other than Claude Code do not report this status.

Orphaned worktrees taking up disk space

Settings > Storage > Worktree Storage lists worktrees that are orphaned or belong to completed quests, with their sizes, and offers Reclaim All. To do it by hand:

# List Sidequest worktrees
ls ~/.sidequest/worktrees/

# Remove a specific orphan
rm -rf ~/.sidequest/worktrees/<quest-id>

# Prune git references in your repo
cd ~/your-repo && git worktree prune

Unicode characters showing as underscores in the terminal

This happens when tmux does not have a UTF-8 locale. Sidequest sets LANG=en_US.UTF-8 when creating sessions, but your system must have this locale available:

locale -a | grep UTF-8

Icons in the terminal look wrong

Claude Code draws some of its interface with Nerd Font glyphs. Install one (Fira Code, MesloLGS, Hack or JetBrains Mono Nerd Font) and pick it in Settings > Appearance > Terminal > Font Family.

The database seems corrupted

The SQLite database can be inspected directly:

sqlite3 ~/Library/Application\ Support/com.sidequest.app/sidequest.db ".tables"

If the database is corrupted, quit Sidequest, rename the database file as a backup, and relaunch. Sidequest will create a fresh database with all migrations applied. Your worktrees, branches and journals will still exist on disk but quests will need to be recreated.

High CPU or memory usage

Each active quest runs an agent process inside tmux. If many are active simultaneously, lower your supervisors’ ceilings or complete quests that are finished. The Active quests timeline in the bottom toolbar shows everything running across projects and flags quests that have gone quiet, and the Live Stats panel helps identify expensive sessions.