wctx

Contexto de espacio de trabajo para agentes de codificación.

Tu sistema abarca múltiples repositorios. El contexto de tu agente también debería hacerlo.

wctx capture --summary "what this session figured out"   # at the end of a session
wctx search  "has anyone looked at this?"                # from any other repo, later

Session in Repo A
        ↓
discovers behavior in Repo B
        ↓
wctx
        ↓
fresh session in Repo B retrieves it

Una sesión de agente de codificación está limitada a un repositorio, porque es donde se editan los archivos. El sistema bajo investigación no lo está. Por lo tanto, una sesión en tu repositorio de UI descubre que el error está en realidad en tu SDK — y cuando abres una nueva sesión en el SDK una semana después, ese conocimiento se ha perdido.

wctx convierte las sesiones de agente completadas en contexto de ingeniería estructurado y respaldado por evidencia, y lo sirve a futuras sesiones a través de MCP. Local-primero: sin cuenta en la nube, sin embeddings, sin carga de transcripciones.

Demostración de dos minutos

pnpm install
pnpm demo

Sin clave API, sin red. Construye tres repositorios sintéticos, importa una sesión finalizada de uno y luego hace una pregunta en lenguaje natural desde otro:

$ wctx search "Has the selfie session expiration issue already been investigated?" --repo websdk-demo

  3 result(s) · 4 candidates · 14ms · searched websdk-demo plus 2 related repositories

  1. WebSDK uploadSessionImage does not retry after session expiration  [finding]
     from websdk-demo · session ses_8d3fb1a5 · commit 45a4cab · confidence 0.87
     · matches the query text
     · same repository
     · matches symbol uploadSessionImage

  3. Verify UI delegates selfie upload to the WebSDK  [finding]
     from verify-ui-demo · session ses_8d3fb1a5 · commit b041200 · confidence 0.95
     · matches the query text
     · verify-ui-demo uses websdk-demo (direct consumer)
     · high stated confidence (0.95)

Luego, el archivo del SDK cambia y la evidencia deja de ser confiable:

$ wctx evidence verify ev_9ae81278
  before: current — The repository is still at the source commit b60a991; nothing has changed.
  after:  stale   — All 1 referenced file(s) changed in b60a991..1ceeaa4. Re-read the code
                    before relying on this.

Recorrido completo: docs/demo.md.

Related MCP server: obsmcp

Instalación

Requiere Node 22+ y git.

pnpm install
pnpm build
npm link        # optional: puts `wctx` on your PATH

wctx init       # creates ~/.wctx
wctx doctor     # checks database, git, adapters, and prints MCP setup hints

Configuración de MCP

claude mcp add wctx -- wctx mcp

O, para Codex y otros clientes MCP:

{ "mcpServers": { "wctx": { "command": "wctx", "args": ["mcp"] } } }

Siete herramientas, ordenadas para divulgación progresiva para que sigan siendo asequibles en una ventana de contexto:

wctx mcp-info imprime los fragmentos de superficie y configuración del cliente.

Registro de lo que aprendió una sesión

Un solo comando, al final de una sesión. Importa la sesión si es necesario y registra la evidencia en un solo paso, por defecto en la sesión en la que estás ejecutando:

wctx capture --summary "Traced the upload failure into the SDK" \
  --finding "SDK swallows the 419 :: uploadSessionImage returns it as terminal, no retry" \
  --repo my-sdk \
  --file "src/session/upload.ts#uploadSessionImage"

O simplemente pídele a tu agente que lo haga — "registra lo que aprendimos" — y llama a finalize_session con su propio id de sesión. Nunca necesita conocer un id interno, y llamarlo repetidamente en una sesión acumula evidencia en lugar de duplicar la sesión.

Haciéndolo proactivo

Un agente solo hace esto si algo se lo dice, y el lugar más contundente para decirlo es el archivo de agente propio del proyecto — esos se leen en cada solicitud:

wctx instructions          # print the guidance
wctx instructions --write   # install it into CLAUDE.md / AGENTS.md (idempotent)

La guía cubre cuándo buscar (antes de investigar algo no trivial), cuándo registrar (causas raíz, decisiones con fundamento, restricciones ganadas con esfuerzo, preguntas sin resolver, sorpresas) y qué no registrar. Esa es la diferencia entre una herramienta que recuerdas usar y una que se acumula.

Sin ningún resumen proporcionado, wctx capture deriva uno factual de la actividad de herramientas registrada en la sesión — recuentos de archivos, comandos, errores, archivos cambiados. Aburrido a propósito: inventar una narrativa a partir de llamadas de herramientas sería exactamente la tontería segura de sí misma que este proyecto se niega a producir.

Conceptos fundamentales

Workspace — un producto lógico por encima de los repositorios. El límite del contexto. Los repositorios siguen siendo el límite de edición; nada aquí amplía el ámbito de escritura de un agente.

Repository — un checkout de git registrado, identificado por su ruta real para que el mismo repositorio no pueda registrarse dos veces a través de un enlace simbólico o subdirectorio. Puede pertenecer a varios workspaces.

Relation — una arista declarada, direccional y tipada (uses, depends_on, calls, imports, consumes_api, provides_api, shares_schema_with, related). El recorrido sigue las aristas en ambas direcciones, porque si verify-ui usa websdk, entonces una sesión en websdk aún quiere lo que verify-ui aprendió.

Session — una sesión de agente de codificación normalizada de Xirp, Claude Code o JSONL genérico, con su cwd, rama, commit, mensajes y actividad de herramientas.

Evidence — un hallazgo, decisión, cambio, pregunta sin resolver, problema conocido, nota de arquitectura o restricción, adjunto al repositorio sobre el que trata (a menudo no aquel en el que se ejecutó la sesión), con los archivos y símbolos que concierne y el commit en el que era cierto.

Freshness — un veredicto basado en git sobre si los archivos referenciados han cambiado desde ese commit: current, possibly_stale, stale o unknown.

Arquitectura

Xirp · Claude Code · Codex · generic JSONL
                  ↓
          session adapters              ← the only code that knows a vendor format
                  ↓
        NormalizedSession
           ↓            ↓
  transcript copy   deterministic extraction (files, commands, errors — no LLM)
                        ↓
              structured evidence (findings, decisions, questions)
                        ↓
              workspace catalog · SQLite + FTS5 + git
                        ↓
              CLI  ·  MCP  ·  web UI          ← one service layer, no duplicated logic

Detalles, y el razonamiento detrás de cada límite: docs/architecture.md.

Estado de integración con Xirp

Resultó que Xirp expone una ruta de lectura genuina y documentada, por lo que el adaptador es real y no un stub.

El adaptador fija ambas cadenas de esquema y falla ruidosamente en una versión desconocida en lugar de adivinar. Evidencia completa, incluyendo lo que queda sin verificar y cómo reproducirlo: docs/research/xirp.md.

Seguridad

Nada sale de tu máquina. Sin nube, sin telemetría, sin API de embeddings, sin carga de transcripciones; la lista completa de dependencias es @modelcontextprotocol/server, better-sqlite3, commander y zod.

• Las transcripciones se copian en tu directorio de datos (Claude Code elimina las suyas después de 30 días) con una copia censurada junto a ella — y solo se sirve la copia censurada.

• La censura cubre claves privadas, JWTs, encabezados de autorización, tokens de AWS/GitHub/Slack/OpenAI/Google, URLs con credenciales y asignaciones secretas. Es coincidencia de patrones de mejor esfuerzo y no es una garantía de que una transcripción sea segura para compartir.

• La evidencia devuelta a los agentes se etiqueta como datos históricos no confiables, y las líneas similares a instrucciones ("ignora todas las instrucciones anteriores") se neutralizan. Mitigación, no inmunidad.

• Cada llamada a git usa un array de argumentos, nunca una cadena de shell. Las consultas FTS5 se construyen, nunca se interpolan.

• La eliminación de transcripciones y la eliminación de evidencia son operaciones independientes.

Detalles: docs/security.md.

Comparación con herramientas existentes

Las afirmaciones de capacidad provienen del README de cada proyecto, verificado el 2026-08-13. Nada aquí afirma que otro proyecto no pueda hacer algo.

Encuesta completa con el límite de memoria de cada proyecto, mecanismo de captura y lo que se reutilizó como idea: docs/research/competitive-landscape.md.

Evaluación

En un corpus sintético de 15 consultas, 28 elementos (pnpm eval), la sesión previa relevante apareció entre los cinco primeros para 15 de 15 consultas y ocupó el primer lugar para 11 de 15, con una latencia de recuperación local mediana de 1.6 ms. Agregar la topología del workspace a FTS5 simple dejó la tasa de aciertos sin cambios en este corpus pero mejoró el MRR de 0.839 a 0.867, hizo que la atribución del repositorio fuera exacta (0.93 → 1.00) y eliminó los resultados de repositorios no relacionados (0.20 → 0.00 por consulta).

El corpus es pequeño, sintético y escrito por la misma persona que escribió las consultas. Lo que eso significa para leer los números se explica en docs/evaluation.md.

Limitaciones

La lista honesta, completa: KNOWN_LIMITATIONS.md. Las tres que más importan:

• La recuperación tiene forma de palabras clave. FTS5 empareja tokens. Una consulta completamente parafraseada sin superposición léxica puede fallar; los refuerzos estructurales solo compensan parcialmente.

• La actualidad no es verificación. Responde «¿han cambiado los archivos referenciados?», nunca «¿sigue siendo cierta esta afirmación?». Un cambio de comportamiento en un archivo no tocado es invisible.

• Las relaciones se declaran, no se infieren. Una relación no declarada es invisible para el ranking.

Roadmap

Ordenado por cuánto mejorarían el bucle central:

1. Finalización automática de sesión mediante un hook stop de arnés (actualmente manual).

2. Adaptación del adaptador Xirp entre versiones y los arneses codex / gemini.

3. Detección de conflictos y sugerencias de sustitución: el esquema soporta ambas; nada las pobló.

4. Importación de catalog-info.yaml de Backstage / Portal tras la costura existente CatalogProvider.

5. Un corpus de evaluación más difícil con hallazgos casi duplicados, para probar si la topología ayuda a encontrar en lugar de solo a ordenar.

Contributing

Ver CONTRIBUTING.md. pnpm typecheck && pnpm lint && pnpm test deben pasar, y pnpm demo debe funcionar desde un clon limpio sin credenciales.

Atribución y no afiliación

wctx es un experimento independiente de código abierto inspirado en ideas públicas de Xirp, Spotify Portal, Backstage y MCP.

No está afiliado ni respaldado por Spotify.

No se copió ningún código fuente de ninguno de los proyectos en la tabla de comparación. La distinción Componente/Sistema de Backstage se utiliza como inspiración de diseño, no como una dependencia en tiempo de ejecución, y no se requiere ninguna instancia de Backstage.

Licencia

MIT. Ver LICENSE.