README
¶
A git worktree manager that gives each branch its own ports, Compose project, database and URL, so you and your coding agents can run several branches side by side.
Docs · Install · Guide · Changelog
One command for a worktree, one for its stack.
Highlights
- A worktree per branch, ready to code:
.envfiles copied and your hooks run, from any base. - Its own stack: shifted ports, its own Compose project and database, a named URL.
- Stacked branches stay in order: a whole chain rebased onto its parents in one command.
- Gone once merged: never with uncommitted, unpushed or open work.
- Configured once, run by everyone: one person writes
run.toml, the team imports it. - Built for agents: a skill,
--output json,--yes, a live event stream.
Install
brew install LucasPcq/tap/wtm
echo 'eval "$(wtm shell-init)"' >> ~/.zshrc
macOS, Linux and WSL2. Other ways to install, and a specific version: Installation. Then wtm init once in your repository, or follow Getting started.
The life of a branch
Created, ready to code
A worktree from any base, its .env files copied and your on_create hooks run.
wtm create feat/login
Running, each with its own stack
Its own ports, Compose project, database and URL. An agent starts the whole app in its worktree and checks its own work while yours keeps running. One person writes the run.toml that describes the stack, the team imports it.
wtm run up
Kept in order
Every worktree knows the branch it came from. When main moves, the whole chain is rebased, parents first.
wtm sync --all
Gone once merged
Every worktree whose pull request merged, removed with its jobs and its data. Uncommitted, unpushed or open work is refused until --force.
wtm prune
Built for agents
Every change takes --yes, every data command --output json, and wtm events streams what every shell and agent does. One command teaches your agent the rest:
wtm agents install
Integrations · The event stream · herdr-wtm
Learn more
Getting started · Guide · Commands · Compared to · Changelog · Contributing
MIT licensed.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
config
Package config loads and validates wtm configuration from project and user-level TOML files.
|
Package config loads and validates wtm configuration from project and user-level TOML files. |
|
domain
Package domain defines shared types, constants, and errors for the wtm CLI.
|
Package domain defines shared types, constants, and errors for the wtm CLI. |
|
domain/remember
Package remember holds the spellings of the answers kept under [wizard.remembered].
|
Package remember holds the spellings of the answers kept under [wizard.remembered]. |
|
domain/statefile
Package statefile names the schema version of each file wtm keeps and the refusal of a newer one.
|
Package statefile names the schema version of each file wtm keeps and the refusal of a newer one. |
|
flow
Package flow carries the run of each wtm command, independently of the surface that drives it.
|
Package flow carries the run of each wtm command, independently of the surface that drives it. |
|
flow/checkout
Package checkout runs the `wtm checkout` flow: a worktree from a pull request.
|
Package checkout runs the `wtm checkout` flow: a worktree from a pull request. |
|
flow/clean
Package clean runs the `wtm clean` flow.
|
Package clean runs the `wtm clean` flow. |
|
flow/create
Package create runs the `wtm create` flow.
|
Package create runs the `wtm create` flow. |
|
flow/decide
Package decide holds the branch and env decisions the create-like flows share.
|
Package decide holds the branch and env decisions the create-like flows share. |
|
flow/env
Package env runs the `wtm env` flow.
|
Package env runs the `wtm env` flow. |
|
flow/envports
Package envports settles the host ports a freshly provisioned .env holds onto the ones the worktree it belongs to actually binds.
|
Package envports settles the host ports a freshly provisioned .env holds onto the ones the worktree it belongs to actually binds. |
|
flow/exec
Package exec runs the `wtm exec` flow.
|
Package exec runs the `wtm exec` flow. |
|
flow/extract
Package extract runs the `wtm extract` flow.
|
Package extract runs the `wtm extract` flow. |
|
flow/fastforward
Package fastforward runs the `wtm fast-forward` flow.
|
Package fastforward runs the `wtm fast-forward` flow. |
|
flow/ordinal
Package ordinal allocates a worktree's number from the flow that needs it, so the change is published like every other change to its identity.
|
Package ordinal allocates a worktree's number from the flow that needs it, so the change is published like every other change to its identity. |
|
flow/orphans
Package orphans asks what becomes of the children a removal leaves behind, for clean and prune alike.
|
Package orphans asks what becomes of the children a removal leaves behind, for clean and prune alike. |
|
flow/prune
Package prune runs the `wtm prune` flow.
|
Package prune runs the `wtm prune` flow. |
|
flow/publish
Package publish turns a change a flow just made into the event reporting it.
|
Package publish turns a change a flow just made into the event reporting it. |
|
flow/relocate
Package relocate runs the `wtm relocate` flow.
|
Package relocate runs the `wtm relocate` flow. |
|
flow/reparent
Package reparent runs the `wtm reparent` flow.
|
Package reparent runs the `wtm reparent` flow. |
|
flow/run/addressing
Package addressing is `wtm run addressing` — switching the mode and settling the .env files on it — and the warning the run flows put under the URLs they hand out: the worktrees whose .env still answers on ports while their jobs are published by name.
|
Package addressing is `wtm run addressing` — switching the mode and settling the .env files on it — and the warning the run flows put under the URLs they hand out: the worktrees whose .env still answers on ports while their jobs are published by name. |
|
flow/run/concurrency
Package concurrency asks what a start does about the jobs other worktrees are running, shared by `run up` and `run start`.
|
Package concurrency asks what a start does about the jobs other worktrees are running, shared by `run up` and `run start`. |
|
flow/run/down
Package down runs the `wtm run down` flow.
|
Package down runs the `wtm run down` flow. |
|
flow/run/foreigndata
Package foreigndata stops a run before a job changes data the worktree does not own, shared by `run up` and `run start`.
|
Package foreigndata stops a run before a job changes data the worktree does not own, shared by `run up` and `run start`. |
|
flow/run/initrun
Package initrun is `wtm run init`: detect the services, ask about them, then write run.toml, the compose files and the .env files the answers call for.
|
Package initrun is `wtm run init`: detect the services, ask about them, then write run.toml, the compose files and the .env files the answers call for. |
|
flow/run/job
Package job runs the `wtm run job add|edit|rm|list` flows — CRUD on the job declarations in run.toml.
|
Package job runs the `wtm run job add|edit|rm|list` flows — CRUD on the job declarations in run.toml. |
|
flow/run/list
Package list runs the `wtm run list` flow: the listing that acts.
|
Package list runs the `wtm run list` flow: the listing that acts. |
|
flow/run/logs
Package logs runs the `wtm run logs` flow.
|
Package logs runs the `wtm run logs` flow. |
|
flow/run/open
Package open runs the `wtm run open` flow.
|
Package open runs the `wtm run open` flow. |
|
flow/run/owed
Package owed settles the namespaces a clean could not give back because the shared service holding them was down: the moment to pay is whenever that service is up again, so every run that finds it up settles what it can.
|
Package owed settles the namespaces a clean could not give back because the shared service holding them was down: the moment to pay is whenever that service is up again, so every run that finds it up settles what it can. |
|
flow/run/probes
Package probes offers to silence the port warnings a job repeats at every run, shared by `run up` and `run start`.
|
Package probes offers to silence the port warnings a job repeats at every run, shared by `run up` and `run start`. |
|
flow/run/profile
Package profile runs the `wtm run profile add|edit|rm|list` flows — CRUD on the profile declarations in run.toml, on the same model as the job ones.
|
Package profile runs the `wtm run profile add|edit|rm|list` flows — CRUD on the profile declarations in run.toml, on the same model as the job ones. |
|
flow/run/seam
Package seam binds a run flow to the daemon holding a worktree's jobs: the board a surface lists, the environment those jobs are given, and the start sequence a surface drives.
|
Package seam binds a run flow to the daemon holding a worktree's jobs: the board a surface lists, the environment those jobs are given, and the start sequence a surface drives. |
|
flow/run/start
Package start runs the `wtm run start` flow.
|
Package start runs the `wtm run start` flow. |
|
flow/run/stop
Package stop runs the `wtm run stop` flow.
|
Package stop runs the `wtm run stop` flow. |
|
flow/run/target
Package target holds the questions every run command shares: which worktree it acts on, and what inside it — a job or a profile.
|
Package target holds the questions every run command shares: which worktree it acts on, and what inside it — a job or a profile. |
|
flow/run/up
Package up runs the `wtm run up` flow.
|
Package up runs the `wtm run up` flow. |
|
flow/run/url
Package url runs the `wtm run url` flow.
|
Package url runs the `wtm run url` flow. |
|
flow/run/urls
Package urls is where every address the run module hands out is computed from.
|
Package urls is where every address the run module hands out is computed from. |
|
flow/runlogs
Package runlogs is the seam between a surface showing a worktree's jobs and the daemon holding them: what a job looks like, how its live output is subscribed to, and how a profile's start sequence is reported.
|
Package runlogs is the seam between a surface showing a worktree's jobs and the daemon holding them: what a job looks like, how its live output is subscribed to, and how a profile's start sequence is reported. |
|
flow/status
Package status runs the `wtm status` flow: a worktree's whole state, read without numbering, waking or writing anything.
|
Package status runs the `wtm status` flow: a worktree's whole state, read without numbering, waking or writing anything. |
|
flow/sync
Package sync runs the `wtm sync` flow.
|
Package sync runs the `wtm sync` flow. |
|
flow/teardown
Package teardown is the sequence clean and prune run on the worktrees they remove, one or several.
|
Package teardown is the sequence clean and prune run on the worktrees they remove, one or several. |
|
infra
Package infra runs git for the commands still on flow/ and holds the wtm state that has not moved to its own package yet.
|
Package infra runs git for the commands still on flow/ and holds the wtm state that has not moved to its own package yet. |
|
infra/fs
Package fs is the only writer of the files wtm keeps.
|
Package fs is the only writer of the files wtm keeps. |
|
infra/proc
Package proc starts the processes wtm runs and settles them on an interrupt.
|
Package proc starts the processes wtm runs and settles them on an interrupt. |
|
rules/envcopy
Package envcopy decides where each .env file of a new worktree is copied from.
|
Package envcopy decides where each .env file of a new worktree is copied from. |
|
rules/statefile
Package statefile decides what a state file's schema version allows.
|
Package statefile decides what a state file's schema version allows. |
|
schemas
Package schemas embeds the JSON Schema files used to validate and provide IDE autocomplete for wtm's TOML config files, and the contract of the `wtm events` stream.
|
Package schemas embeds the JSON Schema files used to validate and provide IDE autocomplete for wtm's TOML config files, and the contract of the `wtm events` stream. |
|
service/branch
Package branch orchestrates branch-candidate listing for the pickers: it lists local and origin branches, computes each local branch's divergence from its origin counterpart, and merges them into a single ordered candidate set.
|
Package branch orchestrates branch-candidate listing for the pickers: it lists local and origin branches, computes each local branch's divergence from its origin counterpart, and merges them into a single ordered candidate set. |
|
service/compose
Package compose reads the `ports:` a docker-compose file declares, and rewrites them in place so each worktree binds its own.
|
Package compose reads the `ports:` a docker-compose file declares, and rewrites them in place so each worktree binds its own. |
|
service/detect
Package detect reads what a project already holds — its .env files, compose files, package manager, scripts and agents — to propose `wtm init`'s answers.
|
Package detect reads what a project already holds — its .env files, compose files, package manager, scripts and agents — to propose `wtm init`'s answers. |
|
service/env
Package env decides what the .env files of a worktree hold — their sync with their source, the ports, the keys wtm owns — and has store write it.
|
Package env decides what the .env files of a worktree hold — their sync with their source, the ports, the keys wtm owns — and has store write it. |
|
service/events
Package events is the `wtm events` bus as wtm itself uses it: the publisher every flow reports through, and the watcher behind both consumers.
|
Package events is the `wtm events` bus as wtm itself uses it: the publisher every flow reports through, and the watcher behind both consumers. |
|
service/execsvc
Package execsvc runs one shell line in several worktrees at once.
|
Package execsvc runs one shell line in several worktrees at once. |
|
service/github
Package github reads a branch's pull requests through the gh CLI.
|
Package github reads a branch's pull requests through the gh CLI. |
|
service/hooks
Package hooks runs a worktree's lifecycle hooks.
|
Package hooks runs a worktree's lifecycle hooks. |
|
service/integration
Package integration adapts wtm to the third-party tools a worktree is used with — for now, whatever the desktop uses to open a URL.
|
Package integration adapts wtm to the third-party tools a worktree is used with — for now, whatever the desktop uses to open a URL. |
|
service/memory
Package memory keeps the answers a repository asked the wizard never to ask again.
|
Package memory keeps the answers a repository asked the wizard never to ask again. |
|
service/portprobe
Package portprobe answers one question about a port: is anything listening on it.
|
Package portprobe answers one question about a port: is anything listening on it. |
|
service/process
Package process manages long-running jobs with pseudo-terminals.
|
Package process manages long-running jobs with pseudo-terminals. |
|
service/process/processtest
Package processtest stands a fake run daemon on the socket a flow dials, so a test can decide what is running without starting a single process.
|
Package processtest stands a fake run daemon on the socket a flow dials, so a test can decide what is running without starting a single process. |
|
service/proxy
Package proxy serves the named URLs of running jobs on one loopback port.
|
Package proxy serves the named URLs of running jobs on one loopback port. |
|
service/runconfig
Package runconfig orchestrates load + validate + write on the run.toml config file.
|
Package runconfig orchestrates load + validate + write on the run.toml config file. |
|
service/runjobs
Package runjobs reads the run daemon's index of jobs.
|
Package runjobs reads the run daemon's index of jobs. |
|
service/selfupdate
Package selfupdate resolves how wtm was installed and brings it to the latest published release.
|
Package selfupdate resolves how wtm was installed and brings it to the latest published release. |
|
service/shell
Package shell generates shell integration functions for zsh, bash, and fish.
|
Package shell generates shell integration functions for zsh, bash, and fish. |
|
service/shellcmd
Package shellcmd checks that a command written in a config file is a shell line the shell can actually parse.
|
Package shellcmd checks that a command written in a config file is a shell line the shell can actually parse. |
|
service/worktree
Package worktree implements git worktree operations (create, list, remove, detect parent).
|
Package worktree implements git worktree operations (create, list, remove, detect parent). |
|
store
Package store is the one writer of each state file: a worktree's meta.json, the changes to config.toml and the .env files wtm manages.
|
Package store is the one writer of each state file: a worktree's meta.json, the changes to config.toml and the .env files wtm manages. |
|
styles
Package styles centralizes all Lipgloss style definitions.
|
Package styles centralizes all Lipgloss style definitions. |
|
surface/cli
Package cli is the command line: the Cobra tree, its run and its exit code.
|
Package cli is the command line: the Cobra tree, its run and its exit code. |
|
surface/cli/checkout
Package checkout implements the wtm checkout command: create a worktree from an existing GitHub pull request.
|
Package checkout implements the wtm checkout command: create a worktree from an existing GitHub pull request. |
|
surface/cli/configcmd
Package configcmd exposes the `wtm config` command group: show and edit.
|
Package configcmd exposes the `wtm config` command group: show and edit. |
|
surface/cli/events
Package events wires `wtm events`, the stream an editor, an agent or a terminal plugin reads instead of guessing what wtm did.
|
Package events wires `wtm events`, the stream an editor, an agent or a terminal plugin reads instead of guessing what wtm did. |
|
surface/cli/render
Package output formats and prints results.
|
Package output formats and prints results. |
|
surface/cli/run/daemoncmd
Package daemoncmd implements `wtm run daemon status|stop|restart` — the way in and out of the process that actually runs the jobs.
|
Package daemoncmd implements `wtm run daemon status|stop|restart` — the way in and out of the process that actually runs the jobs. |
|
surface/cli/run/jobcmd
Package jobcmd implements `wtm run job add|rm|edit|list` — CRUD on jobs in run.toml.
|
Package jobcmd implements `wtm run job add|rm|edit|list` — CRUD on jobs in run.toml. |
|
surface/cli/run/profilecmd
Package profilecmd implements `wtm run profile add|rm|edit|list` — CRUD on profiles in run.toml.
|
Package profilecmd implements `wtm run profile add|rm|edit|list` — CRUD on profiles in run.toml. |
|
surface/cli/run/proxycmd
Package proxycmd implements `wtm run proxy status|install|uninstall` — the machine-wide redirection that lets named URLs drop their port.
|
Package proxycmd implements `wtm run proxy status|install|uninstall` — the machine-wide redirection that lets named URLs drop their port. |
|
surface/cli/run/runctx
Package runctx is what every command of the `run` module opens on: where it was launched, the repository's config, its run.toml, the module's opt-in guard, and the prompt-capability gate.
|
Package runctx is what every command of the `run` module opens on: where it was launched, the repository's config, its run.toml, the module's opt-in guard, and the prompt-capability gate. |
|
surface/cli/ui
Package ui implements `wtm ui`: the full-screen worktree dashboard.
|
Package ui implements `wtm ui`: the full-screen worktree dashboard. |
|
surface/cli/versioncmd
Package versioncmd wires `wtm version`, the probe a host runs before relying on any of wtm's machine contracts.
|
Package versioncmd wires `wtm version`, the probe a host runs before relying on any of wtm's machine contracts. |
|
surface/tui/branchrefresh
Package branchrefresh wires the "r" refresh key into branch pickers: it re-fetches origin, recomputes the divergence-tagged candidates, and rebuilds the branch step in place when it is the one on screen.
|
Package branchrefresh wires the "r" refresh key into branch pickers: it re-fetches origin, recomputes the divergence-tagged candidates, and rebuilds the branch step in place when it is the one on screen. |
|
surface/tui/components
Package components provides reusable Bubbletea UI primitives.
|
Package components provides reusable Bubbletea UI primitives. |
|
surface/tui/dashboard
Package dashboard renders `wtm ui`: a full-screen view of the repository's worktrees, and the surface the create and clean flows are run from.
|
Package dashboard renders `wtm ui`: a full-screen view of the repository's worktrees, and the surface the create and clean flows are run from. |
|
surface/tui/flowui
Package flowui runs a flow.Session as a wtm wizard.
|
Package flowui runs a flow.Session as a wtm wizard. |
|
surface/tui/runview
Package runview renders a job's raw PTY output through a terminal emulator.
|
Package runview renders a job's raw PTY output through a terminal emulator. |
|
surface/tui/worktreepicker
Package worktreepicker renders a rich worktree selector with the same styling (breadcrumb, badges, spacing) as the interactive `list` wizard.
|
Package worktreepicker renders a rich worktree selector with the same styling (breadcrumb, badges, spacing) as the interactive `list` wizard. |
|
surface/tui/worktreerefresh
Package worktreerefresh wires the "r" refresh key into interactive worktree lists: it re-fetches origin, recomputes the worktree statuses (origin divergence, dirty, base-ahead), and rebuilds the worktree step in place when it is the one on screen.
|
Package worktreerefresh wires the "r" refresh key into interactive worktree lists: it re-fetches origin, recomputes the worktree statuses (origin divergence, dirty, base-ahead), and rebuilds the worktree step in place when it is the one on screen. |
|
testutil/flowtest
Package flowtest provides test doubles for the flow surfaces: a Prompter that answers from a script and a Presenter that records what was shown.
|
Package flowtest provides test doubles for the flow surfaces: a Prompter that answers from a script and a Presenter that records what was shown. |
|
testutil/ghtest
Package ghtest drives the GitHub CLI a test sees.
|
Package ghtest drives the GitHub CLI a test sees. |
|
testutil/gittest
Package gittest gives tests a real git repository.
|
Package gittest gives tests a real git repository. |
|
testutil/globaldir
Package globaldir points a test's global wtm directory at a temporary one.
|
Package globaldir points a test's global wtm directory at a temporary one. |
|
testutil/runlogstest
Package runlogstest provides doubles for the run log seam: a Service that answers from a script instead of a daemon, a Stream fed by hand, and a Sink that records what a run emitted.
|
Package runlogstest provides doubles for the run log seam: a Service that answers from a script instead of a daemon, a Stream fed by hand, and a Sink that records what a run emitted. |
|
testutil/schematest
Package schematest compiles a bundled JSON Schema for a test to validate against.
|
Package schematest compiles a bundled JSON Schema for a test to validate against. |
|
testutil/socktest
Package socktest hands tests a Unix socket path short enough to bind, and a stand-in for whatever listens on it.
|
Package socktest hands tests a Unix socket path short enough to bind, and a stand-in for whatever listens on it. |
|
tools
|
|
|
archlint
command
Command archlint checks the architecture rules of CLAUDE.md that no general-purpose linter knows about.
|
Command archlint checks the architecture rules of CLAUDE.md that no general-purpose linter knows about. |
|
gendocs
command
Command gendocs regenerates the Markdown command reference under docs/ from the Cobra command tree, so the reference always matches `wtm <cmd> --help`.
|
Command gendocs regenerates the Markdown command reference under docs/ from the Cobra command tree, so the reference always matches `wtm <cmd> --help`. |
Click to show internal directories.
Click to hide internal directories.