Skip to content
JakeAvePublic

About

A dashboard for git worktrees across every repo in one directory — dirty state, ahead/behind, open PRs, listening dev servers, and a diff viewer with per-hunk staging.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

277 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

forest

A dashboard for git worktrees across every repo in one directory. Scans a root folder, finds each repo and its worktrees, and shows what's dirty, what's ahead or behind, which has an open PR, and which is running a dev server right now — with a built-in diff viewer you can stage, discard, and edit from.

Deno server + Svelte frontend. No database, no config to write by hand.

Forest showing worktrees across six repos, a worktree's changed files, and a side-by-side diff

Quick start

macOS only for now (it reads lsof and macOS app paths). Needs Deno 2, Node 20.19+ (for Vite 7), and git. PR badges also need the gh CLI, authenticated (gh auth login) — without it, Forest runs with PR badges off and says why in a notice under the title bar.

git clone https://github.com/JakeAve/forest.git && cd forest
deno task start --open

start installs frontend deps, builds dist/, starts the server on http://forest-app.localhost:38471, and with --open opens it in your browser. Leave it running in a terminal; Ctrl-C stops it. Re-run it after pulling.

Set root to the directory your repos live in — whatever that is on your machine — via the ⚙ settings panel, or write it directly:

mkdir -p ~/.forest && echo '{"root":"~/your-repos-dir"}' > ~/.forest/settings.json

A leading ~ is expanded. The path is scanned one level deep: every immediate subdirectory containing a .git counts as a repo.

Settings marked "restart" in the table below need one; everything else applies live. watch is the one setting the settings panel can't toggle — edit the file.

What it shows

Each worktree row reads, under a header of column labels: branch, PR title, ticket, PR number with its status word and age (#812 needs review 30m), dirty-file count, ahead/behind arrows, the first listening port (linked, click to open) with +n for the rest (click it to open any of them), the coding agent badge, and last activity. Zero counts stay blank, and a merged or closed PR dims its whole row. Right-click the header row to show or hide columns, drag a header to reorder, or use the Columns section in ⚙. Activity means the newest of the HEAD commit and the mtime of any changed or untracked file, so a worktree you're editing sorts to the top before you commit anything.

Pinned, Recent and All worktrees are collapsible containers, and each repo nests under All. Recent holds the most recently active worktrees; pin one from its right-click menu to keep it in Pinned. A worktree shown in Pinned or Recent is not repeated under its repo, and a collapsed container shows its count and a summary of PRs that need attention (25 · 1 failing). Fuzzy-filter by branch or repo name (dc finds discount-codes), or narrow to dirty-only / running-only.

Right-click a worktree to open it, copy its path or branch, view or create its PR, push, rebase onto origin/HEAD, update the branch, enable auto-merge, mark a PR draft or ready, close it, kill a process running in it, turn on auto-rebase, or remove the worktree. Select several to copy or remove them together. Right-click a repo for new worktree. Hover a row for its checkbox, or ⌘-click, ⇧-click, or press Space to add it to the selection.

A badge on the row names the coding agent session that created the worktree. Forest finds it by reading agent transcripts (~/.claude/projects, ~/.codex/sessions) for the earliest mention of the worktree's path (a main checkout on a feature branch instead matches sessions that ran in it on that branch, cd'd or git -C'd into it, or mention its ticket key); a count on the badge means several sessions worked inside it. Click the badge to list every session that mentions the worktree, most likely creator first, and pick one to open it in its desktop app (claude://resume, codex://threads/); right-click resumes the most likely one directly. A session's › (or right-click, or →) swaps the list for its actions: open in its app, resume in Terminal (claude --resume / codex resume in the directory it started in), copy its ID or its resume link. Keys: a opens the selected worktree's list and ⌥⌘A resumes its most likely session; in the list ↑/↓ (or whatever moves between worktrees) step, ↩ opens, →/← enter and leave a session's actions, and t, c, l resume in terminal, copy the ID, copy the link. They're rebindable under Agent sessions in the shortcuts overlay. Another agent is one entry in PROVIDERS in agents.ts.

Auto-rebase keeps a worktree current with origin/HEAD on a timer (autoRebaseMs). A branch with an open PR is updated on GitHub, the same merge-from-base as the card's update-branch button, and fast-forwarded locally once that lands; any other branch is rebased locally and never pushed. A dirty worktree, one mid-rebase or -merge, or one with unpushed commits is left alone for that tick. A failed attempt shows as a red ↻ on the row with the error as its tooltip, and isn't retried until origin/HEAD moves again. The set of worktrees lives in ~/.forest/autorebase.json.

Selecting a worktree lists its changed files, either since the branch point (merge-base with origin/HEAD) or just uncommitted. Selecting a file opens a CodeMirror diff you can stage or discard by hunk, edit in place, and save — saves are guarded by a compare-and-swap against what was on disk, so a concurrent write returns 409 instead of clobbering.

Switch the files band to all files to browse every file as a tree; gitignored files and folders are dimmed, and an ignored folder lists its contents one level at a time as you expand it. Dependency and cache folders (node_modules, .venv, target, vendor, …) are treated the same even when nothing ignores them, and temporary roots never walk into them. Changed files keep their status letter. Files open in a single editable pane, with a view/diff toggle when they have changes. Binary files and anything over 1 MB show a stub instead. Right-click any file for its relative or absolute path, or press ⌥⇧⌘C / ⌥⌘C for the open one.

Port detection reads lsof and maps listening PIDs to their cwd, then to the owning worktree. PRs come from gh pr list, so PR badges need the gh CLI authenticated; everything else works without it. Click a PR badge (or press p) for its card (⌘-click opens the PR on GitHub). The card is filled by one GraphQL query per open PR: merge state with an update-branch button and auto-merge checkbox, reviewers who have responded (pending requests collapsed), unresolved code threads with the rest collapsed, comments (collapsed), and checks with run time and finish time, optional ones collapsed. Every review, thread, comment and check links to GitHub.

⌘O (or clicking the path in the Files header) turns it into a path box for opening anything: absolute paths, ~/…, a trailing /, path:line / path:line:col, file:// URLs, quoted paths, and relative paths (resolved against the selected worktree or folder). A path inside a scanned worktree selects that worktree in all-files mode with the file opened and scrolled to the line, or the folder expanded. Anything else — a file or folder outside every scanned repo, e.g. in ~/Downloads — opens as a temporary root: the files pane lists that folder (a file's parent, with the file selected), capped at 5000 files. No git features there, but editing and ⌘S work. Temporary roots last until the server restarts.

The layout buttons in the title bar arrange the three panes as a stack, a worktree sidebar beside files over source, three columns, or a rail of worktrees over files beside a full-height source. Worktree rows stay on one line: when the pane is too narrow, the list scrolls sideways. Each layout keeps its own sizes; drag the gaps between panes (or focus one and use the arrow keys) to resize, and double-click a gap between stacked panes to collapse the one above.

⌘K or ⌘P opens the command palette from anywhere, the editor included. It fuzzy-searches worktrees, repos, and the selected worktree's folders and files, plus commands (settings, layout, pane maximize, file modes, wrap, filters, theme) and the selected worktree's context-menu actions. "Filter branches…" and "Filter files…" drive the pane filters live from the palette, listing the best matches first. "Grep…" searches file contents (case-insensitive, gitignored files skipped) and opens a hit at its line. Start the query with > to see only commands and actions. Tab or → drills into an item's actions (a worktree's or repo's context menu, the theme list); ← or Backspace on an empty query goes back.

Agents

The daemon exposes the same data to agents, over plain /api/t/<name> and over MCP at /mcp. Read tools take GET /api/t/<name>?k=v; write tools take POST /api/t/<name> with a JSON body (see Write tools). A wt is any unique substring of a branch or repo name (or a full path), and an ambiguous one comes back as an error listing the candidates (repo, branch, path) (a 400 over /api/t/, a tool error over MCP). wt also accepts any path inside a worktree, ~/… included. q is looser: it fuzzy-matches like the UI filters (branch, repo, ticket key and #PR for wts, plus a substring of an agent session title or id; file path for files), and wrapped in /slashes/ it is a case-insensitive regex, with ^/$ anchoring each field.

tool params returns
snapshot — every repo, with worktrees
wts q, dirty, running, pr, recent worktrees, newest first
whoami path the worktree owning a path
sessions wt, id, q agent sessions, in full
files wt, q, base=branch|head changed files
link wt, file, line, base { url }
wait wt, for, seen, timeout events, [] on timeout

Write tools:

tool kind params returns
set_auto_merge write wt, enable { pr, autoMerge }
set_auto_rebase write wt, enable { wt, autoRebase }
set_auto_close write wt, enable { wt, ticket, autoClose }
create_wt write repo, slug { repo, slug }
remove_wts destructive wts (an array) { removed, refused }

Worktree rows carry a slim agents list (agent, id, title, seenAt, deep), the coding agent sessions that mention them, most likely creator first. sessions has the rest: each session's cwd, transcript file path, resume url and terminal command, tagged created / worked here / mentioned for a worktree. wt lists a worktree's sessions, id (or a unique prefix) gives one session and the worktrees it touched, and q fuzzy-matches titles. An agent landing in a worktree can read the transcript of the session that made it to pick up its context.

That URL is the deep-link contract, and it works typed by hand too: /?wt=<path>&file=<path>&line=<n>&base=branch|head&tree=1 opens the worktree, selects the file, and scrolls to the line; tree=1 opens it in the all-files view. A temporary root (see ⌘O above) uses ?path=<folder>&file=<rel>&line=<n> instead of wt.

curl -s 'forest-server.localhost:38471/api/t/wts?q=1234&recent=3'
claude mcp add --transport http forest http://forest-server.localhost:38471/mcp

*.localhost resolves to loopback with no setup. Existing installs re-run claude mcp remove forest before the add above.

wait blocks until the worktree has one of the notification kinds in for active (comma-separated kinds, or the groups act, move, life, clean), then returns them. It reads the same facts as the inbox but ignores notify settings, mutes and snoozes. A kind that is already true returns at once, so a wait started after a PR merged still sees pr-merged. To wait for the next event instead, pass the keys you have handled back in seen. A seen key is skipped until it clears, so a check that fails again after a fix still wakes you. Edge-only kinds (dequeued, wt-removed, server-died, wt-added, branch-switched, automerge-changed) are never "already true": they return when the edge happens during the wait. timeout is in seconds (default 600, max 3600, 0 for a single check). Over MCP the call holds the agent's tool slot until it returns, so keep timeout short there. For long waits an agent should run the curl form below as a background command, which costs no tokens while it waits:

until out=$(curl -s --max-time 3700 'forest-server.localhost:38471/api/t/wait?wt=1234&for=pr-merged,act&timeout=3600'); do sleep 2; done; echo "$out"

A restart drops every pending wait, so the loop retries until the server is back. It retries only when the connection fails; an error such as an ambiguous wt comes back as JSON and ends the loop. seen lives with the caller, so a retried wait sees level kinds as before, but edge-only kinds that fired while the server was down are not replayed. Over MCP, a failed call after a restart means call again with the same seen. The inbox does catch up: the boot cache seeds the previous state, so a change made during the restart notifies once, and nothing already true re-fires.

Write tools

Agent tools started out read-only. Writes are being added a few at a time, in three tiers. A tool moves up a tier only when the server can enforce that tier's guarantee. A rule in the tool's description doesn't count, because an agent that has read a PR comment or a web page can be talked out of it.

tier guarantee over /api/t/ MCP annotation
read changes nothing GET readOnlyHint
write calling it again with the opposite value undoes it POST —
destructive refuses anything that would lose work POST destructiveHint
  • set_auto_merge toggles GitHub auto-merge (squash) on a worktree's open PR. GitHub still waits for checks and reviews, so it is the reversible form of a merge. Turning it off on a PR that already merged or closed is a no-op, not an error.
  • set_auto_rebase toggles the same auto-rebase as the row's menu.
  • set_auto_close toggles close-ticket-on-merge (below). Turning it on refuses a worktree without a ticket status; with no PR yet it waits for one, and on an already-merged PR it closes the ticket right away. It holds while another worktree on the same ticket key has an open PR, so a ticket split across PRs closes when the last one merges.
  • create_wt makes a worktree and branch slug in repo (its name, as in snapshot), through that repo's launcher command when one is set in Settings, else git worktree add. A slug with .. or a leading - is refused. remove_wts undoes it.
  • remove_wts runs git worktree remove without --force, so branches and their commits stay. It skips, and lists under refused, the primary checkout, a worktree with uncommitted or untracked changes, one mid-rebase or mid-merge, and one with a listening process.

Writes take POST because any page in your browser can make a GET (an <img>, a link). A POST then passes the same Host and Origin checks as the UI's own writes (see Settings). Every write call goes to ~/.forest/forest-log.jsonl as a type: "agentTool" line, with its args and its result or error.

The annotations let the agent decide what needs your approval. In Claude Code, allow the write tools once and keep the prompt on remove_wts:

{
  "permissions": {
    "allow": [
      "mcp__forest__set_auto_merge",
      "mcp__forest__set_auto_rebase",
      "mcp__forest__set_auto_close",
      "mcp__forest__create_wt"
    ]
  }
}

Not exposed yet: merging now, closing a PR, push, discard, killing a process, and --force removal. Each one either can't be undone or lets an agent reach past these guards. Each stays a UI-only action until it can be scoped down to one of the tiers above.

A new write tool sets kind in tools.ts and calls the same function as its UI route (actions.ts, autorebase.ts), so the UI and the agent refresh the same way. Its test shows each refusal.

Settings

Stored at ~/.forest/settings.json — only values that differ from the defaults are written.

key default
port 38471 server port (restart)
host 127.0.0.1 address the server binds (restart)
root ~ directory scanned for repos (restart)
pollMs 5000 rescan tick; with watch on, ports and PRs only
prPollMs 60000 PR refresh for a repo with an open PR
prIdleMs 300000 PR refresh for a repo without one
autoRebaseMs 300000 how often auto-rebase worktrees follow origin/HEAD
watch true recompute on file events instead of polling (restart to turn on)
watchDebounceMs 300 quiet time after an event before recomputing
watchMaxWaitMs 2000 longest a steady event stream defers a recompute
watchSweepMs 300000 full rescan anyway, in case events were dropped
watchHotThreshold 10 recomputes per minute before a repo backs off
watchBackoffMaxMs 30000 longest backoff for a hot repo
watchStormRate 2000 events/sec past which forest falls back to polling
recentCount 10 rows in the Recent group
agentsShown 10 most agent sessions listed per worktree
agoRefreshMs 30000 how often relative times re-render
toastMs 7000 toast lifetime
collapseMargin 3 context lines kept around a hunk
collapseMinSize 5 shortest run of unchanged lines that collapses
launchers {} per-repo worktree-creation commands
terminal Terminal "Open terminal here" command, see Terminal
tickets {} per-repo ticket URL templates
ticketCmds {} per-repo ticket status commands
ticketPollMs 300000 how often a ticket's status is re-fetched
keys {} keyboard shortcut overrides
columns [] worktree columns shown, in order; empty = default (all but title)

host defaults to loopback for a reason: setting it to 0.0.0.0 serves your repositories unauthenticated to everything on the LAN, including file contents and every UI action (save, discard, push, close PR, remove worktree). /mcp checks that the Host header is localhost or forest-server.localhost, which stops DNS rebinding from a browser but not a LAN client that sends that header itself. Every non-GET /api/ request gets the same Host check and is refused unless its Origin is absent or a local one on port 38471, 38472 or the port it arrived on, so another site's page can't post to it. Opening a path outside every scanned repo (⌘O, above) only answers requests from this machine — a loopback address and a Host of localhost, 127.0.0.1, [::1] or forest-app.localhost — even when host is 0.0.0.0.

Notifications

Every kind is off by default: set notify[kind] to app, os or both in settings to turn one on. Events land in an in-memory inbox (notifyMax) and macOS gets one grouped banner per cycle.

route body returns
GET /api/notify events, newest first
POST /api/notify/read { "ids": [...] } or { "all": true } { "ok": true }
POST /api/notify/snooze { "key": "..." } { "ok": true }

Sound is separate from delivery. notifySound maps a kind (or *) to one of:

value plays
Glass a macOS system sound from /System/Library/Sounds
~/sounds/ding.mp3 any audio file, through afplay
say, say:Samantha the title and body spoken, optionally in a voice
say:Daniel:PR {pr} your own words; {repo} {wt} {pr} {title} {body}
hook:~/bin/note.sh your command, with the event as JSON on stdin
{
  "notify": { "ci-failed": "app" },
  "notifySound": { "ci-failed": "Basso", "*": "Pop" }
}

Every event gets its sound, one at a time in arrival order; hooks wait their turn too, and one that runs past 30 s stops holding up the queue. A kind set to app and given a sound alerts without a macOS banner.

Launchers

By default, "new worktree" runs git worktree add <repo>-wt/<slug> -b <slug>. If a repo needs setup beyond that — copying an .env, installing deps — give it a command template. Tokens {slug}, {repo}, {path}, {root} are substituted; * is the fallback for repos without their own entry.

{ "launchers": { "*": "./scripts/new-worktree.sh {slug}" } }

Terminal

Right-click a worktree, file or folder → "Open terminal here" (⌃` for the selected folder, else the selected worktree) runs terminal in that folder. {path} is substituted already shell-quoted, and appended when the command has no {. The default is open -a Terminal {path}; any terminal works, e.g. open -a Ghostty {path} or wezterm start --cwd {path}.

{ "terminal": "open -a iTerm {path}" }

Tickets

A worktree card links the first ticket key found in its branch name, PR title or last commit subject: Jira, Linear and Shipyard-style keys (ROM-123, any case) and GitHub issue numbers (#123). Give each repo the URL template its tracker uses for the former; {key} is substituted, * is the fallback.

{
  "tickets": {
    "twilight": "https://shipyard.podium.com/t/{key}",
    "*": "https://linear.app/acme/issue/{key}"
  }
}

A #123 always links to the repo's own GitHub issues; a tracker key with no template shows nothing rather than guess. The resolved ticket ({key, url} or null) rides every worktree row: the SSE snapshot, the boot cache, and the agent snapshot, wts, whoami and sessions tools.

For a status dot and a click-through card, give the repo a ticketCmds entry: a command that takes the key as $1 and prints {"title", "status", "category", "assignee"} as JSON, exiting non-zero when it can't. It runs on the server with whatever auth your tracker's CLI or API token already has, so Forest never touches browser cookies or stores a token. The result rides the row as ticket.info.

To move a ticket from its card, also print "actions": ["done", "cancelled"]: each becomes a "Mark done" button, which runs the same command with the status as $2 and the worktree's PR URL (or "") as $3, then re-reads the ticket. Forest only passes back a status the command itself offered.

"Close ROM-123 on merge" in an open PR's card (or the row's menu) moves the ticket to its first action that means done (done, completed, closed) once Forest sees the PR merge, then turns itself off. A ticket already done or canceled is left alone. A failure shows in the card until you toggle it again. The set of worktrees lives in ~/.forest/autoclose.json.

{ "ticketCmds": { "*": "~/.forest/jira-ticket.sh" } }

Recipes for GitHub, Jira, Linear and MCP-only trackers, and the full contract, are in the ticket-command skill; ask your coding agent to write one for your tracker.

Keyboard shortcuts

Every command lives in COMMANDS in src/App.svelte with an id, a section, and default keys, and shows up in the palette and the shortcuts overlay (? or ⌘/, also linked from settings). Click a shortcut there and press new keys to rebind it (⎋ cancels, ⌫ restores the default), or set it in settings.json by id. Keys are the physical key (KeyboardEvent.code without Key/Digit, lowercased) joined with ctrl, alt, shift, cmd; a comma separates alternatives. A rebound key that another command also uses goes to the rebound one.

{ "keys": { "palette": "cmd+p", "zoom-in": "cmd+equal, shift+cmd+equal" } }

Themes

Ships a default dark theme and imports any VS Code color theme — either a JSON file you pick, or one VS Code already has installed (it scans VS Code, Insiders, VSCodium, and Cursor extension dirs). Imported themes land in ~/.forest/themes/. Contrast is derived rather than trusted, so a theme whose accent vanishes against its own background gets a readable fallback instead.

Development

deno task serve   # server on :38471, restarts on .ts changes
npm run dev       # in a second terminal: http://forest-app.localhost:38472 with HMR, proxies /api

deno task serve alone serves the last dist/ build; it warns if there isn't one.

deno task check   # fmt + lint + typecheck
deno task test    # unit tests, no network or fixtures
deno task setup   # wire .githooks (check + test on commit and push)

Parsing is deliberately split out of main.ts into parse.ts, src/theme.js, and src/filter.js — that's the part with edge cases worth testing, and it's testable without spawning git. The rest of the server is split into per-system modules (exec, repo, prs, ports, store, sse, watcher, files, themes, log, actions, tools, routes, stats, settings, agents, sessions, types), each with its own <module>_test.ts.

Desktop app

deno task desktop   # builds Forest.app via `deno desktop`

Same server, wrapped in a native window with a transparent titlebar. Cmd +/-/0 zoom only in that build.

Opened from Finder or the Dock, an app gets launchd's bare PATH rather than your shell's, so the desktop build reads PATH from your login shell ($SHELL -il) at startup; gh, launchers, and repo git hooks then find the same tools a terminal would.

deno desktop moves the first server onto a random port that only the window uses, so the app starts a second one on port as well: the browser UI, the agent API and /mcp answer at the usual address while the app is open. If a terminal Forest already has that port, the window still works and those go to the terminal one.

About

A dashboard for git worktrees across every repo in one directory — dirty state, ahead/behind, open PRs, listening dev servers, and a diff viewer with per-hunk staging.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages