Waymark

waymark: marca que señala el camino en una ruta.

Réplica abierta de Devin Codemaps para cualquier harness agéntico: mapas jerárquicos, narrados y anclados a líneas de cómo se ejecuta el código (trazas → nodos numerados 1a, 1b… → archivo:línea), con una historia holística, guías Motivation/Details por traza, una explicación tipo storytelling por nodo, un visor de código con los archivos embebidos y un diagrama interactivo. Funciona en Claude Code, Codex CLI / IDE / desktop y cualquier cliente MCP.

┌──────── harness (Claude Code, Codex CLI/desktop, Cursor, Agent SDK, CI…) ────────┐
│  agente "waymark" (subagente / skill)  ── explora en solo-lectura ──┐            │
└─────────────────────────────────────────────────────────────────────┼────────────┘
                               MCP (stdio)                            │
┌─ waymark-mcp ───────────────────────────────────────────────────────▼────────────┐
│ waymark_start → waymark_create ─► normalizar ─► ANCLAR contra el código real      │
│                                     (líneas movidas, archivos renombrados)        │
│ resource waymark://<id>  (@-mention)        waymark_verify (drift / CI)           │
└────────────► .waymark/<id>.json  +  .waymark/<id>.html (visor) ◄─────────────────┘

Paridad con Devin Codemaps

Diferencias: no hay panel nativo en el IDE (el visor es HTML + links al editor) y el "historial de navegación" se aproxima con git.

Related MCP server: gbrain-code

Instalación

Opción recomendada: plugin de Claude Code (sin clonar nada)

/plugin install waymark --marketplace h0w4r/waymark

(En versiones anteriores a 2.1.275: /plugin marketplace add h0w4r/waymark y luego /plugin install waymark@waymark.)

El plugin trae todo empaquetado (servidor MCP, CLI y hooks en plugin/dist/waymark.mjs, sin node_modules), la skill /waymark y el subagente. Se actualiza con /plugin marketplace update waymark (o con auto-update). Usa el plugin o la instalación desde el clon, no ambos (duplicarías servidor y hooks).

Desde el clon (desarrollo, Codex, otros harnesses)

git clone https://github.com/h0w4r/waymark.git
cd waymark && npm install
npm link            # opcional: deja `waymark` y `waymark-mcp` en el PATH

En el repo donde quieras usarlo:

waymark install --target <ruta-del-repo>        # o: node <waymark>/src/cli.js install …

Escribe (respetando archivos que no son suyos y sin duplicar en reinstalaciones):

Flags: --no-claude, --no-codex, --no-agents-md, --global-bin (usa el bin waymark-mcp tras npm link), --claude-global, --codex-global, --global (ambos).

¿No ves /waymark? La instalación por defecto es por proyecto: sólo aparece en el repo donde corriste install (y en la CLI el servidor de .mcp.json queda pending approval hasta que lo apruebas). Para tenerlo en todos tus proyectos usa el modo global.

Claude Code (global)

waymark install --claude-global

Registra el servidor con claude mcp add -s user waymark … (disponible en todos los proyectos, sin aprobación por repo), copia la skill y el subagente a ~/.claude/skills/waymark y ~/.claude/agents/waymark.md, y añade los hooks a ~/.claude/settings.json (con backup, sin tocar tus otros hooks; --no-hooks para omitirlos). Abre una sesión nueva y escribe /waymark.

Hooks (los mapas como memoria del agente):

Nunca bloquean la herramienta y fallan en silencio.

Extensión de VS Code (también Cursor / Windsurf)

waymark install --vscode      # empaqueta vscode/ como VSIX y lo instala con `code`

• Vista Waymark en la Activity Bar: mapa → traza → nodo (marca los nodos a revisar).

• Marcas en el margen (1a, 2b… con el color de la traza) y hover con la explicación.

• CodeLens sobre cada línea anclada del mapa activo: 2b · descripción · Explain · ← prev · next →.

• Alt+] / Alt+[ recorren los nodos del mapa activo.

• Visor embebido sincronizado en ambos sentidos (nodo → editor, cursor → nodo).

• Historial de navegación (en .waymark/.local/, ignorado por git) que alimenta las sugerencias de /waymark.

• Comandos que lanzan claude "/waymark …" (crear, añadir storytelling, refrescar explicaciones, verificar).

Instalar y actualizar (sin agente)

Waymark tiene dos piezas que se actualizan distinto:

Opción A — un solo comando desde el clon (MCP, skill, hooks y extensión):

cd <clon-de-waymark>
npm run update          # = waymark update --claude-global --vscode

waymark update hace git pull --ff-only, corre npm ci si cambió el lockfile, reinstala la skill/subagente/hooks de Claude Code y empaqueta e instala la extensión. Se niega a actualizar si tienes cambios sin commitear en el clon.

Opción B — sólo la extensión, desde el clon:

npm run vscode:install  # empaqueta vscode/ y ejecuta code --install-extension <vsix> --force

Opción C — sin clonar nada, desde GitHub Releases:

1. Descarga waymark-vscode-<versión>.vsix de la página de Releases.

2. En VS Code: vista Extensions → menú … → Install from VSIX… → elige el archivo. O en una terminal:

   code --install-extension waymark-vscode-0.2.0.vsix --force

   (Cursor: cursor --install-extension …; Windsurf: windsurf --install-extension ….)

3. Developer: Reload Window.

Opción D — automática: la extensión consulta GitHub Releases una vez al día; si hay una versión más nueva muestra "Waymark X is available" → Install → Reload. También a mano con Waymark: Check for updates. Se desactiva con waymark.updates.check: false.

Desinstalar: code --uninstall-extension h0w4r.waymark-vscode.

Canales de distribución

Cada secreto se agrega en GitHub → Settings › Secrets and variables › Actions; el siguiente tag publica en ese canal automáticamente.

Publicar una versión nueva (mantenedores)

npm run version:set -- 0.3.0           # versión en package.json, vscode, servidor MCP y plugin (y reconstruye plugin/dist)
git commit -am "Release v0.3.0"
git tag v0.3.0
git push && git push origin v0.3.0

El workflow release corre los tests, comprueba que las versiones coinciden con el tag, empaqueta el .vsix y crea el GitHub Release con el archivo adjunto. A partir de ahí la opción D lo ofrece a todas las extensiones instaladas.

Codex CLI, IDE y desktop

Los tres comparten ~/.codex/config.toml y además leen .codex/config.toml del proyecto solo si el proyecto es de confianza (Codex lo pregunta al abrir la carpeta).

• Por proyecto (lo que hace install): abre la carpeta en Codex y acepta "trust". Usa $waymark <tema> o /skills.

• Global (recomendado para Codex desktop, sirve en cualquier workspace):

  waymark install --target <repo> --codex-global

  Añade un bloque gestionado [mcp_servers.waymark] al final de ~/.codex/config.toml (con backup previo; no reformatea el resto del archivo, a diferencia de codex mcp add) y copia la skill a ~/.agents/skills/waymark. El servidor resuelve el repo abierto solo (workspace del cliente vía MCP roots, cwd, o el argumento root).

• Subagente: requiere [features] multi_agent = true en tu config de Codex; sin eso la skill hace el trabajo en el hilo principal.

• Las tools de solo lectura declaran readOnlyHint; si quieres que Codex no pregunte por las de escritura, añade default_tools_approval_mode = "approve" al bloque [mcp_servers.waymark].

Otros harnesses

• Cursor / Windsurf / VS Code: mismo bloque mcpServers de .mcp.json en su archivo de MCP.

• Claude Agent SDK: mcpServers: { waymark: { command: "node", args: [".../src/mcp.js"] } } y el prompt MCP create_waymark o la tool waymark_start.

• Sin MCP: waymark guide "<tema>" imprime el procedimiento; el agente escribe el JSON y ejecuta waymark create map.json (exit 2 si hay anclas sin verificar).

Skill portable using-waymark (cualquier agente, cualquier harness)

skills/using-waymark es el playbook que un agente sigue por iniciativa propia mientras trabaja: antes de editar un archivo cubierto por un mapa, al depurar, al revisar un PR, al refactorizar, al terminar un cambio (verificar/refrescar), al hacer onboarding o un hand-off. La skill waymark sigue siendo la de los comandos que pide el usuario (/waymark <tema>, list, check…).

• SKILL.md: tabla situación → acción, cómo interpretar las señales de confianza (anclas, drift, fact-check, ejecución) y las reglas.

• references/: playbooks paso a paso (workflows.md), todas las tools MCP con su gemelo CLI (tools.md), el formato del mapa (map-format.md) y cómo conectarla en cada harness (harnesses.md).

• scripts/wm.mjs: wrapper del CLI para harnesses sin MCP (node <skill>/scripts/wm.mjs for-file src/app.ts 42). Resuelve el CLI en este orden: WAYMARK_CLI, wm.config.json (lo escribe el instalador), el bundle del plugin, el clon del repo, waymark en el PATH y por último npx github:h0w4r/waymark. wm.mjs where muestra cuál usó.

Se instala sola con --claude-global (~/.claude/skills/using-waymark), --codex-global (~/.agents/skills/using-waymark), la instalación por proyecto (.claude/skills, .agents/skills) y el plugin. Para cualquier otro harness que lea skills de una carpeta:

node src/cli.js install --no-claude --no-codex --no-agents-md --skill-dir <carpeta-de-skills-del-harness>

Si el harness no soporta skills, pega SKILL.md en su archivo de reglas (AGENTS.md, .cursor/rules, etc.) y deja el resto de la carpeta accesible.

Uso

CLI:

waymark generate "how does auth work?" --open                 # claude si está instalado, si no codex
waymark generate "how does auth work?" --engine codex -m <modelo> --mode fast
waymark enrich <id> --open                                     # añade story, Motivation/Details y explicaciones
waymark annotate <id> patch.json                               # edita la prosa sin re-anclar ("reviewed": ["2b"] confirma sin cambios)
waymark refresh <id>                                           # el agente reescribe sólo lo que quedó desactualizado
waymark lint [id] [--strict]                                   # [refs] rotas, nodos no citados, narrativa faltante…
waymark for-file src/x.ts [linea]                              # qué mapas/trazas/nodos cubren un archivo
waymark list
waymark show <id> --format compact|markdown|json|mermaid
waymark verify [id] --fix [--strict] [--strict-narrative]
waymark render <id> --open
waymark suggest

generate --engine codex ejecuta codex exec --sandbox read-only inyectando el servidor con -c mcp_servers.waymark.* (no toca tu config global); el agente sólo lee y el servidor MCP —fuera del sandbox— escribe en .waymark/.

Verificar las afirmaciones (fact-check)

/waymark check <id> (o waymark check <id>) lanza un agente distinto del que escribió el mapa, en modo escéptico: abre el código de cada nodo, contrasta cada afirmación (qué llama a qué, datos, condiciones, efectos), corrige la prosa errónea y registra un veredicto por nodo, guía y historia: ✓ supported, ◑ partial (no verificable desde el código) o ✗ unsupported. El veredicto queda atado al código y a la prosa que juzgó: si cualquiera cambia, pasa a "sin verificar". unsupported es error de lint. En el visor: insignias ✓/◑/✗ y chip "N/M verified".

Generación en paralelo

waymark generate "<tema>" --parallel [--jobs 4] [--coordinator-model sonnet]: un agente planifica las trazas, uno por traza las construye a la vez (cada uno con su propio contexto, así cada traza sale más profunda) y un editor final escribe la historia y los enlaces. En Claude Code la skill hace lo mismo con subagentes en paralelo (waymark_plan → waymark_add_trace × N → waymark_finalize). En mapas medianos el tiempo total es similar al secuencial (plan + cierre ≈ 2 min fijos); la ganancia es profundidad y que mapas grandes no saturan el contexto de un solo agente.

Impacto de cambios y PRs

waymark diff                       # cambios sin commitear
waymark diff origin/main --range   # una rama o PR
waymark install --pr-action        # .github/workflows/waymark-pr.yml en tu repo

Cruza las líneas cambiadas con el bloque de código de cada nodo y lista nodos tocados, anclas rotas y prosa a revisar. La GitHub Action publica (y actualiza) un comentario en cada PR. --fail-on touched|broken|drift para usarlo como gate.

Notas humanas

Conocimiento del equipo que la IA no reescribe nunca: waymark note <id> <nodo> "texto", botón + Note en el visor, Waymark: Add team note / hover en VS Code, o waymark_note. Sobreviven a que el agente regenere el mapa y aparecen en el contexto que reciben los agentes (incluidos los hooks).

Verificado por ejecución

waymark exec <id> -- npm test               # Node/JS: cobertura V8 (incluye procesos hijos)
waymark exec <id> --lcov coverage/lcov.info # cualquier lenguaje con LCOV (Jest, coverage.py, JaCoCo…)

Marca qué nodos se ejecutaron realmente en los tests (▶) y cuáles no (○). Igual que los veredictos, el resultado caduca si el código del nodo cambia.

Mapa de mapas

/waymark overview o waymark generate "<tema>" --overview: un mapa de arquitectura (kind: "overview") cuyos nodos enlazan (mapRef) a los mapas detallados; abrirlos es un clic (o doble clic en el diagrama). .waymark/index.html lista todos los mapas con su salud (verificados, ejecutados, a revisar), con el overview primero.

CI (detectar mapas desactualizados)

- run: npx waymark verify --strict   # falla si algún nodo ya no existe o se movió
- run: npx waymark lint             # falla si la prosa cita nodos inexistentes

Narrativa al día (drift narrativo)

Cada nodo guarda el hash del bloque de código del que habla (la línea + su cuerpo por indentación, o unas líneas hermanas si es una sentencia). Mover código no cuenta; editarlo sí. verify reporta los nodos, guías de traza e historia escritos para código que ya cambió; el visor y la extensión los marcan con ◔; waymark refresh <id> / waymark_refresh hace que el agente reescriba sólo eso (o lo confirme con reviewed).

Herramientas MCP

Todas aceptan root opcional. Estados de ancla: ok, moved, relocated (archivo renombrado), fuzzy (revisar), unresolved, missing. Las rutas fuera del repo se rechazan.

Formato

Ver src/schema.js y el ejemplo en src/guide.js:

{
  "title": "...", "query": "...", "language": "es",
  "description": "resumen de 2-3 frases que cita [1a], [2b, 2c]",
  "story": "historia holística en markdown (problema → recorrido → cómo encaja → takeaways)",
  "traces": [{
    "id": "1", "title": "...", "description": "una frase", "diagramTitle": "Título del árbol",
    "motivation": "por qué existe esta parte (markdown)",
    "details": "recorrido narrado que cita cada nodo [1a] (markdown)",
    "locations": [{ "id": "1a", "title": "≤ 5 palabras", "description": "una frase ≤ 15 palabras",
                    "explanation": "3-6 frases tipo storytelling (markdown)",
                    "path": "src/x.ts", "lineNumber": 42, "lineContent": "exact line text", "symbol": "fn" }],
    "tree": [{ "ref": "1a", "children": [{ "label": "paso intermedio" }, { "ref": "1b", "via": "devuelve el token" }] }]
  }],
  "links": [{ "from": "1b", "to": "2a", "label": "..." }]
}

Se recomienda commitear .waymark/ para compartir los mapas con el equipo. Este repo incluye mapas de ejemplo sobre su propio código en .waymark/ (generados con Claude Code y con Codex, uno en español con 49 nodos narrados); CI los verifica con verify --strict. Mapas antiguos sin narrativa siguen funcionando (guide se lee como details); waymark enrich <id> les añade el storytelling.

Licencia

MIT. Inspirado en Devin Codemaps; no afiliado a Cognition ni Windsurf.

Desarrollo

npm test     # cliente MCP real sobre repos git temporales, hooks, instalador, drift y la extensión de VS Code (con un stub de la API)