Worktree Control

One dev port per project. Shared context for you and your coding agents.

Switch a development server between Git worktrees without changing its port. Queue builds and tests, see which code they checked, and keep the tasks, discussions and decisions that the next session will need.

Worktree Control runs on your machine with a browser dashboard, CLI and MCP server. It supports Node.js and Django servers, verification-only projects such as Godot and Godot Web previews, stores state in SQLite, and needs no hosted account. Optional individual accounts with per-project permissions run on the same machine. It is MIT licensed.

Website · Why I built it · Try it locally · Connect your agent · Project knowledge · Documentation

Screenshots show the current dashboard with fictional demo data. The interface supports English and Polish, dark and light themes, and mobile layouts.

Keep development servers predictable

Your frontend can run feature/checkout on port 3000 while the API stays on main at port 4000. Switching one project leaves the others alone.

• Pin a worktree with a human lock while you use it.
• Let an agent claim a project, start or switch its server, and release the claim when it finishes. Release leaves the server running.
• Inspect the branch, local changes, server state and logs before taking action.
• Check worktree disk usage and remove a stopped, unlocked Next.js worktree's .next cache with confirmation.

Use your existing editor and Git tools to create worktrees. Worktree Control discovers them. Humans and agents must use its controller for ownership rules to apply; it cannot prevent an unrelated terminal from starting another process.

Know what passed

Run a discovered test, lint, typecheck or build preset against a specific worktree. A shared queue limits concurrent checks and allows at most one active run per worktree. Submitting a test does not move or reserve the dev server.

A passing command and a result that applies to your current code are separate things. Tests shows the command outcome, Git observations around the run, current relevance and output. Dirty or changed source stays visible. Local checks use the worktree's files, including uncommitted edits; they are not immutable snapshots.

Keep project context between sessions

Knowledge gives humans and agents the same project records through the dashboard, MCP and CLI. It works without a running dev server or a Git repository.

• Backlog: capture a task, set its priority and status, and link the discussion that led to it.
• Discussions: keep findings, questions and replies together. Turn an agreed next step into a task.
• Memory: retain decisions and notes with sources, revision history and explicit approval.

Follow named links between records, search titles and content, and jump to the reply that matched. Open attached documents in the reader. A task's Next session context collects linked memory and source revisions for a handoff; you can export that context as Markdown or JSON.

Search currently covers record titles and bodies. Attached documents can be read in the dashboard but are not yet included in search.

Hub import, attachments, backup and project transfer are implemented. An existing Hub project still needs a reviewed migration and a clear choice of where future writes belong. See the knowledge delivery plan.

Quick start

Status: pre-1.0. This README describes 0.2.0, dated 2026-11-09; see the changelog. Check the npm version listing or run npm view [email protected] version to confirm registry availability. The local controller is in daily use by its author. Linux x64 is verified; macOS and Windows are unverified. The CLI and data model may change.

Install Node.js 22 or newer and Git, then install and start the controller:

npm install --global [email protected]
worktree-control start --host 127.0.0.1

The first start prints the installation token once. Save it in a password manager; it is not shown again, and worktree-control auth token rotate issues a new one. Open the controller's printed address and sign in with that token. The token is printed only to an interactive terminal; in scripts and CI run worktree-control auth token generate first. To keep the controller running after you close the terminal, run worktree-control service install --host 127.0.0.1 instead of start. It prints the token the same way if none exists yet; see Run it in the background. A global install into the system npm prefix may need elevated rights. The installation guide shows a user-owned prefix and how to install a checksum-verified tarball from CI instead of the registry.

This is the beginning of the README. Read the rest at the original. Read the full README ↗