worktree-manager

CLI para gerenciar git worktrees por produto: várias tasks em paralelo, com config YAML reutilizável, cópia de arquivos/dependências e workspace Cursor/VS Code gerado automaticamente.

Binário: wt · MCP: wt-mcp · Python 3.11+

---

Índice

• Para quem é
• Como funciona
• Instalação
• Início rápido
• Fluxos de trabalho
• Comandos
• Configuração
• Estado
• MCP para agentes
• Vários produtos
• Documentação
• Desenvolvimento

---

Para quem é

Útil quando você:

• Mantém mais de um repositório por produto (ex.: API + web, backend + mobile)
• Cria uma pasta por task/ticket com worktrees git isoladas
• Quer reaproveitar arquivos locais (.env, launch.json, node_modules, etc.)
• Abre tudo num .code-workspace com pastas extras (docs, utilitários, specs)

Não é um wrapper genérico de git worktree para um único repo solto — o foco é o workspace de produto com N projetos.

---

Como funciona

Pasta do produto/
├── api/                           ← repositório git
├── web/                           ← repositório git
├── docs/                          ← pasta extra no workspace
└── .worktree-manager/              ← pasta do manager
    ├── config.yml                 ← config (versionável)
    ├── state.yml                  ← estado local (não versionar)
    └── worktrees/
        └── TASK-123/
            ├── api/               ← worktree
            ├── web/               ← worktree
            └── TASK-123.code-workspace

Dois caminhos para criar tasks:

1. Em etapas — create (pasta + workspace + estado) e depois add projeto a projeto
2. Preset — create --preset … encadeia create + vários adds

A branch de trabalho default é o nome da task (--branch sobrescreve; no preset, --branch proj=b por projeto).
A base de origem é por projeto (default_base no YAML, com override via --base).

Execute os comandos na pasta base do produto (pai de .worktree-manager/) ou dentro de .worktree-manager/.
Outro produto = outra pasta = outro init.

---

Instalação

Desenvolvimento (recomendado hoje)

git clone <url-deste-repo> worktree-manager
cd worktree-manager

uv venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

wt --version

Alternativa com pip:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Deixe o venv ativo (ou exponha wt no PATH) para usar em qualquer pasta de produto.

---

Início rápido

1. Entre na pasta do produto

cd ~/projetos/meu-produto

Estrutura mínima esperada: repositórios git lado a lado (ex.: api/, web/).

2. Inicialize a config

wt init

O assistente pergunta:

1. Nome do produto
2. Loop de projetos: path → nome (default: basename) → default base

Cria .worktree-manager/config.yml (worktrees em .worktree-manager/worktrees/).
Depois edite copy, workspace_folders e presets, ou use wt projects add.

3. Complete o YAML (exemplo)

name: meu-produto
root: .
worktrees_dir: worktrees
workspace_file: "{task}.code-workspace"

workspace_folders:
  - path: docs

projects:
  api:
    path: api
    default_base: main
    copy:
      - from: .env.local
        to: .env.local
  web:
    path: web
    default_base: main
    copy:
      - from: node_modules
        to: node_modules
        strategy: rsync

presets:
  backend: [api]
  frontend: [web]
  fullstack: [api, web]

Veja o schema completo em docs/configuracao.md e exemplos em docs/exemplos/.

4. Crie uma task

Rápido (preset):

wt create TASK-123 --preset fullstack --open
# ou com branches explícitas:
wt create TASK-123 --preset fullstack --branch feature/TASK-123 --open

Em etapas:

wt create TASK-123
wt add TASK-123 api
wt add TASK-123 web --base develop
wt open TASK-123

5. Gerencie

wt list
wt status TASK-123
wt sync TASK-123
wt doctor
wt doctor --fix
wt prune
wt remove TASK-123 --force

---

Fluxos de trabalho

Só um projeto da stack

wt create TASK-10 --preset backend

Começar parcial e evoluir

wt create TASK-11
wt add TASK-11 api --branch feature/TASK-11
# ... trabalhar só na API ...
wt add TASK-11 web --branch feature/TASK-11

Branches e bases diferentes por projeto no mesmo preset

wt create TASK-12 \
  --preset fullstack \
  --branch api=feature/TASK-12-api \
  --branch web=feature/TASK-12-ui \
  --base api=main \
  --base web=develop

Simular antes de executar

wt create TASK-13 --preset fullstack --dry-run
wt add TASK-13 api --dry-run
wt remove TASK-13 --force --dry-run
wt sync TASK-13 --dry-run

Remover um projeto sem apagar a task

wt remove TASK-12 web --force

Remover tudo (e opcionalmente a branch local)

wt remove TASK-12 --force --delete-branch

---

Comandos

Comando	Descrição
wt init	Cria .worktree-manager/config.yml
wt create <task>	Cria task vazia (pasta + workspace + estado)
wt create <task> --preset <nome>	Create + adds do preset
wt add <task> <project> [--branch <b>] [--base <b>]	Adiciona projeto à task (branch default = task)
wt remove <task> [project] --force	Remove projeto da task ou a task inteira
wt list	Lista tasks do estado
wt projects list	Lista projetos do config.yml
wt projects add <path> [--name] [--base]	Adiciona projeto à config (nome default = basename)
wt projects remove <nome> --force	Remove projeto da config
wt status <task>	git status dos projetos da task
wt sync <task> [project]	Fetch + rebase/merge na base registrada
wt open <task>	Abre o .code-workspace (Cursor/VS Code)
wt doctor [--fix]	Diagnóstico; --fix tenta corrigir
wt prune	Limpa órfãos e ghosts
wt help [comando]	Ajuda detalhada
wt --help / wt --version	Ajuda curta e versão

Opções úteis:

Opção	Onde	Efeito
--branch	add, create --preset	Branch de trabalho (default: nome da task)
--branch proj=b	create --preset	Branch por projeto (repetível)
--base	add	Base de origem (senão usa default_base)
--base proj=branch	create --preset	Override de base por projeto
--strategy	sync	rebase (default) ou merge
--open	create	Abre o workspace ao terminar
--delete-branch	remove	Apaga a branch local criada
--dry-run	create, add, remove, sync, doctor --fix, prune	Mostra o plano sem alterar nada
--force	remove, sync	Confirma remoção / permite dirty no sync

Referência detalhada: docs/comandos.md.

---

Configuração

Arquivo: .worktree-manager/config.yml.

Campo	Obrigatório	Default	Descrição
name	sim	—	Nome do produto
root	não	.	Raiz relativa ao produto (pai de .worktree-manager/)
worktrees_dir	não	worktrees	Pasta das tasks (relativa a .worktree-manager/)
workspace_file	não	{task}.code-workspace	Nome do workspace gerado
workspace_folders	não	[]	Pastas extras no workspace
projects.<id>.path	sim	—	Path do repositório (relativo à raiz do produto)
projects.<id>.default_base	sim	—	Branch de origem padrão
projects.<id>.copy	não	[]	Arquivos/pastas a copiar no add
projects.<id>.copy[].strategy	não	rsync	rsync | copy | skip
presets	não	{}	Nome → lista de ids de projeto

Não existem allowed_bases nem pattern automático de branch.

Guia completo do schema, init e estado: docs/configuracao.md.

---

Estado

Arquivo local: .worktree-manager/state.yml.

	Config	Estado
Responde	O que pode ser feito	O que já existe
Versionar?	Sim (config.yml é útil no time)	Não
Quem escreve	init + edição humana	Só o CLI

Sugestão de .gitignore no produto:

.worktree-manager/state.yml

O wt doctor compara estado, pastas em disco e git worktree list (órfãos, drift de branch, worktrees fantasma, etc.).
wt doctor --fix e wt prune corrigem o que for seguro; wt sync atualiza as branches da task com a base.

---

MCP para agentes

O servidor wt-mcp expõe as mesmas operações da CLI via Model Context Protocol (stdio), para agentes Cursor (e outros clientes MCP) criarem/listarem/sincronizarem tasks sem parsear stdout.

Pré-requisito: pacote instalado (uv tool install --editable . ou uv pip install -e .) e wt-mcp no PATH (which wt-mcp).

Adicionar no Cursor

1. Abra Cursor Settings → MCP (ou edite o JSON de MCP).
2. Inclua o servidor abaixo.
3. Salve e confirme que worktree-manager aparece como conectado (tools disponíveis no chat/agente).

Global (~/.cursor/mcp.json):

{
  "mcpServers": {
    "worktree-manager": {
      "command": "wt-mcp",
      "args": []
    }
  }
}

Só neste repo (.cursor/mcp.json na raiz do projeto):

{
  "mcpServers": {
    "worktree-manager": {
      "command": "wt-mcp",
      "args": []
    }
  }
}

Se wt-mcp não estiver no PATH, use o caminho absoluto do venv:

{
  "mcpServers": {
    "worktree-manager": {
      "command": "/caminho/para/worktree-manager/.venv/bin/wt-mcp",
      "args": []
    }
  }
}

Uso pelo agente

• Passe product_root (path absoluto da pasta do produto) quando o cwd do agente não for o produto.
• Respostas: { "ok": true, "data": … } ou { "ok": false, "error": { "kind", "message" } }.
• Ações destrutivas (remove, prune, doctor com fix) exigem confirm=true (ou dry_run=true para simular).

Tool	Equivale a
resolve_product / list_tasks / list_projects	inventário
create_task / create_with_preset / add_project	wt create / --preset / wt add
remove	wt remove … --force
status / sync	wt status / wt sync
doctor / prune	wt doctor [--fix] / wt prune
workspace_path / open_workspace	path do workspace / wt open

Skill opcional (orquestra MCP ou CLI): .cursor/skills/worktree-manager/.
Detalhes e contrato de erro: docs/mcp.md.

---

Vários produtos

Cada produto tem sua própria pasta .worktree-manager/:

ProdutoA/
├── api/
└── .worktree-manager/
    ├── config.yml
    └── worktrees/

ProdutoB/
├── backend/
├── mobile/
└── .worktree-manager/
    ├── config.yml
    └── worktrees/

cd ~/projetos/ProdutoA && wt init
cd ~/projetos/ProdutoB && wt init

---

Documentação

Documento	Conteúdo
README.md	Porta de entrada (este arquivo)
docs/configuracao.md	Schema YAML, init, estado
docs/comandos.md	Referência detalhada dos comandos
docs/mcp.md	Servidor MCP (wt-mcp) para agentes
docs/exemplos/	YAMLs de exemplo (genérico + casos)
docs/migracao-clinic.md	Caso: migrar script legado Clinic → wt
docs/plano-desenvolvimento.md	Histórico de fases / backlog interno

Exemplos prontos para copiar:

# stack API + web (genérico)
mkdir -p /caminho/do/produto/worktree-manager
cp docs/exemplos/api-web.yml /caminho/do/produto/.worktree-manager/config.yml

# caso Clinic (referência)
mkdir -p /caminho/do/Clinic/worktree-manager
cp docs/exemplos/clinic.yml /caminho/do/Clinic/.worktree-manager/config.yml

Skill opcional do Cursor (orquestra MCP/wt, sem reimplementar lógica):
.cursor/skills/worktree-manager/

---

Desenvolvimento

source .venv/bin/activate
uv pip install -e ".[dev]"
pytest
wt --help
wt-mcp   # sobe o servidor MCP em stdio (usado pelo Cursor)

Layout do pacote:

src/worktree_manager/
├── cli/           # comandos Typer
├── config/        # load/validate/write YAML
├── state/         # estado local
├── git/           # operações git
├── workspace/     # geração .code-workspace
├── mcp/           # servidor MCP (wt-mcp)
├── copyops.py     # cópias declarativas
└── services.py    # create/add/remove/sync/doctor/prune

Plano e backlog: docs/plano-desenvolvimento.md.

---

Licença

MIT (ver pyproject.toml).