Docket

Docket

Una lista que cada herramienta de IA que uses puede escribir — Claude Code, Codex, Cursor, Warp — en todos tus proyectos, antes de que el trabajo merezca un ticket. Local-first, autoalojable, sin cuenta SaaS.

_{Mira la demo de un minuto · descarga el mp4}

Inicio rápido

Necesitas: Node.js 18+ y al menos un host MCP — Claude Code, Codex, Cursor, Windsurf, Claude Desktop, Zed o Warp.

npx -y @pasichdev/docket setup

Eso configura cada host que encuentre en esta máquina y termina diciéndote cuáles son. Luego reinicia tu agente y pídele "agrega un todo: compra leche" — aparecerá en http://localhost:8787, un panel que se inició solo en el momento en que el agente se conectó.

¿Solo quieres Claude Code, y nada escrito en ningún otro lugar? claude mcp add docket -- npx -y @pasichdev/docket hace solo esa parte. Otros hosts: Hosts compatibles.

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é

Un pensamiento que aparece a mitad de sesión vale la pena capturarlo pero no vale la pena la ceremonia: una plantilla de Notion, un formato de issue de GitLab, un id de ticket que tienes que inventar. Así que hoy se evapora. Docket es la capa debajo de todo eso — el trabajo aterriza aquí a la velocidad a la que un agente puede escribir, desde cualquier herramienta, en cualquier proyecto, y se gradúa a Notion/GitLab/Obsidian cuando se lo ha ganado.

Nadie más ocupa este espacio, y no es un accidente: Anthropic no integrará Claude Code con Cursor, y Cursor no se integrará con Codex. Cada proveedor optimiza su propio bucle cerrado. El espacio entre las herramientas es estructuralmente de nadie.

Una lista, muchos proyectos

Docket archiva cada elemento bajo el proyecto en el que fue capturado, automáticamente — resuelto desde el remoto git de donde sea que el agente esté ejecutándose. Nunca lo escribes tú, y ningún agente tiene que recordarlo.

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

• todo_list en ~/work/backend muestra los elementos abiertos de ese proyecto, no todos los tres proyectos — compacto, una línea cada uno.
• El panel web tiene un selector de espacio de trabajo con conteos de abiertos por proyecto.
• Los elementos sin contexto de proyecto aterrizan bajo Sin clasificar y permanecen visibles, nunca adivinados.

Usar el remoto de git en lugar de la ruta significa que el mismo repositorio clonado en ~/src/backend en una laptop y /work/backend en un escritorio es un espacio de trabajo — lo cual importa precisamente porque la sincronización existe. Orden completo de resolución y la anulación de .docket.json: docs/workspaces.md.

_{Regenera estos con node docs/assets/demo-seed.mjs — construye el espacio de trabajo que muestran, así que siguen siendo una imagen del panel real en lugar de uno escenificado.}

Actualizando desde 2.x

Lee esto antes de actualizar si tienes elementos existentes.

3.0 migra tu almacén del formato de datos v7 a v8 en la primera ejecución, automáticamente. La migración en sí es segura y no es el riesgo. Bajar de versión después sí lo es.

docket 2.3.1 escribe el almacén desde su propia forma v7: nunca ha oído hablar de los campos que v8 agrega, así que su primera escritura después de una reinstalación silenciosamente los elimina de cada elemento. Nada da error, y una re-actualización posterior entrega números de secuencia nuevos que ya no significan lo que tus dispositivos emparejados creen que significan. 2.3.1 está publicado y no se puede parchear, así que 3.0 se defiende de la única manera que puede — manteniendo una copia de tu almacén previo a la migración:

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

Se escribe una vez, antes de la primera escritura v8, y nunca se sobrescribe. La actualización imprime su ruta en la ejecución que la crea.

Para volver a 2.x, restáuralo primero:

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

En ese orden. restore --from-v7 no borra nada — tu almacén v8 se renombra a un lado, así que puedes avanzar de nuevo más tarde.

Si prefieres tener también una copia portátil, docket backup ./pre-v3.backup antes de actualizar te da una que incluye tu identidad y pares emparejados.

Puentes, no reemplazos

Docket deliberadamente no es donde el trabajo vive para siempre. Es donde el trabajo aterriza primero, antes de que alguien sepa si merece un ticket. La mayor parte no lo merece y se cierra a mano; el resto se gradúa.

sourceUrl es el puente en ambas direcciones. Establécelo cuando un elemento se mapee a algo con una URL — un issue de GitLab, una página de Notion, un enlace compartido de Obsidian, un hilo de Slack, un PR de GitHub — y la tarjeta lleva un enlace clicable directo de vuelta a él.

¿Por qué no usar simplemente GitHub Issues? Porque un issue cuesta un título que tienes que redactar para una audiencia, un repositorio que tienes que elegir, y etiquetas que tienes que mantener — y porque tu sesión de Cursor no puede escribir uno por ti mientras estás a mitad de pensamiento en un proyecto diferente. Docket cuesta una oración, desde la herramienta que ya tengas abierta. Cuando el elemento resulta importar, se convierte en un issue, y sourceUrl recuerda a dónde fue.

Hosts compatibles

Cualquier host MCP funciona — las herramientas son idénticas en todas partes:

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

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

El único hook

Claude Code además recibe un hook de SessionStart, y solo ese:

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

Cuando una sesión comienza, inyecta los elementos abiertos en ese proyecto — compacto, como máximo 7, bajo 120 tokens. Nada en absoluto cuando el proyecto no tiene nada abierto. Todo su trabajo es continuidad: vuelves a una terminal y el hilo ya está ahí.

¿No lo quieres? export DOCKET_HOOKS=off lo desactiva inmediatamente, sin editar ninguna configuración ni desinstalar nada. docket hook doctor mide el viaje de ida y vuelta real y lo dice si es lo suficientemente lento como para notarlo.

Falla abierto, siempre. Servidor no ejecutándose, solicitud con tiempo agotado, respuesta malformada, DOCKET_HOOKS=off — cada uno de esos sale con 0 e imprime nada. Una herramienta que degrada tu sesión cuando la herramienta misma está rota se desinstala, momento en el cual no ayuda a nadie. docket hook doctor ejecuta el comando configurado de verdad e informa lo que una sesión vería realmente, así que un hook que nunca se dispara es visible en lugar de meramente silencioso.

Sin PreToolUse, sin bloqueo, sin otros hosts — el único trabajo del hook en esta versión es continuidad, no aplicación.

Orientación para agentes que no son Claude Code

Las herramientas funcionan en todas partes; la orientación se envía como un plugin de Claude Code. Para cualquier otro agente, copia skills/docket/SKILL.md (todo debajo del frontmatter de ---) en el archivo que tu agente lea — AGENTS.md para Codex, .cursor/rules/docket.mdc para Cursor, .windsurfrules para Windsurf, CLAUDE.md para Claude Desktop, o la configuración de instrucciones personalizadas de Warp.

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

Herramientas

Referencia completa de campos y flujo de trabajo: skills/docket/SKILL.md.

Resúmenes

Pídele a tu agente "haz un resumen" (o "зроби дайджест"). La habilidad docket:digest lee tus merge requests, pull requests, tickets de Notion, commits locales y elementos de docket, verifica cada estado en la fuente, y publica el resultado — que se convierte en la página de inicio del panel: qué te necesita, qué se envió, qué está en revisión, qué está atascado, cada elemento enlazado de vuelta a donde vive y a un clic de convertirse en una tarea.

Docket nunca guarda una credencial de GitLab, GitHub o Notion: el agente las lee con las CLI y servidores MCP que ya tiene, y Docket solo guarda lo que escribió — en esta máquina en Modo Local (sincronizado a dispositivos emparejados), o en el Servidor Docket en Modo Autoalojado, compartido por cada cliente. Cualquier otra cosa que el agente pueda alcanzar — Jira, Linear o Sentry a través de sus servidores MCP, una bóveda de Obsidian, la carpeta de documentos de un proyecto — se puede agregar como fuente, y el resumen se puede dividir en grupos como trabajo, aprendizaje y proyectos secundarios. Qué leer es local a cada máquina, en ~/.config/docket/digest.json (la habilidad docket:digest-setup lo escribe); los resúmenes mismos se sincronizan a dispositivos emparejados. Detalles: docs/digests.md.

• Qué cambió desde el resumen anterior se calcula cuando se publica — elementos nuevos, cambios de estado, qué se eliminó — no se deja a la memoria del agente.
• Quién hace qué: cada elemento puede nombrar a su dueño (tú, un compañero, el agente); Por persona convierte el resumen en próximos pasos numerados por persona.
• Profundidad donde importa: los elementos rutinarios permanecen en una línea; los bloqueados, fallidos o desactualizados llevan el análisis del agente de la causa real y el próximo paso.
• Entrégalo por número: dile a cualquier agente "toma 7" — digest_take le da el breve y una tarea reclamada en su nombre; cierra la tarea con la razón.
• Visto oculta un elemento hasta que su estado cambie; las marcas se sincronizan entre dispositivos.
• Tuyo para dar forma: grupos, personas, preajustes ("resumen trabajo", "resumen semana"), verificaciones de entorno, correo y chat vía MCP, una ejecución diaria — y la habilidad mantiene notas cortas sobre lo que sigues corrigiendo.

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 la lista canónica, siempre actual. Referencia completa: docs/cli.md.

Modos de implementación

Ambos modos se instalan desde el mismo paquete y exponen las mismas herramientas MCP. Configuración completa de autoalojamiento y lo que deliberadamente no hace: docs/self-hosting.md.

La sincronización P2P está obsoleta a partir de v3.0. Sigue funcionando, y nada se elimina en esta versión — pero su intervalo de extracción de 15 segundos significa que las reclamaciones son consultivas a través de ella, por lo que no puede ofrecer una garantía atómica. El modo Autoalojado es la ruta multi-máquina compatible. Ver docs/p2p-sync.md.

Interfaz web

Un panel de lectura/escritura en tiempo real — http://localhost:8787 por defecto en modo Local (anular con DOCKET_WEB_PORT), o la URL propia del servidor Docket en modo Autoalojado. La página de inicio (/) muestra el último resumen junto a la lista de tareas de un vistazo; la lista en sí está en /tasks. Conmutador de espacios de trabajo con recuentos de apertura por proyecto, un panel de sesiones activas, tema claro/oscuro, búsqueda, ordenación, edición en línea, deshacer eliminación, diseño móvil adaptable.

En modo Local se inicia solo: el primer cliente MCP que se conecta lo lanza en segundo plano de forma separada si nada está escuchando aún. Las actualizaciones se transmiten en vivo a través de Eventos enviados por el servidor (/api/events), sin sondeo.

Abrirlo desde otro dispositivo en tu LAN (teléfono, tableta) requiere una aprobación explícita de Puerta de Visor desde la máquina anfitriona primero — ver Seguridad.

Seguridad

Docket tiene cuatro modelos de amenaza separados (almacenamiento local cifrado, sincronización P2P, la Puerta de Visor LAN, y tráfico cliente/servidor autoalojado) — una garantía de uno no se aplica a otro. Lo básico:

• En reposo: todos.json.enc y history.json.enc están cifrados con AES-256-GCM con una clave generada localmente — protege contra exposición accidental, no contra alguien con acceso de lectura a tu propia cuenta de usuario.
• Sincronización P2P: X25519 ECDH + secretos por par derivados de HKDF, solicitudes firmadas con HMAC con protección de repetición, respuestas cifradas con AES-256-GCM.
• Puerta de Visor LAN: cualquier navegador que no sea la máquina anfitriona necesita aprobación humana explícita antes de poder abrir el panel; ese tráfico local en sí es HTTP simple, no TLS (compensación documentada, no un descuido).
• Modo autoalojado: firmas HMAC por dispositivo con protección de repetición de marca de tiempo + nonce. El servidor no está cifrado de extremo a extremo contra su propio operador.
• Actualizaciones: cada versión se publica con procedencia npm respaldada por Sigstore, verificable con npm audit signatures.

Modelo de amenaza completo, primitivas exactas y limitaciones: docs/security.md.

Datos y cifrado

Los datos autoritativos viven en esta máquina (~/.docket) en modo Local, o en el servidor Docket en modo Autoalojado — de cualquier manera en infraestructura que controlas, nunca una cuenta alojada.

• todos.json.enc — el almacén, cifrado con AES-256-GCM
• history.json.enc — el registro de auditoría completo, mantenido fuera de la ruta de escritura del almacén
• digests.json.enc — resúmenes, cifrados con AES-256-GCM, con su propio cursor de sincronización
• key — una clave de 256 bits generada localmente, chmod 600
• device.json — el id de esta máquina, nombre y par de claves de identidad X25519
• peers.json.enc — dispositivos P2P emparejados y sus secretos de sincronización derivados
• sessions.json — qué sesiones de agente están abiertas ahora mismo (simple, solo local, nunca sincronizado; contiene metadatos de proceso, no contenido)

Establece DOCKET_DATA_DIR para reubicar el directorio; el inicio se niega a dividir silenciosamente un almacén existente en lugar de adivinar.

Copia de seguridad y actualización

docket backup <file> agrupa todo el directorio de datos en un archivo protegido por contraseña (AES-256-GCM, clave derivada de scrypt); docket restore lo escribe de vuelta, renombrando lo que está en disco a un lado en lugar de sobrescribirlo.

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

Pruebas

npm test

Ejecuta la suite completa de node:test — entrega y paginación de sincronización, el bloqueo de archivos entre procesos bajo contención real, resolución y alcance de espacios de trabajo, el registro de sesiones, presupuestos de tokens orientados a agentes, y el comportamiento de fallo abierto del gancho.

Licencia

MIT — ver LICENCIA.