Projetos e Git

Um projeto (workspace) conecta conversas a um repositório Git na sua máquina. O Git dá a cada tarefa um conjunto visível de mudanças e, quando você quiser, uma worktree isolada. Para uma pergunta rápida ou um trabalho que não precisa de repositório, um chat avulso basta.

Chats e projetos

A barra lateral tem as abas Chats, Workspaces e Bots.

• Chats → Novo chat inicia um chat avulso, sem projeto. Ele guarda os arquivos de trabalho numa pasta privada no perfil do app, que não é um sandbox do sistema operacional. Começa no último modo que você escolheu num chat avulso (Pergunta na primeira vez), com Solicitar aprovação, e não herda instruções, memória nem permissões salvas de nenhum projeto. Maestro, review de Git, operações de branch e memória de projeto exigem um projeto. Arquivar mantém o chat e seus arquivos; excluir os remove.
• Workspaces lista seus projetos e as conversas deles. Remover um workspace da lista não apaga o repositório no disco.

Adicionar um projeto

Em Workspaces, escolha Adicionar workspace para abrir Adicionar projeto:

• Abrir existente: escolha a pasta de um repositório. Desde a 0.24.0, uma pasta sem histórico Git utilizável pode ser inicializada na main (Inicializar Git nesta pasta), fazendo o commit dos arquivos atuais como Initial commit para que conversas em worktree comecem com os seus arquivos em vez de uma pasta vazia. Arquivos ignorados pelo .gitignore ou pelas exclusões globais do Git, pastas de dependências e cache (node_modules, .venv, venv, __pycache__), .DS_Store e Thumbs.db, prováveis segredos (como .env e arquivos de chave), arquivos de 50 MB ou mais e pastas com repositório Git próprio ficam fora do commit, intactos na sua pasta.
• Criar novo: uma pasta nova dentro de uma Pasta pai, com Git, um README e um commit inicial.
• Clonar repositório Git: uma URL HTTPS, SSH ou file, ou um caminho local. A autenticação usa seu credential helper do Git ou seu agente SSH; URLs com credenciais embutidas são recusadas. Nada é enviado por push automaticamente.

Antes de começar, confirme que você entende as mudanças já existentes na árvore de trabalho, que as dependências de build e teste estão disponíveis e que segredos e arquivos gerados estão cobertos pelas regras de ignore. Os repositórios continuam nos caminhos de sempre. Use Branch padrão… no menu do workspace para definir a base das novas worktrees.

Criar ou clonar um projeto a partir de um chat

Desde a 0.15.0, o projeto de que você está falando não precisa existir ainda. Primeiro escolha uma Pasta de projetos em Configurações → Execução; ela também é a pasta pai padrão em Adicionar projeto. Depois peça, por exemplo, "Clona o acme/api do GitHub e começa a implementar o endpoint de exportação" ou "Cria um projeto novo chamado Atlas com repositório no GitHub e começa o MVP."

O agente primeiro procura um workspace correspondente. Se não houver, ele pode encontrar o repositório com o GitHub CLI (gh) em que você está logado, cloná-lo ou criar um projeto vazio com README e commit inicial. O projeto é registrado como workspace, e o agente pode iniciar uma conversa nele. Um card Novo projeto mostra a origem, a pasta, o progresso do clone e Mostrar na barra lateral.

• Sem pasta de projetos nada é criado, e o card oferece Definir pasta de projetos (navegando pelas pastas deste computador, ou pelas pastas de um computador pareado ou ambiente de workspaces do servidor).
• URLs Git são clonadas com suas próprias credenciais do Git; o formato dono/nome do GitHub usa o protocolo configurado no gh.
• Um repositório no GitHub só é criado quando você pede. Ele é privado, a menos que você o queira público, e um público só é criado depois que você confirma no chat. Um repositório existente com o mesmo nome nunca é reutilizado nem sobrescrito.
• Projetos só são criados em turnos que você inicia, nunca por subagents, bots, automações ou porque um arquivo, card ou página web mandou. Uma mensagem pode criar até 10. Repetir o pedido informa o projeto já existente em vez de clonar de novo.

Escolher onde a conversa trabalha

Em Nova conversa, escolha a branch (Nova branch a partir de uma base em Criar a partir de, ou Branch existente; Atualizar branches traz branches criadas no remoto) e um Modo de trabalho:

• Worktree: uma pasta isolada fora do repositório, nos dados do app, com branch própria. Não mexe no seu checkout principal. Escolha para trabalho paralelo ou automatizado, ou para tudo que você quer revisar antes.
• Local: usa a própria pasta do repositório, compartilhada com seu editor. Se a branch precisar mudar, o Maestrly mostra uma prévia antes e preserva suas mudanças locais. Escolha para trabalho supervisionado.

Migrar para branch isolada… move uma conversa local e o trabalho atual dela para uma nova branch e worktree, depois de uma prévia. Excluir uma conversa também apaga a worktree e a branch que ela criou, então entregue antes o que quiser manter.

Mandar trabalho de um chat para um projeto

Desde a 0.14.0, um chat avulso pode enviar um plano de desenvolvimento para um workspace registrado quando você pede explicitamente, como "Envia este plano para desenvolvimento no workspace Exemplo, numa branch nova feat/exemplo a partir da main." O agente encontra o workspace e pergunta quando o nome é ambíguo. Um workspace de destino sempre ganha uma worktree nova. A branch parte da branch padrão do workspace, a menos que você indique uma base, e só referências disponíveis localmente são usadas; nada é buscado no remoto. Modelo, esforço e Fast são mantidos, a menos que você diga outra coisa. Tentar de novo reaproveita a mesma conversa de destino, e um chat no modo Pergunta continua somente leitura. Chats de projeto também podem fazer isso; veja Maestro, agentes e skills para iniciar várias conversas de uma vez.

Trabalhar em paralelo

• Dê a cada conversa automatizada a própria worktree. Evite duas conversas automatizadas no mesmo checkout.
• Nova conversa a partir desta cria uma conversa irmã que compartilha a mesma worktree, o índice Git e as notas. Divida o trabalho para evitar conflitos.
• Para trabalho entre repositórios, marque dois ou mais repositórios em Nova conversa. A Branch (criada em todos os repos) é criada em cada um, com uma worktree por repositório. Revise cada diff separadamente.
• Worktrees isolam arquivos, mas bancos de dados, portas, credenciais e ambientes de nuvem ainda podem entrar em conflito.
• Abrir chat em nova janela deixa uma conversa aberta ao lado de outras, inclusive em outro monitor, enquanto o trabalho dela continua.

Projetos no seu servidor de bots

Um bot do seu servidor de bots pode iniciar conversas nos projetos que você liberar para ele, e você também pode rodar workspaces inteiros no próprio servidor (ambos Experimental). Veja Bots e Workspaces remotos.

Revisar o resultado

A aba Review da gaveta mostra o Diff (branch local contra a base, ou o pull request), além de PR, Checks e Comentários quando a branch tem um pull request no GitHub. Os dados de pull request exigem o GitHub CLI logado com gh auth login. Antes de entregar:

1. inspecione arquivos alterados e não rastreados;
2. compare o diff com o escopo solicitado;
3. rode testes focados, formatação, checagem de tipos ou build;
4. procure segredos, arquivos gerados por acidente e edições sem relação;
5. faça commit com uma mensagem que descreva o resultado verificado.

Não faça merge ou deploy só porque o agente disse que terminou. Trate o resumo dele como um resultado a verificar. Resolver conflitos com IA faz o merge da base numa branch de pull request com conflito, commita e publica a branch; use só quando quiser esse push.

Limpar com segurança

Faça merge, cherry-pick ou entregue a branch revisada pelo seu processo Git normal. Exclua uma conversa, o que remove a worktree e a branch dela, só depois que as mudanças desejadas estiverem commitadas e preservadas em outro lugar. Se abandonar uma tarefa, inspecione as mudanças não commitadas antes de descartar qualquer coisa.

Desde a 0.20.0, arquivar ou excluir uma conversa encerra os processos que os terminais e os comandos bash dela deixaram rodando, como um servidor de desenvolvimento em segundo plano, e excluir também apaga os arquivos temporários que as ferramentas dela gravaram. Só são encerrados os processos que o Maestrly consegue ligar àquela conversa; programas que se desligam de propósito, como setsid, docker compose up -d, tmux e screen, continuam rodando.

A seguir: Uso e custos.