Crate wt 

wt — a Git worktree and GitHub PR manager (library crate).

All real logic lives here so it is unit-testable and counted by coverage; src/main.rs is a thin entry point. See spec.md for the full behavior specification.

The single entry point is run, which takes the command-line arguments and a Cx (injected I/O, environment, and working directory) and returns the process exit code. Keeping the side-effecting handles in Cx makes the whole dispatch path testable without touching the real terminal.

Embedding wt

That entry point is the application. Embedders skip it and drive the worktree engine directly. The crate is published as kono-wt, but the library target is named wt, so the API is imported as wt::… either way:

kono-wt = { version = "1", default-features = false }

Turning the default features off drops the application surface — argument parsing, the TUI, the PR compose flow — and with it clap, ratatui, crossterm and tokio. What remains is the engine:

• worktree::Workspace — discover a repository, then enumerate, create and remove worktrees and read or write their metadata. Nothing on it prompts, reads stdin, or writes to stdout; outcomes come back as data.
• template — where worktrees live. The layout is repository configuration, so resolve paths through this module; reimplementing the template makes the two products disagree about where worktrees are.
• config::wtconfig — the wt.<branch>.* metadata contract, plus worktree::SCHEMA_VERSION and the version gate to check before mutating.
• worktree::RepoLock — the advisory lock that serializes mutations across every wt and embedder in one repository. Taking it re-validates the metadata schema under the lock, so an acquisition is also the version gate. Call install_signal_handlers once at startup so a signal cannot strand it.

wt owns only the short, structured generation steps it needs for its own branch and PR proposals ([agent.generation]). Running a coding agent on the work itself belongs to the embedder.

See the “Using wt as a library” section of the README for a worked example.

Re-exports

pub use cx::Cx;

pub use cx::Env;

pub use cx::Stream;

pub use error::Error;

pub use error::Result;

Modules

agent

The code-agent boundary (issue #11): detect installed agent CLIs and drive them in their JSON output mode. AgentClient isolates the subprocess work so callers can inject a fake; RealAgent spawns the real binaries. A missing binary yields Error::AgentUnavailable; a non-zero exit yields Error::Subprocess.

config

Configuration loading and merging (spec §11).

copy

Copying Git-ignored local files into newly created worktrees (spec §8).

cx

Runtime context: injected I/O, environment, and working directory.

error

Typed error type for the wt library.

gh

The GitHub boundary (spec §4): all pull-request operations shell out to the gh CLI. GhClient isolates this so tests can inject a fake; RealGh spawns the real binary. A missing or unauthenticated gh yields Error::GhUnavailable with an actionable message (§12).

git

The Git boundary (spec §4): gix for reads, the git CLI for mutations and network operations. Submodules:

hooks

Post-create and pre-remove hooks (spec §8), and the --start command (issue #89). All three run via sh -c (Unix) or cmd /C (Windows) with the worktree as the working directory and the WT_* variables in the environment.

keys

TUI key bindings (spec §10/§11): the action set, the default keymap, and parsing/rendering of key strings such as ctrl+u or f5.

model

Domain model: the worktree row and its JSON schema (spec §7), plus the sort and column enums used by list/status.

naming

The branch-name contract for issue-driven worktrees (issue #96): the conventional TYPE/{number}-SLUG form, its prompt fragment, its validator, and a deterministic fallback.

output

Output rendering: color decisions, paging, table layout, and the human renderers. Submodules are added as the command surface grows; the stdout/stderr discipline itself lives on crate::cx::Cx.

query

Query resolution (spec §7): match a query against a set of worktrees in a defined precedence order, reporting a unique match, ambiguity, or no match.

slug

Branch-slug normalization (spec §3).

template

Worktree-store path-template rendering (spec §6).

time

Time formatting for display (spec §7 “Display conventions”).

tui

The terminal UI (spec §10): a live dashboard and action center.

util

Shared utilities: fuzzy matching, copy-on-write cloning, and editor resolution.

version

Build and version metadata surfaced by wt --version / wt -V.

worktree

The worktree operation layer (issue #95).

Functions

install_signal_handlers

Arms the signal handlers that release the advisory repository lock.

run

Runs wt with the given command-line arguments (excluding argv[0]), writing through the provided Cx, and returns the process exit code.