taskswarm

TaskSwarm

Instalação • Início rápido • O que ele faz • Referência da CLI • Servidor MCP • Como ele se compara • FAQ

Servidor de eventos auto-hospedado e CLI que dispara uma notificação local do sistema operacional e atualiza uma página de status ao vivo no instante em que uma sessão de agente de codificação paralela fica bloqueada, precisa de revisão, falha ou termina.

Você está executando três sessões do Claude Code em dois repositórios. Uma delas encontrou um prompt de permissão há quatro minutos e está parada desde então, esperando por você. Você não sabia, porque nada te avisou. Você apenas voltou para verificar.

TaskSwarm é um servidor de eventos auto-hospedado que resolve isso. Cada sessão de agente reporta seu estado, e no instante em que uma fica bloqueada, precisa de revisão, falha ou termina, o TaskSwarm dispara uma notificação local do sistema operacional e atualiza uma página de status ao vivo. Sem ficar monitorando terminais. Sem conta. Sem dependência de nuvem.

Instalação

O TaskSwarm é distribuído como duas distribuições independentes e igualmente de primeira classe do mesmo servidor de eventos — um pacote npm (este código, TypeScript) e um pacote PyPI (taskswarm-cli, Python, python/). Escolha o que se encaixa na sua ferramenta; o servidor e a CLI não precisam ser da mesma distribuição que o agente do qual você está reportando.

npm (JS/TS): disponível no npm como taskswarm-cli:

npm install -g taskswarm-cli
taskswarm start

Prefere não instalar globalmente? npx taskswarm-cli start executa o mesmo binário sem etapa de instalação.

pip (Python): disponível no PyPI como taskswarm-cli (renomeado do pacote original taskswarm, que parou de receber atualizações e aponta para cá):

pip install taskswarm-cli
taskswarm start

Veja python/README.md para o guia específico de Python. Ambas as distribuições falam o mesmo protocolo de rede (o mesmo esquema de eventos, a mesma regra de deduplicação de notificações), então um servidor iniciado em Python e uma CLI npm reportando para ele (ou vice-versa) funcionam juntos sem problema.

Início rápido

# Terminal 1: start the server
node dist/cli.js start
# TaskSwarm server listening on http://127.0.0.1:4173
# Live status page: http://127.0.0.1:4173/?token=<your-token>

# Terminal 2: report a session's status as it works
node dist/cli.js agent report-status --task my-fix --repo ./api --state running
node dist/cli.js agent report-status --task my-fix --repo ./api --state done

Abra a URL da página de status ao vivo impressa por start. A linha para my-fix é atualizada no instante em que cada chamada de report-status chega, sem atualização manual. Esta é a saída real desse fluxo, capturada enquanto este README era escrito:

{
  "sessions": [
    {
      "session_id": "my-fix",
      "latest": { "repo": "./api", "agent_type": "generic", "status": "done", "...": "..." },
      "history": [
        { "status": "running", "timestamp": "2026-07-15T23:46:41.376Z" },
        { "status": "done", "timestamp": "2026-07-15T23:46:41.436Z" }
      ]
    }
  ]
}

Integre-o diretamente ao Claude Code em vez de chamar report-status manualmente:

node dist/cli.js hooks install claude-code

Isso escreve os hooks Stop/Notification em .claude/settings.json para o projeto atual. Cada turno que o Claude Code termina, e cada prompt de permissão ou espera ociosa que ele exibe, agora reporta automaticamente para o TaskSwarm.

Acompanhe tarefas localmente, independentemente do estado da sessão ao vivo (uma lista de tarefas leve, não o feed de eventos):

node dist/cli.js task add --title "Fix flaky test" --repo ./api
node dist/cli.js task list

O que ele faz

• Notificações push, a partir de um quadro que você não precisa manter aberto. No momento em que uma sessão transita para blocked, needs-review, failed ou done, o TaskSwarm dispara uma notificação nativa do sistema operacional (osascript no macOS, um sino de terminal como fallback em outros lugares). Latência de envio medida abaixo. Nenhum dos paperclip, Vibe Kanban ou Multica (veja a comparação abaixo) faz isso; todos os três são quadros que você precisa estar olhando.
• Uma página de status ao vivo que atualiza via eventos enviados pelo servidor, não por polling. Uma tabela simples: sessão, repositório, tipo de agente, status, timestamp do último evento. Sem botão de atualizar.
• Integração real de hooks do Claude Code, verificada contra a referência de hooks publicada. taskswarm hooks install claude-code escreve entradas de hook Stop e Notification em .claude/settings.json, apontando para o binário Node exato e o script CLI já presentes no disco. Ele evita deliberadamente npx; veja o comentário no código em src/adapters/claude-code-adapter.ts para entender por que a resolução flutuante de registro a cada disparo de hook é um risco de cadeia de suprimentos. Uma ressalva dita claramente: o hook Stop do Claude Code dispara por turno, não por tarefa, então uma sessão longa de múltiplos turnos atualmente reporta done após cada turno, não apenas no final.
• Um fallback de script wrapper para Codex, Cursor ou qualquer outra coisa. taskswarm agent report-status --task <id> --repo <path> --state <state> é o mesmo primitivo que o adaptador do Claude Code chama internamente. Qualquer script que envolva qualquer agente CLI pode chamá-lo diretamente.
• Uma API local protegida por token de portador, vinculada ao loopback por padrão. POST /events e a página ao vivo exigem o token que o TaskSwarm gera na primeira execução (~/.taskswarm/config.json, escrito em 0600). Gire-o com taskswarm token rotate.
• Projetado para agentes por natureza. Todo subcomando inclui uma flag --json com um esquema estável, incluindo saída de erro, para que um script que chama esta CLI nunca precise extrair texto formatado para humanos.
• ntfy.sh é opcional, nunca padrão. O único canal de notificação que sai da sua máquina, e está desligado a menos que você o ative. A alegação de auto-hospedagem se mantém de ponta a ponta sem ele.

[!NOTE] A notificação push nativa do sistema operacional só dispara no macOS, via osascript. No Linux e no Windows, o TaskSwarm cai para uma linha de console mais um sino de terminal em vez de uma notificação do sistema, ainda local, ainda sem ntfy.sh a menos que você opte por ele.

Referência da CLI

Capturado diretamente da saída de --help na CLI compilada (node dist/cli.js <command> --help):

Comando	Descrição	Opções principais
taskswarm start	Inicia o servidor TaskSwarm e imprime a URL da página de status ao vivo	--json
taskswarm task add	Registra uma nova tarefa	--title <title> (obrigatório), --repo <path> (obrigatório), --json
taskswarm task list	Lista tarefas rastreadas, enriquecidas com status ao vivo quando o servidor está acessível	--json
taskswarm agent report-status	Reporta uma transição de status para uma tarefa/sessão ao servidor local	--task <id> (obrigatório), --repo <path> (obrigatório), --state <state> (obrigatório, um de queued|running|blocked|needs-review|done|failed), --blocked-reason <text>, --agent-type <type> (claude-code|codex|cursor|generic, padrão generic), --json
taskswarm token rotate	Gera um novo token de portador, invalidando o antigo	--json
taskswarm hooks install <adapter>	Instala hooks para uma integração de agente (atualmente claude-code)	--scope <project|local|user> (padrão project), --project-dir <path>, --json
taskswarm hooks claude-code-relay	Interno: lê um payload de hook do stdin e o retransmite. Instalado automaticamente; não deve ser executado manualmente.	nenhuma

Todo subcomando também aceita -h, --help. taskswarm --version imprime o número da versão do pacote instalado, lido ao vivo de package.json (para que sempre corresponda à versão que você realmente tem instalada, em vez de um número fixo que ficaria desatualizado aqui).

Uma falha real, para referência

$ node dist/cli.js agent report-status --task foo --repo /tmp/x --state bogus
error: option '--state <state>' argument 'bogus' is invalid. Allowed choices are queued, running, blocked, needs-review, done, failed.

$ node dist/cli.js agent report-status --task foo --repo /tmp/x --state blocked
Error: could not reach TaskSwarm server at http://127.0.0.1:4173 -- is it running? (`taskswarm start`)

Ambos saem com código não zero, com uma mensagem em inglês simples e sem stack trace, inclusive sob --json.

Referência da API da biblioteca

O pacote npm também é importável, não apenas executável como CLI: main/types apontam para dist/index.js/dist/index.d.ts, e src/index.ts exporta uma superfície pública real para qualquer coisa que queira incorporar o armazenamento de eventos, o servidor ou os adaptadores diretamente, em vez de chamar via shell.

Esquema (src/schema/events.ts)

• agentEventSchema, agentEventInputSchema — esquemas Zod para o envelope de eventos
• toAgentEvent(input: AgentEventInput): AgentEvent — preenche os padrões de event_id/timestamp/schema_version
• AGENT_TYPES, AGENT_STATUSES — os arrays const que sustentam os tipos de união AgentType/AgentStatus
• NOTIFY_ON_STATUSES: ReadonlySet<AgentStatus> — os quatro status que disparam uma notificação: blocked, needs-review, failed, done
• CURRENT_SCHEMA_VERSION — o número da versão atual do envelope

Servidor (src/server/)

• class EventStore extends EventEmitter — armazenamento de sessão em memória apoiado por um log JSONL somente anexação. constructor(logPath?: string, options?: EventStoreOptions). Métodos: append(event): { previousStatus, previousBlockedReason }, getSession(sessionId): SessionState | undefined, listSessions(): SessionState[], size(): number. Emite 'event' a cada anexação.
• startServer(options?: StartServerOptions): Promise<RunningServer> — inicia o armazenamento de eventos e o servidor HTTP/SSE. RunningServer é { server, store, config, url, close }.
• loadOrCreateConfig(): TaskSwarmConfig, saveConfig(config): void, rotateToken(): string, generateToken(): string, getTaskSwarmHome(): string

Notificações (src/notify/index.ts)

• shouldNotify(status, previousStatus, blockedReason?, previousBlockedReason?): boolean — a regra de deduplicação. Chaveia no par (status, blocked_reason), não apenas no status, para que dois prompts de permissão diferentes em sequência notifiquem ambos.
• notify(event, previousStatus, previousBlockedReason, options?: NotifyOptions): void — dispara os canais habilitados. A notificação local do sistema operacional está sempre ativa; ntfy.sh só dispara quando options.ntfy.enabled é verdadeiro.

Adaptadores (src/adapters/)

• interface AgentAdapter { agentType: AgentType; name: string; toEventInput(raw): AgentEventInput } — o ponto de plugin que toda integração implementa
• class GenericAdapter implements AgentAdapter — o caminho de fallback do script wrapper
• class ClaudeCodeAdapter implements AgentAdapter, installClaudeCodeHooks(options: InstallHooksOptions): InstallHooksResult — a integração real de hooks do Claude Code

Incorporando o servidor diretamente em vez de executar taskswarm start, verificado funcionando contra o pacote compilado:

import { startServer, EventStore } from 'taskswarm-cli';

const running = await startServer({ logPath: null }); // in-memory only, no JSONL log
console.log(running.url); // http://127.0.0.1:4173/?token=...
console.log(running.store instanceof EventStore); // true
await running.close();

Tipos exportados junto com cada função: AgentEvent, AgentEventInput, AgentType, AgentStatus, SessionState, TaskSwarmConfig, NotifyOptions, RunningServer, StartServerOptions, HookInstallScope, InstallHooksOptions, InstallHooksResult.

A distribuição Python espelha a mesma superfície (snake_case em vez de camelCase, py.typed para verificadores de tipo), também verificada funcionando contra o pacote compilado:

from taskswarm import start_server, EventStore, TaskSwarmConfig

cfg = TaskSwarmConfig(token="local-dev", port=4175, host="127.0.0.1", ntfy={"enabled": False})
running = start_server(config=cfg, log_path=None)  # in-memory only, no JSONL log
print(running.url)  # http://127.0.0.1:4175/?token=local-dev
running.close()

Servidor MCP

A distribuição Python do TaskSwarm inclui um servidor Model Context Protocol, para que um agente compatível com MCP (Claude Desktop, Claude Code, um orquestrador) possa chamar o TaskSwarm diretamente como ferramenta, em vez de invocar a CLI e analisar texto.

pip install "taskswarm-cli[mcp]"

Ele expõe uma ferramenta, run, um wrapper genérico de subprocesso: passe a mesma lista de argumentos que você passaria na linha de comando, e ele invoca o binário taskswarm instalado, analisa o JSON resultante e o retorna. Cada modo de falha (binário ausente, erro de inicialização, timeout, saída não zero, saída não analisável) retorna como um dict simples {"error": ...} em vez de lançar exceção, para que uma chamada ruim não derrube o servidor.

run(args=["task", "list", "--json"])
# -> {"result": [{"id": "84c94aca-...", "title": "Fix flaky test", "repo": "/tmp/x", "created_at": "2026-08-09T17:37:00.949Z", "status": "unknown"}]}

Para registrá-lo com um cliente compatível com MCP, como o Claude Desktop, adicione-o à configuração de servidor do cliente:

{
  "mcpServers": {
    "taskswarm": {
      "command": "taskswarm-mcp"
    }
  }
}

Isso pressupõe que taskswarm-mcp já esteja em PATH (instalado via o extra mcp acima). Se você o instalou em outro lugar, substitua "command" pelo caminho completo para o script de console. Este servidor é atualmente apenas Python; a distribuição npm ainda não inclui um servidor MCP.

Como ele se compara

Verificado ao vivo contra os metadados da API do GitHub e o README de cada projeto, em 2026-08-03. Os números do próprio TaskSwarm são medidos, não estimados. Metodologia abaixo da tabela.

	TaskSwarm	paperclip	Vibe Kanban	Multica
Estrelas	pré-lançamento	75.547	27.656	43.690
Licença	MIT	MIT	Apache-2.0	Código-fonte disponível (Apache-2.0 modificado; restringe uso comercial hospedado)
Status de manutenção	ativo	ativo (commits hoje)	em descontinuação: empresa encerrada, README traz um aviso de encerramento, último commit em 2026-04-24, mais de 3 meses desatualizado no momento desta escrita	ativo (commits hoje)
Notificação push/desktop em mudança de estado	sim: notificação local do SO por padrão, ntfy.sh opcional	não encontrado no README	não encontrado no README	não encontrado no README
UI principal	tabela de status ao vivo (SSE)	quadro Kanban completo + organograma	quadro Kanban completo	quadro Kanban completo
Auto-hospedado, sem conta	sim	sim	sim (guia de auto-hospedagem, Docker)	sim (Docker)
Pegada de memória ociosa	~39 MB (medido)	não medido (fora do escopo)	não medido (fora do escopo)	não medido (fora do escopo)
Inicialização a frio (boot do servidor até acessível)	~0,19 s (medido)	não medido	não medido	não medido

O TaskSwarm não tenta superar nenhum desses três em quadro. paperclip e Multica são feitos para gerenciar uma lista inteira de agentes como um organograma, e o Vibe Kanban (enquanto durou) era um espaço de trabalho completo de planejamento e revisão. O TaskSwarm permanece focado: a única coisa que nenhum dos três oferece é um sinal de push quando uma sessão precisa de você, e esse é o produto inteiro aqui.

Metodologia de benchmark (para você reproduzir): medido em macOS 26.5.1, Apple Silicon (arm64), Node v24.4.0, npm 11.15.0, 2026-07-15.

• Cold start: inicialização do processo até um curl receber HTTP 200 da URL da página de status ao vivo, cronometrado com time.perf_counter(), com média em execuções repetidas (158 a 188 ms observados).
• Memória ociosa: ps -o rss no processo node dist/cli.js start em execução, alguns segundos após a inicialização sem sessões ativas (38,4 a 39,4 MB observados entre execuções).
• Latência de ingestão de evento até despacho de notificação: tempo de relógio de parede para uma requisição POST /events retornar 201, em 20 requisições com status: blocked (o caminho de código que chama sincronamente notify(), que inicia o processo de notificação do SO, antes de a resposta HTTP ser enviada). Mediana 3,1 ms, média 5,8 ms, p95 24,1 ms, n=20.
• Tempo total até o primeiro quadro (um usuário real de primeira viagem, git clone novo): npm install (2,05 s) mais npm run build (0,78 s) mais start até a página ao vivo ficar acessível (0,15 s), totalizando 2,99 s, em uma máquina com cache npm local aquecido. A meta era menos de 60 segundos; o resultado medido real é cerca de 20x abaixo disso.

Os números não listados para as outras três ferramentas não são placeholders estimados. Eles genuinamente não foram medidos, porque executar suas pilhas completas (Rust, PostgreSQL, Docker Compose) não estava no escopo desta passada. Suas contagens de estrelas, termos de licença e status de manutenção acima são fatos verificados ao vivo, não benchmarks.

Onde o TaskSwarm se encaixa no cenário mais amplo de 2026

paperclip, Vibe Kanban e Multica são os comparáveis mais próximos de quadro completo, mas não são o quadro inteiro. Executar vários agentes de codificação em paralelo se tornou um dos cantos mais ativos do código aberto em 2026: o próprio Relatório de Tendências de Codificação Agêntica 2026 da Anthropic nomeia a coordenação multiagente como uma das oito tendências que remodelam como o software é construído, e a OpenAI relatou que só o Codex ultrapassou 5 milhões de usuários semanais até junho de 2026. Uma onda inteira de UIs de orquestração foi lançada junto com esse crescimento. Aqui está onde o TaskSwarm se posiciona ao lado das ferramentas mais novas de agente paralelo que cobrem um fluxo de trabalho semelhante com uma forma diferente, verificado ao vivo em 2026-08-03:

Ferramenta	Estrelas	Licença	O que realmente é
TaskSwarm	pré-lançamento	MIT	Servidor de eventos somente com notificações; sem UI que você precise manter aberta
Claude Squad	8.231	AGPL-3.0	Gerenciador de terminal baseado em tmux para sessões de agentes paralelos, nenhum recurso de notificação encontrado em seu README
Superset	12.763	Elastic License 2.0 (código-fonte disponível)	Editor de código completo construído em torno de agentes paralelos; "seja notificado quando precisarem de atenção" segundo seu próprio README
Nimbalyst	1.394	MIT	Espaço de trabalho visual de desktop com um aplicativo complementar para celular que envia notificações; sincroniza por um servidor de colaboração hospedado
Paneflow	48	GPL-3.0	Espaço de trabalho nativo em Rust com fila de atenção e notificações de desktop
Conductor (Melty Labs)	código fechado, sem repositório público	proprietário	Painel de worktree exclusivo para macOS; não instalável via npm ou PyPI

Cada um desses oferece um lugar para você observar seus agentes trabalharem. O TaskSwarm é construído na suposição oposta: você não está observando, então ele envia notificações para você. Adjacente a isso, o protocolo padronizado de integração de agentes MCP cresceu para sua própria categoria mainstream no mesmo período, mais de 10.000 servidores MCP públicos ativos e mais de 97 milhões de downloads mensais de SDK, conforme a atualização do ecossistema de dezembro de 2025 da Anthropic -- a mesma mudança subjacente em direção a agentes que se conectam a pontos de integração padrão, que é a mesma razão pela qual o adaptador de script wrapper do TaskSwarm (taskswarm agent report-status) é deliberadamente agnóstico de protocolo, em vez de vinculado ao formato de hook de um agente específico.

O que é o TaskSwarm e por que ele existe

Executar um agente de codificação é uma conversa. Executar três ou quatro em paralelo vira um problema de alternância de abas: nada envia o estado para você, então você acaba monitorando terminais visualmente só para descobrir que um deles está parado em um prompt de permissão há dez minutos. O TaskSwarm existe para fechar essa lacuna: um sinal de push para o momento em que uma sessão realmente precisa de um humano.

O núcleo (servidor de eventos, CLI, página de status ao vivo, integração de hook do Claude Code) é licenciado sob MIT e gratuito para auto-hospedagem, para uso individual, para equipe, para qualquer coisa. Não há camada hospedada nem camada paga atualmente. O núcleo auto-hospedado é o produto inteiro agora.

Perguntas frequentes

Isso substitui meu quadro Kanban / Linear / GitHub Projects? Não. Esses rastreiam itens de trabalho que um humano planeja. O TaskSwarm rastreia o estado da sessão do agente ao vivo e informa no instante em que muda. Trabalho diferente.

Preciso especificamente do Claude Code? Não. taskswarm hooks install claude-code é a única integração nativa verificada atualmente. Codex, Cursor ou qualquer outra coisa funciona através do mesmo primitivo que o adaptador chama internamente: taskswarm agent report-status, chamável de qualquer script wrapper em torno de qualquer agente CLI.

Para onde vão meus dados? Para lugar nenhum, por padrão. O servidor vincula-se a 127.0.0.1, exige um token bearer para cada requisição e grava o estado em ~/.taskswarm/ (ou onde TASKSWARM_HOME apontar) no seu próprio disco. O único canal opcional que sai da sua máquina é o ntfy.sh, e ele fica desligado a menos que você o habilite explicitamente.

Isso vai começar a me cobrar depois? O núcleo licenciado sob MIT permanece gratuito. Tudo descrito neste README é o produto inteiro como existe hoje, não um teste ou uma camada limitada de algo maior. Por que não usar apenas tmux e observar os painéis? Esse é o status quo ao qual este projeto responde. Funciona até você estar executando mais de duas ou três sessões ao mesmo tempo, momento em que você gasta mais tempo monitorando painéis do que escrevendo código.

O que acontece se o servidor não estiver em execução quando eu chamar um comando? Comandos que precisam dele falham rapidamente com uma mensagem específica (could not reach TaskSwarm server at http://127.0.0.1:4173 -- is it running? (taskswarm start)), não um stack trace. task add e task list ainda funcionam sem o servidor; eles apenas pulam o enriquecimento de status em tempo real.

O que é TaskSwarm, exatamente? Um servidor de eventos auto-hospedado mais uma CLI. Sessões de agentes, ou um script wrapper em torno de qualquer agente, reportam status para ele (taskswarm agent report-status), e ele envia uma notificação local do sistema operacional e atualiza uma página de status SSE ao vivo no instante em que uma sessão fica blocked, needs-review, failed ou done. Ele não inicia, agenda ou executa agentes em si; apenas rastreia e envia estado para sessões que já estão em execução em outro lugar.

Posso usar TaskSwarm como uma biblioteca em vez da CLI? Sim. Ambas as distribuições exportam uma superfície programática real, não apenas uma entrada bin: import { startServer, EventStore } from 'taskswarm-cli' no npm, from taskswarm import start_server, EventStore no PyPI. Veja a referência da API de biblioteca acima para a lista completa de exportações e um exemplo funcional de cada uma.

Quais são os requisitos de plataforma e instalação? A compilação npm (taskswarm-cli) precisa do Node.js >=18.18.0, conforme o campo engines em package.json. A compilação PyPI (também taskswarm-cli) precisa do Python >=3.9, conforme pyproject.toml, que também declara Operating System :: OS Independent. Uma ressalva que é específica da plataforma na prática: a notificação push nativa do sistema operacional só dispara no macOS, via osascript (veja src/notify/os-notify.ts). No Linux e no Windows, o TaskSwarm recorre a uma linha de console mais um sino de terminal em vez de uma notificação do sistema, ainda local, ainda sem ntfy.sh, a menos que você opte por isso.

Como o TaskSwarm se compara a um concorrente específico, como Vibe Kanban ou paperclip? Veja as tabelas de comparação acima para o detalhamento completo, mas a versão curta: paperclip e Multica são construídos para executar e visualizar uma lista inteira de agentes como um organograma, e o Vibe Kanban era um espaço de trabalho completo de planejamento e revisão antes de a empresa por trás dele fechar (seu README carrega um banner de encerramento no momento em que escrevo). Nenhum dos três lista um recurso de notificação push/desktop em seu próprio README. O TaskSwarm pula o quadro inteiro e faz apenas uma coisa: envia um sinal no instante em que uma sessão precisa de você.

Posso usar o TaskSwarm em um produto comercial ou pago? Sim. O núcleo (servidor de eventos, CLI, página de status ao vivo, integração de hook do Claude Code) é licenciado sob MIT, sem restrição de campo de uso, então auto-hospedá-lo dentro de um produto comercial, um serviço pago ou uma ferramenta interna é aceitável. Esse é um ponto real de diferença em relação à Multica na tabela de comparação acima, que é distribuída sob uma licença Apache-2.0 modificada que restringe explicitamente o uso comercial hospedado.

Contribuindo

Issues e pull requests são bem-vindos. Antes de abrir um PR:

npm run lint
npm run typecheck
npm run test:coverage

Todos os três devem passar limpos. Para a distribuição Python, cd python && pip install -e ".[dev]" && pytest. Veja CONTRIBUTING.md para a lista de verificação completa cobrindo ambos os codebases.

Licença

MIT. Veja LICENSE. Livre para auto-hospedar, modificar e redistribuir, individualmente ou em equipe. Não existe camada hospedada ou paga nesta versão.