fwts 0.1.0

Git worktree workflow manager for feature development

fwts

Git worktree workflow manager for feature development. Automates creating worktrees, tmux sessions, docker services, and more.

Features

• Worktree Management - Create and manage git worktrees for parallel feature development
• Focus Switching - Claim shared resources (DB ports, etc.) for one worktree at a time
• Multi-Project Support - Manage multiple repos with named projects in global config
• Tmux Integration - Automatic session creation with editor and side command (e.g., Claude)
• Docker Compose - Start/stop isolated docker services per feature
• Linear Integration - Resolve ticket IDs to branch names
• GitHub Integration - Resolve PR numbers to branches
• Graphite Support - Optional stacking workflow integration
• Interactive TUI - Rich terminal UI for viewing and managing worktrees
• Programmable Columns - Custom hooks for CI status, review status, etc.
• Shell Completions - bash, zsh, and fish support

Installation

From PyPI

pip install fwts
# or with uv
uv tool install fwts

From Homebrew

brew install laudiacay/tap/fwts

Quick Start

1. Initialize global configuration:

fwts init --global
# Edit ~/.config/fwts/config.toml to add your projects

2. Or initialize per-repo configuration:

cd ~/code/myproject
fwts init
# Edit ..fwts.toml to configure

3. Start working on a feature:

# From a Linear ticket
fwts start SUP-123

# From a GitHub PR
fwts start #456

# From a branch name
fwts start feature/my-feature

# Interactive mode - pick from existing worktrees
fwts start

4. View all worktrees:

# Interactive TUI
fwts status

# Simple list
fwts list

5. Focus on a worktree (claim shared resources):

# Focus on a branch
fwts focus feature/my-feature

# Show current focus
fwts focus

# Clear focus
fwts focus --clear

6. Clean up when done:

fwts cleanup feature/my-feature
# Or interactively
fwts cleanup

Configuration

Global Config (Multi-Project)

Create ~/.config/fwts/config.toml for managing multiple projects:

# Default project when not in a project directory
default_project = "supplyco"

[projects.supplyco]
name = "supplyco"
main_repo = "~/code/supplyco"
worktree_base = "~/code/supplyco-worktrees"
base_branch = "dev"
github_repo = "workonsupplyco/supplyco"

[projects.supplyco.focus]
on_focus = ["just docker expose-db"]

[projects.myproject]
name = "myproject"
main_repo = "~/code/myproject"
worktree_base = "~/code/myproject-worktrees"
base_branch = "main"

Per-Repo Config

Create ..fwts.toml in your repo root:

[project]
name = "myproject"
main_repo = "~/code/myproject"
worktree_base = "~/code/myproject-worktrees"
base_branch = "main"
github_repo = "username/myproject"

[linear]
enabled = true
# LINEAR_API_KEY from environment

[graphite]
enabled = false
trunk = "main"

[tmux]
editor = "nvim ."
side_command = "claude"
layout = "vertical"

[lifecycle]
on_start = ["just up"]
on_cleanup = ["just down"]

[focus]
# Commands to run when this worktree gains focus
on_focus = ["just docker expose-db"]
# Commands to run when this worktree loses focus
on_unfocus = []

# Per-branch pattern overrides
[focus.overrides."claudia-*"]
on_focus = ["just docker expose-db", "just connect dev-tunnel"]

[symlinks]
paths = [".env.local"]

[docker]
enabled = true
compose_file = "docker-compose.dev.yml"

# Custom TUI columns
[[tui.columns]]
name = "CI"
hook = "gh run list --branch $BRANCH_NAME --limit 1 --json conclusion -q '.[0].conclusion'"
color_map = { success = "green", failure = "red", pending = "yellow" }

Per-Worktree Config

Create .fwts.local.toml in a worktree to override settings for that specific worktree. This file is gitignored.

Config Hierarchy

Configuration is loaded and merged in this order (later overrides earlier):

1. ~/.config/fwts/config.toml (global)
2. <main_repo>/..fwts.toml (per-repo)
3. <worktree>/.fwts.local.toml (per-worktree)

Commands

Command	Description
fwts start [input]	Start or resume a feature worktree
fwts cleanup [input]	Clean up worktree, tmux, docker
fwts status	Interactive TUI dashboard
fwts list	Simple worktree list
fwts focus [branch]	Switch focus to a worktree
fwts projects	List configured projects
fwts init	Initialize config file
fwts init --global	Initialize global config
fwts completions <shell>	Generate shell completions

Global Options

All commands support:

• --project, -p - Use a specific named project from global config
• --config, -c - Use a specific config file

Aliases

fb is an alias for fwts:

fb start SUP-123
fb status
fb focus my-feature

TUI Keyboard Shortcuts

Key	Action
j / ↓	Move down
k / ↑	Move up
space	Toggle selection
a	Select all
enter	Launch selected
f	Focus selected
d	Cleanup selected
r	Refresh
q	Quit

Focus Switching

Focus allows one worktree to "claim" shared resources like database ports. This is useful when:

• Multiple worktrees share localhost ports (e.g., postgres:5432)
• You need to switch your database GUI between worktrees
• External tools need to connect to the "current" worktree's services

Configure focus commands in your config:

[focus]
on_focus = ["just docker expose-db"]  # Run when gaining focus
on_unfocus = ["echo 'Releasing resources'"]  # Run when losing focus

Only one worktree per project can have focus at a time. The TUI shows focus status with a ◉ indicator.

Shell Completions

# Bash
eval "$(fwts completions bash)"

# Zsh
eval "$(fwts completions zsh)"

# Fish
fwts completions fish > ~/.config/fish/completions/fwts.fish

Environment Variables

Variable	Description
LINEAR_API_KEY	Linear API key for ticket integration

Requirements

• Python 3.10+
• git
• tmux
• gh (GitHub CLI) - optional, for PR integration
• gt (Graphite) - optional, for stacking workflow

License

MIT