Primeiros Passos

Há duas formas de entrar no FlowForge, e você deve escolher a que combina com você.

• Nunca escreveu código? Comece pelo aplicativo desktop e pelo passo a passo de 90 segundos abaixo. Sem configuração, sem jargão, nada para instalar manualmente.
• Já usa o Claude Code? Vá direto para Instale ao lado do Claude Code e execute sua primeira sessão rastreada a partir do terminal.

Seu primeiro projeto em 90 segundos

Você não precisa saber nada técnico para começar. Abra o aplicativo desktop do FlowForge e você chega a uma tela de boas-vindas tranquila. A partir daí são cerca de um minuto e meio até um projeto funcionando — dois cliques e algumas respostas em linguagem simples.

1. Abra o aplicativo. Dê um duplo clique no FlowForge. A tela de boas-vindas aparece — nenhuma conta para configurar antes, nada para ajustar.

2. Escolha “Start something new”. Na tela de boas-vindas, selecione + Start something new (“+ Começar algo novo”). Essa é a porta de entrada para começar do zero: você não precisa de uma pasta existente nem de nada preparado.

3. Diga o que você quer construir. O FlowForge pergunta, em palavras simples, O que você quer construir? Responda em uma ou duas frases — “uma página de agendamento para o meu estúdio”, “algo para acompanhar minhas plantas”. Seja o que for, palavras simples são perfeitas.

4. Acrescente alguns detalhes. Uma segunda pergunta — O que isso deve fazer? — deixa você dizer um pouco mais. Mantenha curto; você pode refinar depois, e pode até deixar em branco por enquanto.

5. Deixe o FlowForge construir. O FlowForge prepara um projeto para você — uma única pasta no seu computador que guarda tudo sobre essa ideia. Você nunca precisou criar ou nomear nenhuma das peças técnicas; o FlowForge cuidou de tudo isso silenciosamente, nos bastidores.

6. Escolha se quer manter um backup online. O FlowForge oferece salvar uma cópia privada online, guardada na sua própria conta do GitHub, para que o seu trabalho fique seguro mesmo se algo acontecer com o seu computador. É opcional — “Agora não, manter neste computador” é uma opção tão válida quanto qualquer outra, e você pode ativar um backup depois, a qualquer momento.

7. Você está pronto. Seu projeto abre e o FlowForge orienta você a partir daí — você nunca está sozinho. A partir deste momento, toda hora que você dedica é rastreada, e o seu trabalho é salvo à medida que você avança.

Essa é a jornada completa: descreva sua ideia → responda duas perguntas simples → seu projeto está pronto. Tudo o que é técnico — criar a pasta do projeto, salvar o seu progresso, manter o backup online sincronizado — o FlowForge faz por você, longe da vista.

Uma nota sobre as palavras. No FlowForge, um projeto é simplesmente uma pasta em que você trabalha, e manter um backup online significa que uma cópia privada fica guardada junto com a sua conta. Você nunca precisa aprender o funcionamento por baixo dos panos — esconder isso é o objetivo.

Instale ao lado do Claude Code

Este caminho é para quem já usa o Claude Code; o FlowForge se instala ao lado dele. O instalador de uma linha baixa o binário lançado e o integra ao seu ambiente:

curl get.flowforgesoft.com/install.sh | sh

O instalador posiciona o binário e, em seguida, executa flowforge install --global, que registra o FlowForge no Claude Code — os hooks, os comandos de barra, o servidor MCP e a seção gerenciada do seu CLAUDE.md global.

Reinicie o Claude Code após a primeira instalação para que ele reconheça o servidor MCP do FlowForge.

O layout do binário (por que há duas cópias)

Uma instalação correta tem duas cópias byte a byte idênticas do mesmo binário lançado:

• /usr/local/bin/flowforge — a cópia que o instalador baixa e coloca no seu PATH.
• ~/.flowforge/bin/flowforge — uma autocópia em um caminho absoluto estável, que os hooks e o servidor MCP invocam sem brigar com o $PATH.

Ambas precisam ser a mesma versão — isso é “uma única versão”. Você nunca compila à mão nem copia um binário para o lugar; novas versões chegam apenas pelo pipeline de release (flowforge version update ou reexecutando o instalador). A regra de ouro é que a sua máquina permaneça idêntica à instalação de um cliente, de modo que os bugs que você vê sejam os bugs que ele vê — nem mais, nem menos.

Verifique a instalação

flowforge version        # imprime a versão instalada
flowforge doctor         # autorrepara caminhos obsoletos, hooks ausentes, desvio de config

O flowforge doctor é seguro de rodar a qualquer momento. O FlowForge foi projetado para se autorreparar: falhas visíveis ao cliente (um caminho obsoleto, um hook ausente) se consertam sozinhas na instalação, na atualização e ao iniciar o cockpit, porque a pessoa que poderia corrigi-las à mão geralmente não estará presente.

Sua primeira sessão

Todo trabalho começa da mesma forma — inicie uma sessão sobre um ticket:

/flowforge:session:start 123

Esse único comando faz tudo o que o caminho disciplinado exige:

1. Verifica o ticket — confere se ele existe e está aberto (GitHub, Linear, Jira ou local).
2. Inicia o cronômetro — o registro faturável começa aqui.
3. Coloca você em uma branch de feature — nunca na main, nunca na develop.
4. Restaura o contexto de qualquer sessão anterior no mesmo ticket.

Quando ele retorna, você está na branch certa, o relógio está correndo e você está pronto para construir. Se não passar um número de ticket, o FlowForge tenta detectar um a partir da sua sessão atual ou das issues abertas atribuídas a você.

O cockpit (opcional, mas recomendado)

Para uma visão interativa do seu trabalho — cronômetros, estado dos tickets e despacho de agentes — inicie o cockpit no terminal:

flowforge tui

O cockpit é abordado em ForgePlay e o Cockpit. Você pode fazer tudo apenas com os comandos de barra, mas é no cockpit que o fluxo de trabalho se torna visível.

Por que isso importa

Seja qual for a porta pela qual você entrou — o passo a passo do aplicativo desktop ou a instalação pelo terminal — você chega ao mesmo lugar: um trabalho rastreado, salvo e vinculado a um projeto desde o primeiro minuto. Esse é o objetivo dos Primeiros Passos. Todo o resto deste manual se constrói sobre essa base.