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.

Antes de começar: baixe o aplicativo. Baixe o FlowForge Desktop em flowforgesoft.com/desktop — o botão Download FlowForge Desktop passa primeiro pelo cadastro.

• macOS — o cockpit inteiro abre com um duplo clique.
• Linux — o aplicativo desktop é x86_64 por enquanto.
• Windows — o FlowForge roda a versão Linux dentro do WSL2: configure o WSL2 uma vez e depois inicie o FlowForge pelo shell do WSL. O aplicativo é x86_64 por enquanto.

1. Abra o aplicativo e faça os dois logins. Dê um duplo clique no FlowForge. Na primeira vez, ele mostra Finish setting up FlowForge (“Termine de configurar o FlowForge”) com duas linhas, e cada uma pede o seu próprio login:

• FlowForge account (conta FlowForge) — a sua assinatura do FlowForge. É preciso ter uma conta para usar o FlowForge.
• Claude Code — o seu login da Anthropic. Sign in abre o navegador; se o navegador mostrar um código em vez de concluir sozinho, cole-o em Code from your browser (“Código do seu navegador”). O FlowForge nunca pede a sua senha da Anthropic.

Você faz os dois uma vez em cada computador, de dentro do aplicativo — sem terminal. Com as duas linhas concluídas, a tela de boas-vindas aparece.

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 que você precisa antes

• macOS ou Linux — no Windows, dentro do WSL2.
• Claude Code, na versão mínima que o FlowForge suporta ou acima dela. Você não precisa decorar o número: com o FlowForge instalado, flowforge version mostra a sua versão do Claude Code ao lado da mínima (floor) e da mais nova com que ele foi testado.
• tmux — o cockpit e os workers rodam dentro dele.
• A CLI do GitHub, gh, com login na sua conta do GitHub — o FlowForge lê os seus tickets e abre pull requests por ela.
• Uma conta FlowForge.

Instale

O instalador de uma linha baixa o binário lançado e o integra ao seu ambiente:

curl -fsSL https://get.flowforgesoft.com/install.sh | sh

Digite exatamente assim, com https:// e -fsSL. Sem eles, o curl pode entregar ao sh uma página de redirecionamento no lugar do instalador.

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.

Faça login

O FlowForge precisa de dois logins, e eles são separados: entrar em um nunca faz você entrar no outro.

flowforge login          # a sua conta FlowForge (e-mail e senha)
flowforge claude login   # Claude Code — abre o navegador

Rode-os de qualquer pasta; o login vale para todos os seus projetos. Para ver como está sem responder a nenhuma pergunta, rode flowforge login --status e flowforge claude status. No cockpit, @ abre o login do Claude Code: veja a conta, entre ou troque de conta.

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

Atualize

flowforge update            # instala a versão mais recente e repara esta instalação
flowforge update --check    # só diz se existe uma versão mais nova

O flowforge update é seguro de rodar com o cockpit aberto. Se uma instalação parecer quebrada, flowforge update --repair refaz os arquivos do FlowForge a partir do binário que já está no disco, sem baixar nada — funciona offline.

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.