npm package: @lucashca/claudecontrol
Description: AI Agent Dashboard — manage multiple Claude Code agents across projects
Author: Lucas Araujo
Latest version: 0.5.29

# ClaudeControl

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

[![npm version](https://img.shields.io/npm/v/@lucashca/claudecontrol?color=%236d28d9&label=npm&style=for-the-badge)](https://www.npmjs.com/package/@lucashca/claudecontrol)
[![node version](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=for-the-badge&logo=node.js)](https://nodejs.org)
[![license](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)

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

![ClaudeControl Demo](docs/screenshots/demo.gif)

> Vídeos completos com player: [GitHub Pages](https://lucashcaraujo.github.io/claude-control/)

---

## Sumário

- [Por que usar](#por-que-usar)
- [Instalação](#instalação)
- [Quick Start](#quick-start)
- [Comandos CLI](#comandos-cli)
- [Seção npm (release)](#seção-npm-release)
- [Recursos](#recursos)
- [Arquitetura](#arquitetura)
- [Fluxo de agentes](#fluxo-de-agentes)
- [Permissões e segurança](#permissões-e-segurança)
- [Estrutura `.claudecontrol`](#estrutura-claudecontrol)
- [Controles de custo](#controles-de-custo)
- [Desenvolvimento local](#desenvolvimento-local)
- [Troubleshooting](#troubleshooting)
- [Requisitos](#requisitos)
- [Licença](#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

```bash
npm install -g @lucashca/claudecontrol
```

## Quick Start

```bash
claudecontrol init
```

Abra no navegador:

```txt
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:

```bash
# 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:

```bash
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:

```bash
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

```txt
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`

```txt
.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:

```bash
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

```bash
# backend
cd backend
npm run dev

# frontend
cd frontend
npm run dev
```

Build:

```bash
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