Docket

Docket

Uma lista que toda ferramenta de IA que você usa pode escrever — Claude Code, Codex, Cursor, Warp — em todos os projetos, antes que o trabalho valha um ticket. Local-first, auto-hospedável, sem conta SaaS.

_{Assista à demonstração de um minuto · baixe o mp4}

Início rápido

Você precisa de: Node.js 18+ e pelo menos um host MCP — Claude Code, Codex, Cursor, Windsurf, Claude Desktop, Zed ou Warp.

npx -y @pasichdev/docket setup

Isso configura todos os hosts encontrados nesta máquina e termina informando quais são. Em seguida, reinicie seu agente e peça "adicione um todo: comprar leite" — ele aparece em http://localhost:8787, um painel que iniciou sozinho no momento em que o agente conectou.

Quer apenas Claude Code, e nada escrito em qualquer outro lugar? claude mcp add docket -- npx -y @pasichdev/docket faz apenas essa parte. Outros hosts: Hosts suportados.

npm install -g @pasichdev/docket        # the hook runs a command, so it needs one on PATH
docket hook install                     # then: docket hook doctor

Por quê

Um pensamento que surge no meio da sessão vale ser capturado, mas não vale a cerimônia: um template do Notion, um formato de issue do GitLab, um id de ticket que você precisa inventar. Então hoje ele evapora. Docket é a camada abaixo de tudo isso — o trabalho chega aqui na velocidade que um agente consegue digitar, de qualquer ferramenta, em qualquer projeto, e se forma para Notion/GitLab/Obsidian quando merece.

Ninguém mais ocupa esse espaço, e não é acidente: a Anthropic não vai integrar Claude Code com Cursor, e a Cursor não vai integrar com Codex. Cada fornecedor otimiza seu próprio ciclo fechado. O espaço entre as ferramentas é estruturalmente de ninguém.

Uma lista, muitos projetos

Docket arquiva cada item sob o projeto em que foi capturado, automaticamente — resolvido a partir do remote git de onde o agente está rodando. Você nunca digita isso, e nenhum agente precisa lembrar.

~/work/backend      claude-code, codex   ─┐
~/side/tracker      claude-code          ─┼──▶  docket  ──▶  one list, three scopes
~/side/notes        codex, warp          ─┘

• todo_list em ~/work/backend mostra os itens abertos daquele projeto, não todos os três projetos — compacto, uma linha cada.
• O painel web tem um seletor de workspace com contagens de abertos por projeto.
• Itens sem contexto de projeto caem em Sem classificação e permanecem visíveis, nunca adivinhados.

Usar o remote do git em vez do caminho significa que o mesmo repositório clonado em ~/src/backend em um laptop e /work/backend em um desktop é um workspace — o que importa precisamente porque a sincronização existe. Ordem completa de resolução e a substituição .docket.json: docs/workspaces.md.

_{Regenere estes com node docs/assets/demo-seed.mjs — ele constrói o workspace que eles mostram, então eles permanecem uma imagem do painel real em vez de um encenado.}

Atualizando da versão 2.x

Leia isto antes de atualizar se você tiver itens existentes.

O 3.0 migra seu armazenamento do formato de dados v7 para v8 na primeira execução, automaticamente. A migração em si é segura e não é o risco. Fazer downgrade depois é.

O docket 2.3.1 grava o armazenamento a partir de sua própria forma v7: ele nunca ouviu falar dos campos que o v8 adiciona, então sua primeira gravação após uma reinstalação remove silenciosamente eles de cada item. Nada gera erro, e um re-upgrade posterior entrega novos números de sequência que não significam mais o que seus dispositivos pareados pensam que significam. O 2.3.1 está publicado e não pode ser corrigido, então o 3.0 se defende da única forma que pode — mantendo uma cópia do seu armazenamento pré-migração:

~/.docket/todos.v7-pre-upgrade.enc

Ele é gravado uma vez, antes da primeira gravação v8, e nunca é sobrescrito. A atualização imprime seu caminho na execução que o cria.

Para voltar ao 2.x, restaure-o primeiro:

docket restore --from-v7                     # puts the v7 store back; moves the v8 one aside
npm install -g @pasichdev/docket@2.3.1

Nessa ordem. restore --from-v7 não apaga nada — seu armazenamento v8 é renomeado para o lado, então você pode avançar novamente depois.

Se você preferir também uma cópia portátil, docket backup ./pre-v3.backup antes de atualizar fornece uma que inclui sua identidade e pares pareados.

Pontes, não substituições

Docket é deliberadamente não onde o trabalho vive para sempre. É onde o trabalho chega primeiro, antes que alguém saiba se merece um ticket. A maior parte não merece e é fechada manualmente; o resto se forma.

sourceUrl é a ponte em ambas as direções. Defina-o sempre que um item mapear para algo com uma URL — uma issue do GitLab, uma página do Notion, um link de compartilhamento do Obsidian, um thread do Slack, um PR do GitHub — e o cartão carrega um link clicável direto de volta para ele.

Por que não usar apenas GitHub Issues? Porque uma issue custa um título que você precisa formular para um público, um repositório que você precisa escolher, e labels que você precisa manter — e porque sua sessão do Cursor não pode escrever uma para você enquanto você está no meio de um pensamento em um projeto diferente. Docket custa uma frase, de qualquer ferramenta que você já tem aberta. Quando o item se mostra importante, ele vira uma issue, e sourceUrl lembra para onde foi.

Hosts suportados

Qualquer host MCP funciona — as ferramentas são idênticas em todos os lugares:

{
  "mcpServers": {
    "docket": { "command": "npx", "args": ["-y", "@pasichdev/docket"] }
  }
}

{
  "context_servers": {
    "docket": { "command": { "env": {}, "path": "npx", "args": ["-y", "@pasichdev/docket"] } }
  }
}

O único hook

Claude Code também recebe um hook SessionStart, e apenas esse:

docket hook install      # writes .claude/settings.json (--global for user-wide)
docket hook doctor       # proves it fires, and reports measured latency
docket hook uninstall    # removes only the entries docket owns

Quando uma sessão inicia, ele injeta os itens abertos naquele projeto — compactos, no máximo 7, abaixo de 120 tokens. Nada quando o projeto não tem nada aberto. Seu único trabalho é continuidade: você volta a um terminal e o fio já está lá.

Não quer? export DOCKET_HOOKS=off desativa imediatamente, sem editar nenhuma configuração ou desinstalar nada. docket hook doctor mede o round trip real e avisa se for lento o suficiente para notar.

Ele falha aberto, sempre. Servidor não rodando, requisição expirada, resposta malformada, DOCKET_HOOKS=off — cada um desses sai com 0 e não imprime nada. Uma ferramenta que degrada sua sessão quando a própria ferramenta está quebrada é desinstalada, e nesse ponto não ajuda ninguém. docket hook doctor executa o comando configurado de verdade e relata o que uma sessão realmente veria, então um hook que nunca dispara é visível em vez de meramente silencioso.

Sem PreToolUse, sem bloqueio, sem outros hosts — o único trabalho do hook nesta versão é continuidade, não imposição.

Orientação para agentes que não são Claude Code

As ferramentas funcionam em todos os lugares; a orientação é entregue como um plugin do Claude Code. Para qualquer outro agente, copie skills/docket/SKILL.md (tudo abaixo do frontmatter ---) para o arquivo que seu agente lê — AGENTS.md para Codex, .cursor/rules/docket.mdc para Cursor, .windsurfrules para Windsurf, CLAUDE.md para Claude Desktop, ou a configuração de instruções personalizadas do Warp.

/plugin marketplace add pasichDev/docket
/plugin install docket@docket

Ferramentas

Referência completa de campos e fluxo de trabalho: skills/docket/SKILL.md.

Resumos

Peça ao seu agente "faça um resumo" (ou "зроби дайджест"). A habilidade docket:digest lê seus merge requests, pull requests, tickets do Notion, commits locais e itens do docket, verifica cada status na fonte, e publica o resultado — que se torna a página inicial do painel: o que precisa de você, o que foi entregue, o que está em revisão, o que está travado, cada item linkado de volta para onde vive e a um clique de se tornar uma tarefa.

Docket nunca guarda uma credencial do GitLab, GitHub ou Notion: o agente as lê com os CLIs e servidores MCP que já tem, e o Docket só mantém o que escreveu — nesta máquina no Modo Local (sincronizado com dispositivos pareados), ou no Servidor Docket no Modo Auto-hospedado, compartilhado por cada cliente. Qualquer outra coisa que o agente possa alcançar — Jira, Linear ou Sentry através de seus servidores MCP, um cofre Obsidian, a pasta de docs de um projeto — pode ser adicionada como fonte, e o resumo pode ser dividido em grupos como trabalho, aprendizado e projetos paralelos. O que ler é local a cada máquina, em ~/.config/docket/digest.json (a habilidade docket:digest-setup escreve); os próprios resumos sincronizam com dispositivos pareados. Detalhes: docs/digests.md.

• O que mudou desde o resumo anterior é calculado quando é publicado — novos itens, mudanças de status, o que saiu — não deixado à memória do agente.
• Quem faz o quê: cada item pode nomear seu dono (você, um colega, o agente); Por pessoa transforma o resumo em próximos passos numerados por pessoa.
• Profundidade onde importa: itens rotineiros ficam em uma linha; bloqueados, com falha ou desatualizados carregam a análise do agente da causa real e do próximo passo.
• Entregue pelo número: diga a qualquer agente "pegue o 7" — digest_take dá a ele o briefing e uma tarefa reivindicada em seu nome; ele fecha a tarefa com o motivo.
• Visto esconde um item até seu status mudar; marcações sincronizam entre dispositivos.
• Seu para moldar: grupos, pessoas, predefinições ("resumo trabalho", "resumo semana"), verificações de ambiente, e-mail e chat via MCP, uma execução diária — e a habilidade mantém notas curtas sobre o que você continua corrigindo.

CLI

docket list [-w <project>] [--all]          What's open, scoped like the MCP default
docket workspaces                           Projects, with open counts and last activity
docket sessions                             Agent sessions open right now, and where
docket stats | export | import              Inspection and round-tripping
docket hook install | uninstall | doctor    Claude Code SessionStart hook
docket serve | pair | devices | status      Self-hosted server & devices
docket backend use <url> | localize         Switch deployment mode
docket backup <file> | restore <file>       Encrypted full-device backup
docket web                                  Ensure the Web UI is running
docket check-update | update                Version management

docket help imprime a lista canônica, sempre atual. Referência completa: docs/cli.md.

Modos de implantação

Ambos os modos instalam a partir do mesmo pacote e expõem as mesmas ferramentas MCP. Configuração completa de self-hosted e o que ela deliberadamente não faz: docs/self-hosting.md.

A sincronização P2P está obsoleta a partir da v3.0. Ela ainda funciona, e nada é removido nesta versão — mas seu intervalo de pull de 15 segundos significa que as reivindicações são advisory através dela, então não pode entregar uma garantia atômica. O Modo Self-hosted é o caminho multi-máquina suportado. Veja docs/p2p-sync.md.

Interface Web

Um painel de leitura/escrita em tempo real — http://localhost:8787 por padrão no Modo Local (substituível com DOCKET_WEB_PORT), ou a URL do próprio Docket Server no Modo Self-hosted. A página inicial (/) mostra o resumo mais recente ao lado da lista de tarefas de relance; a lista em si está em /tasks. Seletor de espaços de trabalho com contagens de abertos por projeto, um painel de sessões ativas, tema claro/escuro, busca, ordenação, edição inline, desfazer exclusão, layout responsivo para mobile.

No Modo Local, ele inicia sozinho: o primeiro cliente MCP a conectar o inicia em segundo plano de forma destacada se nada estiver ouvindo ainda. Atualizações são enviadas ao vivo via Server-Sent Events (/api/events), sem polling.

Abrir a partir de outro dispositivo na sua LAN (celular, tablet) requer uma aprovação explícita do Viewer Gate da máquina host primeiro — veja Segurança.

Segurança

O Docket tem quatro modelos de ameaça separados (armazenamento local criptografado, sincronização P2P, o Viewer Gate da LAN, e tráfego cliente/servidor self-hosted) — uma garantia de um não se aplica a outro. O básico:

• Em repouso: todos.json.enc e history.json.enc são criptografados com AES-256-GCM usando uma chave gerada localmente — protege contra exposição acidental, não contra alguém com acesso de leitura à sua própria conta de usuário.
• Sincronização P2P: X25519 ECDH + segredos por par derivados de HKDF, requisições assinadas com HMAC com proteção contra replay, respostas criptografadas com AES-256-GCM.
• Viewer Gate da LAN: qualquer navegador que não seja a máquina host precisa de aprovação humana explícita antes de abrir o painel; esse tráfego local em si é HTTP simples, não TLS (tradeoff documentado, não uma omissão).
• Modo self-hosted: assinaturas HMAC por dispositivo com proteção contra replay por timestamp+nonce. O servidor não é criptografado de ponta a ponta contra seu próprio operador.
• Atualizações: cada versão é publicada com proveniência npm respaldada por Sigstore, verificável com npm audit signatures.

Modelo de ameaça completo, primitivas exatas e limitações: docs/security.md.

Dados e criptografia

Dados autoritativos vivem nesta máquina (~/.docket) no Modo Local, ou no Docket Server no Modo Self-hosted — de qualquer forma, em infraestrutura que você controla, nunca uma conta hospedada.

• todos.json.enc — o armazenamento, criptografado com AES-256-GCM
• history.json.enc — o log de auditoria completo, mantido fora do caminho de escrita do armazenamento
• digests.json.enc — resumos, criptografados com AES-256-GCM, com seu próprio cursor de sincronização
• key — uma chave de 256 bits gerada localmente, chmod 600
• device.json — o id desta máquina, nome e par de chaves de identidade X25519
• peers.json.enc — dispositivos P2P pareados e seus segredos de sincronização derivados
• sessions.json — quais sessões de agente estão abertas agora (simples, apenas local, nunca sincronizado; contém metadados de processo, não conteúdo)

Defina DOCKET_DATA_DIR para realocar o diretório; a inicialização se recusa a dividir silenciosamente um armazenamento existente em vez de adivinhar.

Backup e atualização

docket backup <file> empacota todo o diretório de dados em um único arquivo protegido por senha (AES-256-GCM, chave derivada de scrypt); docket restore o escreve de volta, renomeando o que está no disco de lado em vez de sobrescrever.

docket check-update   # read-only — reports current vs. latest
docket update         # checks, confirms, installs, self-tests, rolls back on failure

Testes

npm test

Executa a suíte completa de node:test — entrega e paginação de sincronização, o bloqueio de arquivo entre processos sob contenção real, resolução e escopo de espaços de trabalho, o registro de sessões, orçamentos de tokens voltados a agentes, e o comportamento fail-open do hook.

Licença

MIT — veja LICENSE.