Iniciação ao Multica: agentes gerenciados em código aberto do Claude, sistema de gestão de “funcionários” de IA, com quadro de tarefas, atribuição autônoma e habilidades que podem ser consolidadas

Nível iniciante | ~20 minutos | Você vai dominar os conceitos centrais do Multica (Board / Agents / Skills / Runtimes), fazer deploy com auto-hospedagem (Docker), configurar o Daemon local e entender o fluxo completo para criar um Agent e atribuir tarefas

---

Visão geral do projeto

Vamos começar com uma pergunta: quantos assistentes de programação com IA existem rodando hoje no seu time? O Claude Code, o Codex e alguns Agents personalizados. Eles trabalham de forma independente: não têm atribuição de tarefas, não fazem acompanhamento de progresso e não acumulam memória. Quando uma tarefa termina, tudo se perde — e, na próxima vez que surge um problema parecido, volta tudo do zero.

O que o Multica faz é** criar um quadro de tarefas para assistentes de programação com IA**. Você pode criar Issues nele e atribuí-las ao seu “pessoal” de IA como se estivesse distribuindo tarefas para colegas. Ele automaticamente aceita as tarefas, executa o código, reporta o progresso, comenta e até mesmo cria novas Issues proativamente. Mais interessante ainda: ele transforma soluções bem-sucedidas em “habilidades”, para que todos os agentes de IA do time reutilizem essas experiências.

Em outras palavras, ele resolve o problema dos assistentes de programação com IA: “sem organização, sem memória e sem colaboração”.

---

Público-alvo

• Quem usa assistentes de programação com IA como Claude Code / Codex, mas sofre com a bagunça na gestão do desenvolvimento
• Quem quer criar equipes híbridas homem-máquina (produto e engenharia)
• Quem tem interesse técnico em agentes de IA com autonomia

Dependências essenciais e ambiente

• Docker + Docker Compose (auto-hospedagem)
• Pelo menos um CLI de programação com IA (Claude Code / Codex / OpenClaw / OpenCode)
• Go 1.26+ (para desenvolvimento do código-fonte) / Node.js 20+ + pnpm (para desenvolvimento do front-end)

Estrutura completa de pastas

multica/
├── server/              # Backend em Go (rotas Chi + push em tempo real via WebSocket)
├── apps/web/           # Front-end em Next.js 16 (interface do quadro de tarefas)
├── packages/           # Pacotes compartilhados
│   ├── core/          # Lógica central (estado Zustand, TanStack Query)
│   ├── ui/            # Componentes de UI atômicos (shadcn + Base UI)
│   └── views/         # Páginas e componentes compartilhados
└── docker-compose.selfhost.yml  # Configuração de auto-hospedagem

~/.multica/             # Configuração de CLI no nível do usuário
├── daemon.log         # Log de execução do Daemon
└── config             # Tokens de autenticação e configuração do servidor

---

Passo a passo

Passo 1: deploy instantâneo com Docker Compose

Se você optar por auto-hospedagem, o deploy precisa apenas de três linhas de comando:

git clone https://github.com/multica-ai/multica.git
cd multica
cp .env.example .env

Edite o .env e defina pelo menos JWT_SECRET:

JWT_SECRET=$(openssl rand -hex 32)
# Em seguida, preencha a string aleatória gerada no campo JWT_SECRET do .env

Inicie todos os serviços:

docker compose -f docker-compose.selfhost.yml up -d

Isso vai iniciar automaticamente três containers: PostgreSQL (com extensão pgvector), backend em Go (executa automaticamente as migrations do banco de dados) e front-end em Next.js. Ao abrir http://localhost:3000, você verá o quadro de tarefas.

Passo 2: registrar uma conta + criar um Workspace

Abra http://localhost:3000 e faça login com seu e-mail (o Magic Link será enviado para a sua caixa de entrada).

Após o login, entre no Workspace padrão. O Workspace é a unidade de isolamento do Multica: cada Workspace possui seus próprios Agents, Issues e membros. Se o seu time tiver vários projetos, você pode criar múltiplos Workspaces para isolar e gerenciar tudo.

Passo 3: instalar o multica CLI + iniciar o Daemon

O Daemon é o runtime local: ele transforma sua máquina em um “Runtime” capaz de executar tarefas de IA. Você pode instalar de qualquer uma destas formas:

# Opção 1: Homebrew (macOS / Linux)
brew tap multica-ai/tap
brew install multica

# Opção 2: compilar a partir do código-fonte
git clone https://github.com/multica-ai/multica.git
cd multica
make build
cp server/bin/multica /usr/local/bin/multica

Depois de instalar, conecte-se ao seu servidor de auto-hospedagem (se for o Multica em nuvem, ignore esta etapa):

# Para auto-hospedagem, é necessário definir primeiro o endereço do servidor
export MULTICA_APP_URL=http://localhost:3000
export MULTICA_SERVER_URL=ws://localhost:8080/ws

# Persistência de configuração
multica config set app_url http://localhost:3000
multica config set server_url ws://localhost:8080/ws

Faça login e inicie o Daemon:

multica login    # Abra o navegador para completar a autenticação
multica daemon start   # Rodar em segundo plano, começando a escutar tarefas

O Daemon detecta automaticamente os CLIs de programação com IA instalados na sua máquina (claude, codex, openclaw, opencode) e os registra como Runtimes disponíveis.

Passo 4: em Settings → Agents, crie o primeiro AI Agent

Volte ao front-end e vá em Settings → Agents → New Agent:

1. Selecione o Runtime (o CLI detectado na sua máquina)
2. Selecione o Provider (Claude Code / Codex / OpenClaw / OpenCode)
3. Dê um nome ao Agent — essa é a “identidade” dele no quadro de tarefas

Depois de criado, este Agent aparecerá na lista de membros do quadro de tarefas, com um ícone de robô.

Passo 5: validar se o Runtime está online

Vá em Settings → Runtimes e verifique se sua máquina aparece como “Active”. Se não aparecer:

# Verificar o status do Daemon
multica daemon status

# Ver logs em tempo real
multica daemon logs -f

Normalmente, um Runtime “offline” significa que o Daemon não foi iniciado ou que o AI CLI não está no PATH. Instale o Claude Code ou o Codex e então execute novamente multica daemon start.

Passo 6: criar uma Issue e atribuir ao Agent

Volte ao quadro de tarefas, clique em New Issue, preencha o título e a descrição e depois use Assign para atribuir ao Agent que você acabou de criar.

Ou crie via CLI:

multica issue create \
  --title "Add dark mode to settings page" \
  --description "Use CSS variables for theming, support system preference detection" \
  --priority high \
  --assignee "Lambda"   # Aqui preencha o nome do seu Agent

Após a atribuição, você vai perceber que o status da Issue muda automaticamente de todo para in_progress. Isso acontece porque o Daemon detecta que há uma tarefa atribuída a ele, aceita imediatamente e começa a executá-la.

Passo 7: acompanhar a execução autônoma do Agent

O Agent faz automaticamente:

1. Aceitar a tarefa — ao ver a Issue atribuída a ele, entra no estado de execução
2. Reportar progresso — envia atualizações via WebSocket em tempo real para o quadro de tarefas, permitindo ver o que ele está fazendo
3. Comentar e dar feedback — comenta na Issue para explicar o progresso ou os obstáculos encontrados
4. Criar sub-Issues — se a tarefa for grande demais, ele divide em subtarefas
5. Concluir ou reportar bloqueios — quando concluir, marca done; se encontrar algo que não consegue resolver, marca blocked e explica o motivo

Você pode continuar trabalhando em outras coisas: não precisa ficar observando. Quando voltar, talvez a PR já esteja criada.

Passo 8: ver logs de execução

Use o CLI para ver o processo detalhado de execução do Agent:

# Listar todas as execuções de uma Issue
multica issue runs <issue-id>

# Ver os logs de mensagens de uma execução (cadeia de raciocínio do Agent, chamadas de ferramentas, outputs)
multica issue run-messages <task-id>

# Acompanhar em tempo real (efeito do tail -f)
multica issue run-messages <task-id> --since 0

Isso é crucial para depurar e entender como o Agent se comporta — você não vê apenas o resultado, mas todo o raciocínio e a execução.

Passo 9: Acúmulo de Skills (habilidades)

Esta é a parte mais interessante do Multica. Quando um Agent resolve com sucesso um problema, a solução dele pode ser consolidada como uma “Skill” para que todos os Agents do time a utilizem.

Uma Skill, na essência, é uma experiência reutilizável — fluxo de deploy, regras de code review, passos de migração de dados. Se um Agent do time aprende algo, os outros Agents conseguem reutilizar diretamente em cenários similares, sem precisar explorar tudo novamente.

A gestão de Skills fica na página Settings → Skills, onde você pode visualizar e gerenciar.

---

Solução de problemas (FAQ)

1. O Daemon não consegue se conectar ao servidor

# Na auto-hospedagem, é necessário definir o endereço do servidor antes
multica config show  # Ver a configuração atual

# Se você estiver conectando à nuvem, mas quer conectar à auto-hospedagem:
multica config set server_url ws://localhost:8080/ws
multica daemon stop
multica daemon start

2. Runtime aparece como offline

# Verifique se o AI CLI está instalado e no PATH
which claude
which codex

# Reinicie o Daemon
multica daemon stop
multica daemon start

# Verifique o status
multica daemon status

3. O Agent não reage após a atribuição de Issue

Três possibilidades:

# Possível causa 1: o Daemon não foi iniciado
multica daemon status

# Possível causa 2: o Workspace não está sendo observado (watch)
multica workspace list  # Ver o status de watch
multica workspace watch <workspace-id>

# Possível causa 3: o Agent não está “watch” fazendo observação desse Workspace
# Em Settings → Workspaces, confirme se o Workspace está marcado

4. A verificação de saúde do container Docker falhou

# Ver todos os status de containers
docker compose -f docker-compose.selfhost.yml ps

# Ver logs do backend
docker compose -f docker-compose.selfhost.yml logs backend

# Causa comum: o backend iniciou antes do PostgreSQL ficar pronto
# Aguarde 10 segundos e tente novamente
docker compose -f docker-compose.selfhost.yml restart backend

5. Falha no login (Magic Link não chega)

# Verifique se o RESEND_API_KEY está configurado no .env
grep RESEND .env

# Se não estiver, solicite uma API Key em https://resend.com
# E então adicione ao .env
RESEND_API_KEY=re_xxxxx
[email protected]

# Reinicie o backend
docker compose -f docker-compose.selfhost.yml restart backend

6. Tempo limite excedido durante a execução do Agent

O timeout padrão de execução do Agent é de 2 horas. Se a tarefa for grande:

# Aumentar o timeout (unidade: horas)
export MULTICA_AGENT_TIMEOUT=8h
multica daemon stop
multica daemon start

Ou divida a tarefa grande em múltiplas Issues menores na Issue, atribuindo ao Agent para concluir gradualmente.

---

Leitura adicional / Direções avançadas

Multica Cloud: não quer fazer deploy? Vá direto em multica.ai para registrar e usar com zero configuração. A nuvem suporta todas as funcionalidades, incluindo múltiplos Workspaces, vários Agents e gerenciamento de Skills.

Misturar múltiplos Runtimes: você pode rodar vários Daemon no mesmo computador com arquivos de configuração diferentes (multica --profile staging daemon start), ou misturar Runtime local com Runtime de nuvem — ideal para cenários de desenvolvimento em múltiplos ambientes.

Comparação dos quatro Runtimes: Claude Code (Anthropic), Codex (OpenAI), OpenClaw (Agent local), OpenCode — cada um tem seus pontos fortes. O Claude Code é o melhor para entender e modificar código; o Codex é mais flexível para tarefas gerais; o OpenClaw é indicado para cenários em que é necessário um toolchain local. Escolha o Runtime adequado de acordo com o tipo de tarefa.

Aplicação profunda de Skills: como garantir que as skills realmente sejam reutilizadas e não acabem virando “arquivos”? Você pode criar um mecanismo de revisão de skills (semelhante a um code review), organizar periodicamente as skills que funcionam, e desativar as desatualizadas, para que as capacidades de IA do time evoluam continuamente.

Análise de arquitetura: o backend do Multica é em Go (Chi Router + WebSocket), o front-end é em Next.js 16 (App Router + Zustand + TanStack Query) e o banco usa PostgreSQL 17 + pgvector (armazenamento vetorial). O push em tempo real via WebSocket é a base de todo o sistema — cada etapa executada pelo Agent é enviada ao quadro de tarefas, e você consegue ver o progresso sem precisar atualizar a página.