ClaudeControl

AI Agent Dashboard para gerenciar múltiplos agentes Claude Code em vários projetos ao mesmo tempo.

ClaudeControl centraliza chat de agentes, execução de tools, diffs de código, editor de arquivos e status de git em uma interface web única.

• npm: https://www.npmjs.com/package/@lucashca/claudecontrol
• GitHub: https://github.com/lucashcaraujo/claude-control
• Issues: https://github.com/lucashcaraujo/claude-control/issues

Vídeos completos com player: GitHub Pages

Sumário

• Por que usar
• Instalação
• Quick Start
• Comandos CLI
• Seção npm (release)
• Recursos
• Arquitetura
• Fluxo de agentes
• Permissões e segurança
• Estrutura .claudecontrol
• Controles de custo
• Desenvolvimento local
• Troubleshooting
• Requisitos
• Licença

Por que usar

• Vários workspaces em paralelo com estados isolados
• Agentes com as mesmas ferramentas do Claude Code (Read, Glob, Grep, Bash, Write, Edit)
• Aprovação inline de permissões (modo seguro)
• Modo bypass para fluxos assistidos/autônomos
• Diffs inline para cada alteração de código
• Editor de arquivos no browser com múltiplas tabs
• Sync de agentes customizados para .claude/commands
• Notificações (som e push)
• Acesso remoto opcional com Cloudflare Tunnel

Instalação

npm install -g @lucashca/claudecontrol

Quick Start

claudecontrol init

Abra no navegador:

http://localhost:22609

O init executa:

• validação do binário Claude Code
• instalação de dependências backend/frontend
• build do frontend
• inicialização do backend em background

Comandos CLI

| Comando | Descrição | |---|---| | claudecontrol init | setup completo + start | | claudecontrol start | inicia servidor | | claudecontrol stop | encerra servidor | | claudecontrol status | status da instância | | claudecontrol -v | versão |

Exemplos:

# porta customizada
PORT=3000 claudecontrol start

# binário Claude customizado
CLAUDE_PATH=/usr/local/bin/claude claudecontrol start

Seção npm (release)

Fluxo padrão:

npm version patch
npm publish

Validações automáticas no prepublishOnly:

• sincroniza version.json com package.json
• valida presença de README.md no tarball (npm pack --dry-run --json)

Scripts úteis:

npm run publish:npm
npm run release:patch

Recursos

Multi-workspace

• abas por projeto
• estado independente por workspace
• indicador de atividade por aba

Agentes

• criação e execução por papel (role)
• subagentes com agrupamento visual no chat
• envio de anexos para o contexto do agente

Ferramentas e diffs

• saída de tools no chat
• diffs inline para Edit
• diff viewer lado a lado

Explorer + editor

• árvore de arquivos
• editor no browser
• múltiplas tabs abertas

Git e notificações

• status de git por workspace
• notificações de conclusão de tarefas
• push notifications configuráveis

Arquitetura

backend/
  agents/     # lifecycle, conversation, roles, permissions
  routes/     # workspaces, agents, files, git, settings
  ws.ts       # websocket broadcast + permission responses

frontend/
  components/ # chat, sidebar, workspace, settings
  hooks/      # regras de negócio UI
  atoms/      # estado global (Jotai)

bin/
  claudecontrol.js  # CLI

Tecnologias:

• Backend: Node.js + TypeScript + Anthropic Agent SDK
• Frontend: React + Vite + Tailwind + Jotai
• Realtime: WebSocket

Fluxo de agentes

1. Usuário cria/abre um workspace
2. ClaudeControl detecta papéis disponíveis
3. Agente inicia via SDK no cwd do workspace
4. Tool calls disparam aprovação (modo seguro) ou auto-allow (bypass)
5. Logs + outputs + diffs são transmitidos em realtime
6. Agentes customizados podem ser sincronizados para .claude/commands

Permissões e segurança

Modo seguro

• ações sensíveis pedem aprovação (Aprovar/Negar)
• ideal para uso diário

Modo bypass

• aprova automaticamente chamadas sensíveis
• indicado para fluxos supervisionados

PIN

• opcional para proteger dashboard
• protege API e WebSocket
• recomendado para acesso remoto

Estrutura .claudecontrol

.claudecontrol/
├── agents/              # prompts de agentes customizados
│   ├── frontend-expert.md
│   ├── backend-expert.md
│   └── orchestrator.md
└── context/             # contexto adicional compartilhado
    └── project-notes.md

Sync para Claude Code:

• origem: .claudecontrol/agents/*.md
• destino: .claude/commands/*.md
• ação: botão Sync no painel lateral

Pool Mode — agentes persistentes e mais baratos

O ClaudeControl opera em pool mode por padrão: cada especialista é um processo Claude Code independente com seu próprio contexto. Isso é fundamentalmente diferente do modo subagente nativo do Claude, onde todos os subagentes rodam dentro do contexto do orquestrador.

Benchmark medido

Tarefa: construir um portal de notícias completo (SPA com login, listagem, detalhe — 7–8 arquivos, 3 especialistas).

| Modo | Custo | Tempo | Turns | |------|-------|-------|-------| | Pool (ClaudeControl) | $0.97 | ~5 min | 72 distribuídos | | Subagente nativo | $1.20 | ~5 min | 13 no orquestrador | | Economia | ~19% | — | — |

Por que o pool escala melhor

No modo subagente nativo, cada turno do orquestrador carrega o contexto acumulado de todos os subagentes — o custo cresce com o tamanho do projeto. No pool mode, cada agente mantém seu próprio contexto isolado; o custo escala proporcionalmente ao trabalho realizado.

| Escala do projeto | Pool | Subagente nativo | Economia estimada | |---|---|---|---| | Pequeno (este benchmark) | $0.97 | $1.20 | ~19% | | Médio (~10x) | ~$10 | ~$18 | ~45% | | Grande (~30x) | ~$29 | ~$79 | ~63% | | SaaS completo (~50x) | ~$49 | ~$180 | ~73% |

As projeções assumem que o custo do pool escala linearmente e o custo do subagente nativo escala super-linearmente pelo acúmulo de contexto. Resultado real pode variar.

Outras vantagens do pool mode

• Visibilidade — cada agente aparece individualmente com seu log, custo e status em tempo real
• Persistência — agentes continuam entre sessões com histórico completo
• Controle — pause, interrompa ou delegue para agentes específicos a qualquer momento
• Rastreamento — custo separado por agente, por tarefa e por sessão

Controles de custo

Use variáveis de ambiente para reduzir consumo:

CC_MAX_TURNS=8
CC_MAX_BUDGET_USD=0.50
CC_MODEL=claude-haiku-4-5-20251001
CC_FALLBACK_MODEL=claude-sonnet-4-5
CC_ENABLE_SUBAGENTS=false
CC_CONTEXT_MAX_CHARS=12000
CC_SUBAGENT_LIMIT=8
CC_SUBAGENT_PROMPT_MAX_CHARS=5000

Desenvolvimento local

# backend
cd backend
npm run dev

# frontend
cd frontend
npm run dev

Build:

cd backend && npm run build
cd frontend && npm run build

Troubleshooting

README não aparece no npm

• confirme README.md na raiz
• rode npm pack --dry-run --json
• publique nova versão (npm version patch && npm publish)

.claude/ pedindo permissão

• comportamento esperado para path protegido
• use .claudecontrol/ + Sync

consumo alto de créditos

• reduza CC_MAX_TURNS
• configure modelo mais barato em CC_MODEL
• desative subagentes com CC_ENABLE_SUBAGENTS=false

Requisitos

• Node.js 20+
• Claude Code instalado nativamente
• cloudflared opcional (acesso remoto)

Licença

MIT