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

Related MCP server: batuta-mcp

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

Opções úteis:

Referência detalhada: docs/comandos.md.

Configuração

Arquivo: .worktree-manager/config.yml.

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.

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).

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

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).