AgenticWorkspace

AgenticWorkspace

Apúntalo a cualquier repositorio. Detecta el stack, escribe un directorio .workspace/ con contexto progresivo y traspasos de sesión, e instala un adaptador funcional de Claude Code, todo en un solo comando.

npx agenticworkspace-cli init

Esta es una versión v0.1. Cero instalaciones, cero estrellas en GitHub, primer lanzamiento. 99/99 pruebas de JavaScript y 132/132 pruebas de Python pasan. Hace lo que se describe a continuación y nada más. Hay una comparación honesta con las otras herramientas que ya funcionan en este espacio más abajo, para que puedas decidir si AgenticWorkspace realmente vale la pena probarlo antes de ejecutarlo.

Tabla de contenidos

• Instalación
• Características
• Inicio rápido
• Referencia de CLI
• El directorio .workspace/
• Referencia de la API de biblioteca
• Estado del adaptador
• Extender AgenticWorkspace
• Cómo se compara esto con repo-harness y harnesskit
• Qué y por qué
• Desarrollo
• Preguntas frecuentes
• Contribuciones
• Licencia

Instalación

AgenticWorkspace incluye dos paquetes independientes, ambos de primera clase, que implementan el mismo pipeline de escaneo/andamiaje/adaptador y leen/escriben la misma forma de directorio .workspace/: elige el que se ajuste a tu cadena de herramientas, o instala ambos. Ninguno está en desuso en favor del otro.

# npm -- JavaScript/TypeScript CLI + library (live today, v0.1.3)
npx agenticworkspace-cli init

# PyPI -- Python CLI + library (live today, v0.1.1)
pip install agenticworkspace-cli
agenticworkspace init --path /path/to/your/repo

Para instalar desde el código fuente en su lugar:

git clone https://github.com/RudrenduPaul/AgenticWorkspace.git
cd AgenticWorkspace/python
pip install -e .
agenticworkspace init --path /path/to/your/repo

Para uso repetido con el paquete npm, instálalo globalmente:

npm install -g agenticworkspace-cli
agenticworkspace init

El punto de entrada de CLI del paquete Python también es agenticworkspace (por ejemplo, agenticworkspace init --path ./my-app); consulta python/README.md y docs/getting-started.md para el tutorial específico de Python.

Para compilar el paquete TypeScript desde el código fuente en su lugar:

git clone https://github.com/RudrenduPaul/AgenticWorkspace.git
cd AgenticWorkspace
npm install
npm run build
node dist/agenticworkspace/cli.js init

Características

Todo lo siguiente está verificado contra el código fuente real en este repositorio, no es aspiracional.

• Detección real de stack -- lenguaje (JavaScript/TypeScript, Python, señales más ligeras para Rust/Go/Ruby), gestor de paquetes (npm/pnpm/yarn) y recuento de paquetes de monorepo, leídos de archivos de manifiesto reales (src/agenticworkspace/scan/stack-detector.ts).
• No destructivo por defecto -- comprueba CLAUDE.md, AGENTS.md, .cursor/rules y .github/copilot-instructions.md y nunca los sobrescribe (src/agenticworkspace/scan/config-detector.ts).
• Detecta otras herramientas de memoria de agente sin tocarlas -- busca un directorio .serena/, una configuración estilo GitNexus, o el propio directorio .ai/harness/ de repo-harness, informa lo que encuentra y nunca lee ni escribe en ninguno de ellos (src/agenticworkspace/memory-backends/).
• Un adaptador real y funcional de Claude Code -- escribe scripts de hook reales para el inicio de sesión, la llamada previa a la herramienta y la generación de traspaso al final de la sesión, conectados a .workspace/adapters/claude-code/settings.json (src/agenticworkspace/adapters/claude-code/install.ts).
• Salida JSON estructurada en cada subcomando -- init, scan, status, adapter install y handoff new admiten --json, incluso en rutas de error (un --path inexistente, un espacio de trabajo faltante, un adaptador no implementado), para que un agente que llama nunca tenga que analizar texto legible por humanos o adivinar códigos de salida.
• Dos interfaces de plugin documentadas, no un pipeline codificado -- MemoryBackend (src/agenticworkspace/memory-backends/types.ts) y Adapter (src/agenticworkspace/adapters/types.ts). Agregar una nueva herramienta significa implementar una interfaz y registrarla (registry.ts en cada carpeta); no se requieren cambios en el código de CLI o escaneo. Consulta Extender AgenticWorkspace a continuación.
• Generación de hooks segura contra inyección de shell -- cada valor escaneado (nombres de módulos, rutas) que termina incrustado en un script de shell generado pasa primero por una lista blanca y una verificación de comillas (src/agenticworkspace/util/sanitize.ts), cubierto por 30 pruebas unitarias dedicadas (confirmado al ejecutar la suite directamente, incluidos los casos de rechazo parametrizados).
• Recuperación de estado parcial -- una ejecución previa de init interrumpida o malformada se detecta y se muestra (mensaje interactivo de reparación/restablecimiento/aborto, o un error JSON estructurado con un código de salida dedicado en modo --json) en lugar de sobrescribirse o reanudarse silenciosamente (src/agenticworkspace/state/partial-state.ts).

Inicio rápido

Una ejecución real contra un pequeño repositorio JavaScript de dos archivos (ruta de destino acortada a /Users/you/my-app para legibilidad, cada valor de campo a continuación es la salida real):

$ agenticworkspace init --json --path ./my-app

{
  "ok": true,
  "agenticworkspace_version": "0.1.1",
  "scanned_at": "2026-08-04T06:18:25.620Z",
  "target": "/Users/you/my-app",
  "stack": {
    "language": "javascript",
    "package_manager": "npm",
    "monorepo": false,
    "packages": 1
  },
  "existing_config": {
    "claudeMd": false,
    "agentsMd": false,
    "cursorRules": false,
    "copilotInstructions": false,
    "anyDetected": false
  },
  "memory_backends": [
    { "name": "serena", "detected": false, "description": "Serena memory/context tool (.serena/ directory)" },
    { "name": "gitnexus", "detected": false, "description": "GitNexus-style config (.gitnexus/ or gitnexus.config.json)" },
    { "name": "repo-harness", "detected": false, "description": "repo-harness (.ai/harness/ directory) -- detected only, never modified" }
  ],
  "context": { "root_context_kb": 0.6, "budget_kb": 12, "modules": [] },
  "adapters": { "claude_code": { "installed": true, "hook_schema_version": "2026-07-01" } },
  "workspace_dir": "/Users/you/my-app/.workspace"
}

El campo agenticworkspace_version en esa salida es una cadena de versión rastreada por separado de la versión npm/PyPI del paquete (pueden divergir; trátalo como un marcador de esquema interno, no la versión del paquete que instalaste).

Esa única ejecución escribió siete archivos reales en disco:

.workspace/workspace.json
.workspace/context/root-context.md
.workspace/adapters/claude-code/settings.json
.workspace/adapters/claude-code/adapter-meta.json
.workspace/adapters/claude-code/hooks/session-start.sh
.workspace/adapters/claude-code/hooks/pre-tool-call.sh
.workspace/adapters/claude-code/hooks/session-end-handoff.sh

Elimina --json para una versión legible por humanos de la misma ejecución:

$ agenticworkspace init --path ./my-app

AgenticWorkspace v0.1 -- Repo-to-Agent-Workspace Converter
Target: /Users/you/my-app

Scanning repository...
[OK] Stack detected: javascript, npm
[--] No existing agent-config files found
[--] No memory/context tool detected

Writing .workspace/ scaffold...
  .workspace/workspace.json                created
  .workspace/context/root-context.md        created (0.6KB of 12KB budget)
  .workspace/handoff/                       created (empty, ready for first session)

Installing Claude Code adapter...
  .workspace/adapters/claude-code/settings.json         written
  .workspace/adapters/claude-code/hooks/session-start.sh  written
  .workspace/adapters/claude-code/hooks/pre-tool-call.sh  written
  .workspace/adapters/claude-code/hooks/session-end-handoff.sh  written

Workspace ready. Next Claude Code session in this repo will load root-context.md automatically
and write a handoff file on exit.

Verificar la salud del espacio de trabajo y escribir un traspaso de sesión en ese mismo repositorio, salida real:

$ agenticworkspace status --path ./my-app

AgenticWorkspace status
Target: /Users/you/my-app
Last scan: 2026-08-04T06:18:25.620Z

Stack: javascript, npm, 1 package(s)
Context budget: 0.6KB of 12KB (0 module block(s))
Handoffs: 0 file(s), most recent: none
Claude Code adapter: installed, schema 2026-07-01, current
Other backends detected: none

$ agenticworkspace handoff new "test session" --path ./my-app

Handoff written: .workspace/handoff/2026-08-04-0618.md

Consulta docs/usage.gif para una ejecución grabada de handoff new y status juntos.

Características

Todo lo siguiente está verificado contra el código fuente real en este repositorio, no es aspiracional.

• Detección real de stack -- lenguaje (JavaScript/TypeScript, Python, señales más ligeras para Rust/Go/Ruby), gestor de paquetes (npm/pnpm/yarn) y recuento de paquetes de monorepo, leídos de archivos de manifiesto reales (src/agenticworkspace/scan/stack-detector.ts).
• No destructivo por defecto -- comprueba CLAUDE.md, AGENTS.md, .cursor/rules y .github/copilot-instructions.md y nunca los sobrescribe (src/agenticworkspace/scan/config-detector.ts).
• Detecta otras herramientas de memoria de agente sin tocarlas -- busca un directorio .serena/, una configuración estilo GitNexus, o el propio directorio .ai/harness/ de repo-harness, informa lo que encuentra y nunca lee ni escribe en ninguno de ellos (src/agenticworkspace/memory-backends/).
• Un adaptador real y funcional de Claude Code -- escribe scripts de hook reales para el inicio de sesión, la llamada previa a la herramienta y la generación de traspaso al final de la sesión, conectados a .workspace/adapters/claude-code/settings.json (src/agenticworkspace/adapters/claude-code/install.ts).
• Salida JSON estructurada en cada subcomando -- init, scan, status, adapter install y handoff new admiten --json, incluso en rutas de error (un --path inexistente, un espacio de trabajo faltante, un adaptador no implementado), para que un agente que llama nunca tenga que analizar texto legible por humanos o adivinar códigos de salida.
• Dos interfaces de plugin documentadas, no un pipeline codificado -- MemoryBackend (src/agenticworkspace/memory-backends/types.ts) y Adapter (src/agenticworkspace/adapters/types.ts). Agregar una nueva herramienta significa implementar una interfaz y registrarla (registry.ts en cada carpeta); no se requieren cambios en el código de CLI o escaneo. Consulta Extender AgenticWorkspace a continuación.
• Generación de hooks segura contra inyección de shell -- cada valor escaneado (nombres de módulos, rutas) que termina incrustado en un script de shell generado pasa primero por una lista blanca y una verificación de comillas (src/agenticworkspace/util/sanitize.ts), cubierto por 30 pruebas unitarias dedicadas.
• Recuperación de estado parcial -- una ejecución previa de init interrumpida o malformada se detecta y se muestra (mensaje interactivo de reparación/restablecimiento/aborto, o un error JSON estructurado con un código de salida dedicado en modo --json) en lugar de sobrescribirse o reanudarse silenciosamente (src/agenticworkspace/state/partial-state.ts).

Referencia de CLI

Cada comando acepta -p, --path <path> (por defecto, el directorio actual) y --json (salida estructurada en lugar del valor predeterminado legible por humanos). La referencia a continuación es la salida real de --help de un binario agenticworkspace compilado localmente.

Comando	Descripción
agenticworkspace init	Escanea el repositorio y escribe el andamiaje .workspace/ más el adaptador de Claude Code. Idempotente: seguro de volver a ejecutar.
agenticworkspace scan	Detecta el stack y la superficie de herramientas de agente existente solo. Sin escrituras.
agenticworkspace status	Informa la salud del espacio de trabajo: stack, uso del presupuesto de contexto, recuento de traspasos, obsolescencia del adaptador.
agenticworkspace adapter install <name>	(Re)instala la conexión de hooks de un solo adaptador, por ejemplo, claude-code. Devuelve adapter_not_implemented para codex o cursor.
agenticworkspace handoff new <message>	Escribe un nuevo archivo de traspaso de sesión con marca de tiempo bajo .workspace/handoff/.

Los códigos de salida son estables entre los modos --json y legible por humanos, por lo que un script puede ramificarse según ellos sin analizar texto. Verificado directamente: adapter install codex sale con 3 con un mensaje "NOT YET IMPLEMENTED", y status contra un objetivo sin .workspace/ sale con 4.

Código	Significado
0	Éxito
1	Error general (entrada incorrecta, fallo inesperado del sistema de archivos)
2	Estado .workspace/ parcial o malformado detectado
3	Adaptador aún no implementado (codex, cursor)
4	No se encontró .workspace/ (ejecuta init primero)

Servidor MCP

El paquete Python incluye un servidor de Protocolo de Contexto de Modelo (MCP), por lo que un agente compatible con MCP (Claude Desktop, Claude Code o cualquier otro cliente MCP) puede llamar a AgenticWorkspace como una herramienta en lugar de invocar la CLI y analizar texto por sí mismo.

pip install "agenticworkspace-cli[mcp]"

Agrégalo a la configuración de tu cliente MCP (transporte stdio):

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

Expone una sola herramienta, run(args: list[str]) -> dict, que invoca la CLI agenticworkspace instalada con la lista de argumentos dada y devuelve su resultado analizado: cada subcomando (init, scan, status, adapter install, handoff new) es accesible a través de ella, por lo que la superficie MCP nunca se desincroniza de la CLI a medida que se agregan nuevos subcomandos. Cada modo de fallo (binario faltante, tiempo de espera, salida distinta de cero, salida no analizable) regresa como un dict {"error": ...} en lugar de lanzar una excepción. Ejemplo de llamada y resultado:

run(["scan", "--json", "--path", "/path/to/repo"])
-> {"ok": true, "target": "/path/to/repo", "stack": {"language": "javascript", ...}, ...}

El directorio .workspace/

.workspace/
  workspace.json              manifest: detected stack, adapters installed, schema version
  context/
    root-context.md           progressive root context, budget-targeted (~12KB)
    modules/
      auth.md                 per-module capability block, loaded on demand
      api.md
  handoff/
    2026-07-13-1421.md         one file per session, timestamped
  adapters/
    claude-code/
      settings.json           hook entries wired into Claude Code's settings schema
      hooks/
        session-start.sh       loads root-context.md + relevant module blocks
        pre-tool-call.sh        lightweight guard, extendable per project
        session-end-handoff.sh writes the next handoff/ file automatically

Referencia de la API de biblioteca

Ambos paquetes exportan su lógica de escaneo/andamiaje/adaptador para uso programático además del binario CLI. Las firmas a continuación se extraen directamente del código fuente.

TypeScript (agenticworkspace-cli, src/agenticworkspace/index.ts)

import {
  detectStack,
  detectExistingConfig,
  memoryBackendRegistry,
  detectAllMemoryBackends,
  adapterRegistry,
  getAdapter,
  runInitEngine,
  readManifest,
  writeManifest,
  sanitizeForShellEmbedding,
  validateAgainstAllowlist,
  shellQuote,
} from "agenticworkspace-cli";

async function detectStack(repoPath: string): Promise<StackDetectionResult>;
async function detectExistingConfig(repoPath: string): Promise<ExistingConfigResult>;
async function runInitEngine(repoPath: string, workspaceDir: string): Promise<InitEngineResult>;
function getAdapter(name: string): Adapter | undefined;
async function readManifest(workspaceDir: string): Promise<WorkspaceManifest | null>;
async function writeManifest(workspaceDir: string, manifest: WorkspaceManifest): Promise<void>;
function sanitizeForShellEmbedding(
  rawValue: unknown,
  warn?: SanitizeWarning,
  options?: SanitizeForShellOptions,
): string | null;
function validateAgainstAllowlist(rawValue: unknown): SanitizeResult;
function shellQuote(value: string): string;

MemoryBackend y Adapter se exportan como tipos de TypeScript para cualquiera que implemente un nuevo plugin (src/agenticworkspace/memory-backends/types.ts, src/agenticworkspace/adapters/types.ts).

Python (agenticworkspace-cli en PyPI, python/src/agenticworkspace/__init__.py)

from agenticworkspace import (
    adapter_registry,
    get_adapter,
    memory_backend_registry,
    detect_all_memory_backends,
    Adapter,
    MemoryBackend,
    AGENTICWORKSPACE_VERSION,
)

Adapter y MemoryBackend son clases abc.ABC aquí en lugar de interfaces de TypeScript: implementa una, agrega una instancia a adapter_registry o memory_backend_registry (listas de Python simples), y no se requieren cambios en el código de CLI o escaneo. El paquete incluye un marcador py.typed, por lo que los verificadores de tipos detectan sus stubs sin configuración adicional.

Estado del adaptador (v0.1)

Adaptador	Estado
Claude Code	Implementado, funciona de extremo a extremo
Codex	Registrado, aún no implementado
Cursor	Registrado, aún no implementado

Extender AgenticWorkspace

AgenticWorkspace está construido alrededor de dos interfaces de plugin, no un proyecto que hace todo por sí mismo:

• MemoryBackend (src/agenticworkspace/memory-backends/types.ts) -- detecta si un repositorio ya tiene una herramienta de memoria/contexto conectada. La detección debe permanecer de solo lectura.
• Adapter (src/agenticworkspace/adapters/types.ts) -- conecta el andamiaje .workspace/ a una herramienta de codificación específica: instalación, verificación de obsolescencia y una descripción legible por humanos.

Agregar soporte para una nueva herramienta significa implementar una de estas interfaces y registrar una instancia en el registry.ts de esa carpeta; no se requieren cambios en el código de CLI o escaneo. Consulta src/agenticworkspace/adapters/codex/ y .../cursor/ para ver la forma que toma un stub aún no implementado (isImplemented: false más una cadena describe() real), y .../claude-code/ para una implementación de referencia completamente funcional. El paquete de Python (pip install agenticworkspace-cli) implementa las mismas dos interfaces que las clases abc.ABC con el mismo contrato de registro (memory_backend_registry / adapter_registry, listas de Python simples) — consulte docs/integrations/custom-plugin.md para ver un ejemplo práctico en ambos lenguajes.

Cómo se compara esto con repo-harness y harnesskit

El contexto local del repositorio y el seguimiento de transferencias de sesión para agentes de codificación no es una idea nueva. Antes de construir esto, verificamos lo que ya se está publicando. Dos paquetes npm cubren terreno superpuesto, y su estado actual (verificado el 2026-08-03) importa más que cualquier afirmación nuestra sobre ellos:

	AgenticWorkspace v0.1.3 (npm) / v0.1.1 (PyPI)	repo-harness v0.13.0	harnesskit v0.1.1
Actividad npm	3 versiones publicadas (0.1.1 -> 0.1.3), creado el 2026-07-15, publicado más recientemente el 2026-08-04	46 versiones publicadas, creado el 2026-05-28, última publicación el 2026-08-03 (el mismo día de esta verificación)	2 versiones publicadas, última publicación el 2026-03-20 (aproximadamente 4.5 meses de desactualización al momento de esta verificación)
GitHub	0 estrellas, 0 bifurcaciones (repositorio nuevo)	402 estrellas, 29 bifurcaciones, actualizado el 2026-08-03	El repositorio de GitHub ahora devuelve 404, no se puede inspeccionar el código fuente
Adaptador Claude Code	Implementado de extremo a extremo: scripts de hook reales + cableado settings.json, instalado por init en la misma ejecución que crea el espacio de trabajo	Implementado: adaptador de hook ~/.claude/settings.json	No verificado, no se pudo inspeccionar el código fuente ni el README (la página npm bloqueó nuestra descarga, el repositorio de GitHub desapareció)
Adaptador Codex	Registrado en la interfaz del adaptador, install() lanza "aún no implementado" — stub honesto, no un no-op silencioso	Implementado: adaptador ~/.codex/hooks.json	No verificado
Adaptador Cursor	Registrado, mismo patrón de stub honesto que Codex	No mencionado en ningún lugar del README actual (una comparación anterior lo encontró referenciado en documentos de arquitectura; esa referencia ha desaparecido al momento de esta verificación)	No verificado
Carga progresiva de contexto	Archivo de contexto raíz orientado a presupuesto (~12KB) más bloques de capacidades por módulo, cargados bajo demanda	Contexto raíz estable de ~12KB más contratos de capacidades de ~1KB cargados solo para archivos que realmente se están tocando, respaldados por un índice estructural CodeGraph que no construimos	No verificado
Archivos de transferencia de sesión	Archivo con marca de tiempo por sesión bajo handoff/	Directorio .ai/harness/handoff/ más tasks/current.md, derivados de artefactos de flujo de trabajo	No verificado
Salida JSON de CLI	Cada subcomando (scan, status, adapter install, handoff) admite --json, incluidos los caminos de error	Tiene salida JSON en al menos --dry-run --json y state-snapshot --json	No verificado
Detecta otras herramientas sin tocarlas	Sí: verifica .serena/, una configuración estilo GitNexus, y el propio directorio .ai/harness/ de repo-harness, informa lo que encuentra, nunca lee ni escribe en ninguno de ellos	No verificado — fuera del alcance de lo que revisamos	No verificado
Modelo de plugin/extensión	Dos interfaces TypeScript documentadas (MemoryBackend, Adapter); agregar una herramienta significa implementar una y registrarla, sin cambios en la CLI	No verificado solo desde el README; sería necesario leer el código fuente para confirmar	No verificado
Panel de control multi-repositorio alojado	No existe. No está planificado como parte de esta CLI OSS.	No existe, solo flujo de trabajo autohospedado respaldado por archivos	No verificado
Idiomas de documentación	Solo inglés	Inglés (principal), más chino simplificado, japonés, francés, español	No verificado

Lo que pudimos verificar provino de npm view, la API de GitHub, y el propio README de repo-harness (obtenido directamente). No instalamos ni ejecutamos repo-harness contra un repositorio real nosotros mismos, por lo que cualquier cosa marcada como "implementado" para él es una afirmación del README que leímos, no una afirmación que reproducimos de primera mano. Todo lo marcado como "no verificado" para harnesskit permaneció así porque su repositorio de GitHub ya no se resuelve y su página npm bloqueó descargas automatizadas; no vamos a adivinar qué hace una herramienta a partir de una cadena de descripción. (También existe un paquete PyPI llamado harnesskit, pero es un proyecto diferente y no relacionado de un autor distinto — una herramienta difusa de reemplazo de cadenas para agentes de codificación LLM — y no lo estamos contando aquí.)

El propio alcance de repo-harness ha crecido desde la última vez que lo verificamos: su README ahora se centra en un sidecar de planificación MCP impulsado por ChatGPT que entrega a Codex para la ejecución, además de los adaptadores de hook Claude/Codex que esta tabla ya cubre. Esa es una superficie materialmente más grande que "contexto local del repositorio y seguimiento de transferencias," y vale la pena saberlo antes de comparar las dos herramientas proyecto a proyecto en lugar de característica a característica.

La lectura honesta: repo-harness es más maduro que AgenticWorkspace en casi todas las dimensiones de esta tabla en este momento. Ya tiene un adaptador de Claude Code funcional, un adaptador de Codex funcional, y cinco idiomas de documentación. Ha estado iterando rápido (46 versiones en poco más de dos meses). Si ya lo usas y te funciona, no hay razón para cambiar.

Lo que realmente construimos de manera diferente: una arquitectura de plugin con dos interfaces pequeñas y documentadas (MemoryBackend para detectar otras herramientas, Adapter para conectarse a un agente de codificación específico) en lugar de un proyecto que hace todo por sí mismo, y una verificación de compatibilidad explícita que detecta el propio directorio .ai/harness/ de repo-harness y lo informa en lugar de duplicarlo o entrar en conflicto silenciosamente. Más allá de eso, en este momento, esta es una CLI nueva y no probada que se enfrenta a una más establecida. No vamos a adornar eso.

Una cosa más que vale la pena mencionar: el propio Claude Code ahora incluye un sistema de memoria de primera parte basado en MEMORY.md y almacenes de memoria de equipo, además de un hook de ciclo de vida post-session que puede capturar instantáneas de trabajo no confirmado. No escanea la pila de un repositorio ni instala un adaptador específico de Claude-Code de la manera que AgenticWorkspace lo hace, pero la brecha entre "lo que la plataforma hace de forma nativa" y "lo que una herramienta como esta agrega" es más estrecha de lo que era cuando comenzó esta categoría, y vale la pena observarla antes de asumir que cualquiera de estas herramientas sigue siendo necesaria.

Qué y por qué

Los agentes de codificación pierden contexto en el momento en que termina una sesión, y cada repositorio necesita su propia configuración manual antes de que un agente pueda trabajar bien en él: qué archivo CLAUDE.md o AGENTS.md escribir, cómo transferir trabajo parcial a la siguiente sesión, qué hooks conectar. Esa configuración es repetitiva, fácil de equivocar, y rara vez se mantiene actualizada a medida que cambia la pila de un proyecto.

AgenticWorkspace automatiza las partes de esa configuración que son mecánicas y agnósticas del repositorio: averiguar qué pila usa un repositorio, escribir un archivo de contexto progresivo dimensionado para mantenerse dentro de un presupuesto de tokens en lugar del código base completo del modelo, e instalar hooks reales para que una sesión de Claude Code genere una nota de transferencia automáticamente en lugar de depender de un humano para escribirla. No intenta ser una base de datos de memoria, un índice de código semántico, o un panel de control alojado. Es una CLI de andamiaje: escribe archivos una vez, en un formato que cualquiera de esas otras herramientas podría leer o extender más tarde, y luego se aparta del camino.

¿Por qué construir otro de estos cuando repo-harness ya existe y tiene más tracción (consulte la tabla de comparación anterior)? Porque la respuesta honesta es: no para desplazarlo. Este proyecto existe para probar una versión más estrecha, primero para Claude-Code, de la misma idea con una arquitectura de plugin que mantiene el código de detección y adaptador desacoplado desde el primer día, y para ser transparente en público sobre exactamente cómo se compara con la herramienta que llegó primero.

Desarrollo

git clone https://github.com/RudrenduPaul/AgenticWorkspace.git
cd AgenticWorkspace
npm install
npm run build
npm test

99/99 pruebas pasan al momento de este lanzamiento. Antes de abrir una solicitud de extracción, ejecute npm run lint, npm run typecheck, npm run test:coverage, y npm run build — los mismos pasos que CI ejecuta en Node 20.x y 22.x.

Para el paquete de Python en su lugar:

cd python
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

132/132 pruebas pasan al momento del lanzamiento inicial del paquete de Python. Consulte python/README.md para las notas de desarrollo específicas de Python.

Preguntas frecuentes

¿Qué es AgenticWorkspace, y qué lo hace diferente de escribir un archivo CLAUDE.md a mano? Es un convertidor de repositorio a espacio de trabajo de agente: un solo comando (agenticworkspace init) escanea la pila de un repositorio, escribe un archivo de contexto progresivo con presupuesto de tokens, e instala un adaptador de Claude Code funcional con scripts de hook reales, todo en una sola ejecución no destructiva. El diferenciador es que esto está automatizado y es agnóstico del repositorio en lugar de una plantilla que copias y editas a mano, y está construido alrededor de dos interfaces de plugin documentadas (MemoryBackend, Adapter) en lugar de un pipeline codificado, por lo que agregar un nuevo adaptador de agente de codificación o backend de memoria no requiere tocar la CLI o el código de escaneo.

¿Cuáles son los requisitos de instalación y plataforma? El paquete npm requiere Node.js 20 o posterior ("engines": { "node": ">=20.0.0" } en package.json). El paquete de Python requiere Python 3.9 o posterior (requires-python = ">=3.9" en python/pyproject.toml) y está clasificado Operating System :: OS Independent en PyPI. Ambos paquetes son Node/Python simples sin dependencias nativas o específicas del sistema operativo; el desarrollo y las pruebas diarias ocurren en macOS y Linux, y Windows no ha sido verificado por separado por los mantenedores.

¿Esto modifica mi CLAUDE.md, AGENTS.md, o .cursor/rules existente? No. init verifica los cuatro archivos de configuración (CLAUDE.md, AGENTS.md, .cursor/rules, .github/copilot-instructions.md) e informa lo que encuentra, pero nunca escribe ni sobrescribe ninguno de ellos.

¿Esto entra en conflicto con Serena, GitNexus, o repo-harness si ya uso uno de ellos? No. La detección es de solo lectura: AgenticWorkspace verifica .serena/, una configuración estilo GitNexus, y el directorio .ai/harness/ de repo-harness, informa lo que encuentra en la salida scan/status/init, y nunca lee, escribe, ni elimina nada dentro de ellos.

¿Cómo se compara esto realmente con repo-harness, la alternativa más establecida? Consulte la tabla de comparación completa anterior para el desglose completo y fechado. En resumen: repo-harness es más maduro en casi todos los ejes medibles en este momento (más versiones publicadas, más estrellas de GitHub, un adaptador de Codex funcional, cinco idiomas de documentación, y un alcance más amplio de planificador-MCP-más-ejecución-Codex). Lo que AgenticWorkspace hace de manera diferente es una arquitectura de plugin más pequeña de dos interfaces y una verificación de compatibilidad explícita y de solo lectura para el propio directorio .ai/harness/ de repo-harness. Si repo-harness ya te funciona para ti, no hay razón en esta tabla para cambiar.

¿Qué sucede si init se interrumpe a mitad de camino? La siguiente ejecución de init detecta el marcador .init-in-progress sobrante o un workspace.json faltante o malformado y ya sea te solicita reparar, restablecer, o abortar (terminal interactiva), o devuelve un error JSON estructurado con código de salida 2 (modo no interactivo o --json) en lugar de sobrescribir o reanudar silenciosamente.

¿Por qué el adaptador de Codex o Cursor aún no está implementado? Ambos están registrados en la interfaz de plugin Adapter con isImplemented: false y una cadena describe() real y honesta en lugar de un no-op silencioso. Claude Code se construyó primero porque ese es el adaptador contra el cual se construyó y probó el propio flujo de trabajo de este repositorio. Las contribuciones que implementen cualquiera de los dos son bienvenidas, consulte Extendiendo AgenticWorkspace.

¿Hay un panel de control alojado o un nivel de pago? No en este repositorio. Esta CLI es la capa gratuita, local, comparable a MIT (Apache-2.0). No hay componente alojado aquí para registrarse.

¿Qué licencia tiene esto, y puedo usarlo comercialmente? Licencia Apache 2.0 (consulte LICENSE). Permite uso comercial, modificación, uso privado, y distribución, e incluye una concesión de patente expresa, sujeto a preservar la licencia y el aviso de derechos de autor y sin garantía. ¿Existe una versión de Python? Sí: un puerto genuino de Python (no un envoltorio alrededor del binario de Node), con la misma forma de CLI, la misma salida de .workspace/, y el mismo contrato de plugins MemoryBackend/Adapter, además de su propia superficie de biblioteca importable (Adapter y MemoryBackend como clases abc.ABC). Consulta python/README.md para el recorrido de instalación y uso específico de Python.

Contribuciones

Consulta CONTRIBUTING.md para la configuración de desarrollo, la lista de verificación previa al PR, e instrucciones concretas para agregar un nuevo MemoryBackend o Adapter. Los cambios sensibles a la seguridad (cualquier cosa que toque scripts de shell generados) deben pasar por el módulo de sanitización compartido descrito allí.

Licencia

Apache 2.0. Consulta LICENSE.