AgenticWorkspace

AgenticWorkspace

Aponte para qualquer repositório. Ele detecta a stack, escreve um diretório .workspace/ com contexto progressivo e transferências de sessão, e instala um adaptador Claude Code funcional, tudo em um único comando.

npx agenticworkspace-cli init

Esta é uma versão v0.1. Zero instalações, zero estrelas no GitHub, primeira versão. 99/99 testes de JavaScript e 132/132 testes de Python passam. Ele faz o que está descrito abaixo e nada mais. Há uma comparação honesta com as outras ferramentas que já funcionam nesse espaço mais adiante, para que você possa decidir se o AgenticWorkspace realmente vale a pena tentar antes de executá-lo.

Sumário

• Instalação
• Recursos
• Início rápido
• Referência da CLI
• O diretório .workspace/
• Referência da API da biblioteca
• Status do adaptador
• Estendendo o AgenticWorkspace
• Como isso se compara ao repo-harness e ao harnesskit
• O quê e por quê
• Desenvolvimento
• FAQ
• Contribuindo
• Licença

Instalação

O AgenticWorkspace oferece dois pacotes independentes, igualmente de primeira classe, que implementam o mesmo pipeline de scan/scaffold/adapter e leem/escrevem o mesmo formato de diretório .workspace/ — escolha o que melhor se adequa à sua ferramenta, ou instale ambos. Nenhum está obsoleto em favor do outro.

# 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 a partir do código-fonte:

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

Para uso repetido com o pacote npm, instale-o globalmente:

npm install -g agenticworkspace-cli
agenticworkspace init

O ponto de entrada da CLI do pacote Python também é agenticworkspace (ex.: agenticworkspace init --path ./my-app); veja python/README.md e docs/getting-started.md para o passo a passo específico do Python.

Para compilar o pacote TypeScript a partir do código-fonte:

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

Recursos

Tudo abaixo é verificado contra o código-fonte real deste repositório, não é aspiracional.

• Detecção real de stack — linguagem (JavaScript/TypeScript, Python, sinais mais leves para Rust/Go/Ruby), gerenciador de pacotes (npm/pnpm/yarn) e contagem de pacotes em monorepo, lidos de arquivos de manifesto reais (src/agenticworkspace/scan/stack-detector.ts).
• Não destrutivo por padrão — verifica CLAUDE.md, AGENTS.md, .cursor/rules e .github/copilot-instructions.md e nunca os sobrescreve (src/agenticworkspace/scan/config-detector.ts).
• Detecta outras ferramentas de memória de agente sem tocá-las — procura por um diretório .serena/, uma configuração estilo GitNexus, ou o próprio diretório .ai/harness/ do repo-harness, relata o que encontra e nunca lê ou escreve em nenhum deles (src/agenticworkspace/memory-backends/).
• Um adaptador Claude Code real e funcional — escreve scripts de hook reais para início de sessão, pré-chamada de ferramenta e geração de transferência no fim da sessão, conectados em .workspace/adapters/claude-code/settings.json (src/agenticworkspace/adapters/claude-code/install.ts).
• Saída JSON estruturada em todo subcomando — init, scan, status, adapter install e handoff new suportam --json, inclusive em caminhos de erro (um --path inexistente, um workspace ausente, um adaptador não implementado), para que um agente chamador nunca precise analisar texto legível ou adivinhar códigos de saída.
• Duas interfaces de plugin documentadas, não um pipeline fixo — MemoryBackend (src/agenticworkspace/memory-backends/types.ts) e Adapter (src/agenticworkspace/adapters/types.ts). Adicionar uma nova ferramenta significa implementar uma interface e registrá-la (registry.ts em cada pasta); nenhuma alteração na CLI ou no código de scan é necessária. Veja Estendendo o AgenticWorkspace abaixo.
• Geração de hooks segura contra injeção de shell — todo valor escaneado (nomes de módulos, caminhos) que acaba embutido em um script de shell gerado passa primeiro por uma lista de permissões e verificação de aspas (src/agenticworkspace/util/sanitize.ts), coberto por 30 testes de unidade dedicados (confirmado ao executar a suíte diretamente, incluindo os casos de rejeição parametrizados).
• Recuperação de estado parcial — uma execução anterior interrompida ou malformada do init é detectada e exibida (prompt interativo de reparo/redefinição/abortar, ou um erro JSON estruturado com um código de saída dedicado no modo --json) em vez de ser silenciosamente sobrescrita ou retomada (src/agenticworkspace/state/partial-state.ts).

Início rápido

Uma execução real em um pequeno repositório JavaScript de dois arquivos (caminho de destino abreviado para /Users/you/my-app para legibilidade, cada valor de campo abaixo é a saída 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"
}

O campo agenticworkspace_version nessa saída é uma string de versão rastreada separadamente da versão npm/PyPI do próprio pacote (elas podem divergir; trate-o como um marcador interno de esquema, não a versão do pacote que você instalou).

Essa única execução escreveu sete arquivos reais no 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

Remova --json para uma versão legível da mesma execução:

$ 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.

Verificando a saúde do workspace e escrevendo uma transferência de sessão nesse mesmo repositório, saída 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

Veja docs/usage.gif para uma execução gravada de handoff new e status juntos.

Recursos

Tudo abaixo é verificado contra o código-fonte real deste repositório, não é aspiracional.

• Detecção real de stack — linguagem (JavaScript/TypeScript, Python, sinais mais leves para Rust/Go/Ruby), gerenciador de pacotes (npm/pnpm/yarn) e contagem de pacotes em monorepo, lidos de arquivos de manifesto reais (src/agenticworkspace/scan/stack-detector.ts).
• Não destrutivo por padrão — verifica CLAUDE.md, AGENTS.md, .cursor/rules e .github/copilot-instructions.md e nunca os sobrescreve (src/agenticworkspace/scan/config-detector.ts).
• Detecta outras ferramentas de memória de agente sem tocá-las — procura por um diretório .serena/, uma configuração estilo GitNexus, ou o próprio diretório .ai/harness/ do repo-harness, relata o que encontra e nunca lê ou escreve em nenhum deles (src/agenticworkspace/memory-backends/).
• Um adaptador Claude Code real e funcional — escreve scripts de hook reais para início de sessão, pré-chamada de ferramenta e geração de transferência no fim da sessão, conectados em .workspace/adapters/claude-code/settings.json (src/agenticworkspace/adapters/claude-code/install.ts).
• Saída JSON estruturada em todo subcomando — init, scan, status, adapter install e handoff new suportam --json, inclusive em caminhos de erro (um --path inexistente, um workspace ausente, um adaptador não implementado), para que um agente chamador nunca precise analisar texto legível ou adivinhar códigos de saída.
• Duas interfaces de plugin documentadas, não um pipeline fixo — MemoryBackend (src/agenticworkspace/memory-backends/types.ts) e Adapter (src/agenticworkspace/adapters/types.ts). Adicionar uma nova ferramenta significa implementar uma interface e registrá-la (registry.ts em cada pasta); nenhuma alteração na CLI ou no código de scan é necessária. Veja Estendendo o AgenticWorkspace abaixo.
• Geração de hooks segura contra injeção de shell — todo valor escaneado (nomes de módulos, caminhos) que acaba embutido em um script de shell gerado passa primeiro por uma lista de permissões e verificação de aspas (src/agenticworkspace/util/sanitize.ts), coberto por 30 testes de unidade dedicados.
• Recuperação de estado parcial — uma execução anterior interrompida ou malformada do init é detectada e exibida (prompt interativo de reparo/redefinição/abortar, ou um erro JSON estruturado com um código de saída dedicado no modo --json) em vez de ser silenciosamente sobrescrita ou retomada (src/agenticworkspace/state/partial-state.ts).

Referência da CLI

Todo comando aceita -p, --path <path> (padrão: o diretório atual) e --json (saída estruturada em vez do padrão legível). A referência abaixo é a saída real do --help de um binário agenticworkspace compilado localmente.

Comando	Descrição
agenticworkspace init	Escaneia o repositório e escreve o scaffold .workspace/ mais o adaptador Claude Code. Idempotente — seguro reexecutar.
agenticworkspace scan	Detecta stack e superfície de ferramentas de agente existentes apenas. Sem escrita.
agenticworkspace status	Relata a saúde do workspace: stack, uso do orçamento de contexto, contagem de transferências, desatualização do adaptador.
agenticworkspace adapter install <name>	(Re)instala a conexão de hooks de um único adaptador, ex.: claude-code. Retorna adapter_not_implemented para codex ou cursor.
agenticworkspace handoff new <message>	Escreve um novo arquivo de transferência de sessão com timestamp em .workspace/handoff/.

Os códigos de saída são estáveis entre os modos --json e legível, para que um script possa ramificar neles sem analisar texto. Verificado diretamente: adapter install codex sai com 3 e uma mensagem "NOT YET IMPLEMENTED", e status contra um alvo sem .workspace/ sai com 4.

Código	Significado
0	Sucesso
1	Erro geral (entrada inválida, falha inesperada do sistema de arquivos)
2	Estado parcial/malformado do .workspace/ detectado
3	Adaptador ainda não implementado (codex, cursor)
4	Nenhum .workspace/ encontrado (execute init primeiro)

Servidor MCP

O pacote Python inclui um servidor Model Context Protocol (MCP), para que um agente compatível com MCP (Claude Desktop, Claude Code ou qualquer outro cliente MCP) possa chamar o AgenticWorkspace como uma ferramenta em vez de invocar a CLI e analisar texto.

pip install "agenticworkspace-cli[mcp]"

Adicione-o à configuração do seu cliente MCP (transporte stdio):

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

Ele expõe uma única ferramenta, run(args: list[str]) -> dict, que invoca a CLI agenticworkspace instalada com a lista de argumentos fornecida e retorna o resultado analisado — todo subcomando (init, scan, status, adapter install, handoff new) é acessível por meio dela, então a superfície MCP nunca fica dessincronizada com a CLI conforme novos subcomandos são adicionados. Todo modo de falha (binário ausente, timeout, saída não zero, saída não analisável) retorna um dict {"error": ...} em vez de lançar exceção. Exemplo de chamada e resultado:

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

O diretório .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

Referência da API da biblioteca

Ambos os pacotes exportam sua lógica de scan/scaffold/adapter para uso programático além do binário da CLI. As assinaturas abaixo são extraídas diretamente do código-fonte.

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 e Adapter são exportados como tipos TypeScript para quem implementar um novo plugin (src/agenticworkspace/memory-backends/types.ts, src/agenticworkspace/adapters/types.ts).

Python (agenticworkspace-cli no 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 e MemoryBackend são classes abc.ABC aqui, em vez de interfaces TypeScript — implemente uma, adicione uma instância a adapter_registry ou memory_backend_registry (listas Python simples), e nenhuma alteração na CLI ou no código de scan é necessária. O pacote inclui um marcador py.typed, então verificadores de tipo reconhecem seus stubs sem configuração extra.

Status do adaptador (v0.1)

Adaptador	Status
Claude Code	Implementado, funciona de ponta a ponta
Codex	Registrado, ainda não implementado
Cursor	Registrado, ainda não implementado

Estendendo o AgenticWorkspace

O AgenticWorkspace é construído em torno de duas interfaces de plugin, não um único projeto fazendo tudo sozinho:

• MemoryBackend (src/agenticworkspace/memory-backends/types.ts) — detecta se um repositório já tem uma ferramenta de memória/contexto conectada. A detecção deve permanecer somente leitura.
• Adapter (src/agenticworkspace/adapters/types.ts) — conecta o scaffold .workspace/ a uma ferramenta de codificação específica: instalação, verificação de desatualização e uma descrição legível.

Adicionar suporte a uma nova ferramenta significa implementar uma dessas interfaces e registrar uma instância no registry.ts daquela pasta; nenhuma alteração na CLI ou no código de scan é necessária. Veja src/agenticworkspace/adapters/codex/ e .../cursor/ para a forma que um stub ainda não implementado assume (isImplemented: false mais uma string describe() real), e .../claude-code/ para uma implementação de referência totalmente funcional. O pacote Python (pip install agenticworkspace-cli) implementa as mesmas duas interfaces que as classes abc.ABC com o mesmo contrato de registro (memory_backend_registry / adapter_registry, listas Python simples) — veja docs/integrations/custom-plugin.md para um exemplo prático em ambas as linguagens.

Como isso se compara ao repo-harness e ao harnesskit

Contexto local do repositório e rastreamento de handoff de sessão para agentes de codificação não é uma ideia nova. Antes de construir isso, verificamos o que já está disponível. Dois pacotes npm cobrem áreas sobrepostas, e seu estado atual (verificado em 2026-08-03) importa mais do que qualquer afirmação nossa sobre eles:

	AgenticWorkspace v0.1.3 (npm) / v0.1.1 (PyPI)	repo-harness v0.13.0	harnesskit v0.1.1
Atividade no npm	3 versões publicadas (0.1.1 -> 0.1.3), criado em 2026-07-15, publicado mais recentemente em 2026-08-04	46 versões publicadas, criado em 2026-05-28, última publicação em 2026-08-03 (mesmo dia desta verificação)	2 versões publicadas, última publicação em 2026-03-20 (cerca de 4,5 meses desatualizado nesta verificação)
GitHub	0 estrelas, 0 forks (repositório novo)	402 estrelas, 29 forks, push em 2026-08-03	Repositório GitHub agora retorna 404, não é possível inspecionar o código-fonte
Adaptador Claude Code	Implementado de ponta a ponta: scripts de hook reais + fiação settings.json, instalado por init na mesma execução que cria o workspace	Implementado: adaptador de hook ~/.claude/settings.json	Não verificado, não foi possível inspecionar o código-fonte ou o README (a página npm bloqueou nossa busca, repositório GitHub inexistente)
Adaptador Codex	Registrado na interface do adaptador, install() lança "ainda não implementado" — stub honesto, não um no-op silencioso	Implementado: adaptador ~/.codex/hooks.json	Não verificado
Adaptador Cursor	Registrado, mesmo padrão de stub honesto do Codex	Não mencionado em lugar nenhum no README atual (uma comparação anterior encontrou referência nos documentos de arquitetura; essa referência desapareceu nesta verificação)	Não verificado
Carregamento progressivo de contexto	Arquivo de contexto raiz com orçamento-alvo (~12KB) mais blocos de capacidade por módulo, carregados sob demanda	~12KB de contexto raiz estável mais contratos de capacidade de ~1KB carregados apenas para arquivos realmente tocados, apoiados por um índice estrutural CodeGraph que não construímos	Não verificado
Arquivos de handoff de sessão	Arquivo com timestamp por sessão em handoff/	Diretório .ai/harness/handoff/ mais tasks/current.md, derivados de artefatos de workflow	Não verificado
Saída JSON da CLI	Todo subcomando (scan, status, adapter install, handoff) suporta --json, incluindo caminhos de erro	Tem saída JSON em pelo menos --dry-run --json e state-snapshot --json	Não verificado
Detecta outras ferramentas sem tocá-las	Sim: verifica .serena/, um config estilo GitNexus e o próprio diretório .ai/harness/ do repo-harness, relata o que encontra, nunca lê ou escreve em nenhum deles	Não verificado — fora do escopo do que revisamos	Não verificado
Modelo de plugin/extensão	Duas interfaces TypeScript documentadas (MemoryBackend, Adapter); adicionar uma ferramenta significa implementar uma e registrá-la, sem mudanças na CLI	Não verificado apenas pelo README; seria necessário ler o código-fonte para confirmar	Não verificado
Dashboard hospedado multi-repositório	Não existe. Não planejado como parte desta CLI OSS.	Não existe, apenas workflow auto-hospedado com arquivos	Não verificado
Idiomas da documentação	Apenas inglês	Inglês (principal), além de chinês simplificado, japonês, francês, espanhol	Não verificado

O que pudemos verificar veio de npm view, da API do GitHub e do próprio README do repo-harness (buscado diretamente). Não instalamos e executamos o repo-harness contra um repositório real nós mesmos, então qualquer coisa marcada como "implementado" para ele é uma afirmação do README que lemos, não uma afirmação que reproduzimos em primeira mão. Tudo marcado como "não verificado" para o harnesskit permaneceu assim porque seu repositório GitHub não resolve mais e sua página npm bloqueou buscas automatizadas; não vamos adivinhar o que uma ferramenta faz a partir de uma string de descrição. (Um pacote PyPI também chamado harnesskit existe, mas é um projeto diferente e não relacionado, de um autor diferente — uma ferramenta fuzzy de substituição de strings para agentes de codificação LLM — e não o estamos contando aqui.)

O escopo do próprio repo-harness cresceu desde a última vez que o verificamos: seu README agora se concentra em um sidecar de planejamento MCP dirigido por ChatGPT repassando para o Codex executar, além dos adaptadores de hook Claude/Codex que esta tabela já cobre. Isso é uma superfície materialmente maior do que "rastreamento de contexto local e handoff do repositório", e vale a pena saber antes de comparar as duas ferramentas projeto a projeto, em vez de recurso a recurso.

A leitura honesta: o repo-harness é mais maduro que o AgenticWorkspace em quase todas as dimensões nesta tabela agora. Ele já tem um adaptador Claude Code funcional, um adaptador Codex funcional e cinco idiomas de documentação. Ele tem iterado rápido (46 versões em pouco mais de dois meses). Se você já o usa e ele funciona para você, não há razão para mudar.

O que realmente construímos de diferente: uma arquitetura de plugin com duas interfaces pequenas e documentadas (MemoryBackend para detectar outras ferramentas, Adapter para integrar a um agente de codificação específico) em vez de um projeto fazendo tudo sozinho, e uma verificação de compatibilidade explícita que detecta o próprio diretório .ai/harness/ do repo-harness e o relata em vez de duplicar silenciosamente ou entrar em conflito com ele. Além disso, agora, esta é uma CLI nova e não comprovada contra uma mais estabelecida. Não vamos embelezar isso.

Mais uma coisa que vale nomear: o próprio Claude Code agora inclui um sistema de memória de primeira parte baseado em MEMORY.md e armazenamentos de memória de equipe, além de um hook de ciclo de vida post-session que pode capturar trabalho não commitado. Ele não escaneia a stack de um repositório nem instala um adaptador específico do Claude-Code da maneira que o AgenticWorkspace faz, mas a lacuna entre "o que a plataforma faz nativamente" e "o que uma ferramenta como esta adiciona" é mais estreita do que era quando esta categoria começou, e vale a pena observar antes de assumir que qualquer uma dessas ferramentas permanece necessária.

O quê e por quê

Agentes de codificação perdem contexto no momento em que uma sessão termina, e todo repositório precisa de sua própria configuração manual antes que um agente possa trabalhar bem nele: qual arquivo CLAUDE.md ou AGENTS.md escrever, como repassar trabalho parcial para a próxima sessão, quais hooks conectar. Essa configuração é repetitiva, fácil de errar e raramente mantida atualizada à medida que a stack de um projeto muda.

O AgenticWorkspace automatiza as partes dessa configuração que são mecânicas e agnósticas de repositório: descobrir qual stack um repositório usa, escrever um arquivo de contexto progressivo dimensionado para permanecer dentro de um orçamento de tokens em vez do codebase inteiro do modelo, e instalar hooks reais para que uma sessão do Claude Code gere uma nota de handoff automaticamente em vez de depender de um humano para escrevê-la. Ele não tenta ser um banco de memória, um índice semântico de código ou um dashboard hospedado. É uma CLI de scaffolding: escreve arquivos uma vez, em um formato que qualquer uma dessas outras ferramentas poderia ler ou estender depois, e então sai do caminho.

Por que construir outra dessas quando o repo-harness já existe e tem mais tração (veja a tabela de comparação acima)? Porque a resposta honesta é: não para substituí-lo. Este projeto existe para testar uma versão mais estreita, primeiro-Claude-Code, da mesma ideia com uma arquitetura de plugin que mantém código de detecção e adaptador desacoplados desde o primeiro dia, e para ser transparente em público sobre exatamente como ele se compara à ferramenta que chegou lá primeiro.

Desenvolvimento

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

99/99 testes passam a partir deste release. Antes de abrir um pull request, execute npm run lint, npm run typecheck, npm run test:coverage e npm run build — os mesmos passos que o CI executa no Node 20.x e 22.x.

Para o pacote Python em vez disso:

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

132/132 testes passam a partir do release inicial do pacote Python. Veja python/README.md para as notas de desenvolvimento específicas do Python.

FAQ

O que é o AgenticWorkspace, e o que o torna diferente de escrever um arquivo CLAUDE.md manualmente? É um conversor de repositório para workspace de agente: um único comando (agenticworkspace init) escaneia a stack de um repositório, escreve um arquivo de contexto progressivo com orçamento de tokens e instala um adaptador Claude Code funcional com scripts de hook reais, tudo em uma execução não destrutiva. O diferencial é que isso é automatizado e agnóstico de repositório, em vez de um template que você copia e edita manualmente, e é construído em torno de duas interfaces de plugin documentadas (MemoryBackend, Adapter) em vez de um pipeline fixo, então adicionar um novo adaptador de agente de codificação ou backend de memória não requer tocar na CLI ou no código de escaneamento.

Quais são os requisitos de instalação e plataforma? O pacote npm requer Node.js 20 ou posterior ("engines": { "node": ">=20.0.0" } em package.json). O pacote Python requer Python 3.9 ou posterior (requires-python = ">=3.9" em python/pyproject.toml) e é classificado como Operating System :: OS Independent no PyPI. Ambos os pacotes são Node/Python puros, sem dependências nativas ou específicas de SO; desenvolvimento e testes diários acontecem em macOS e Linux, e o Windows não foi verificado separadamente pelos mantenedores.

Isso modifica meu CLAUDE.md, AGENTS.md ou .cursor/rules existentes? Não. init verifica todos os quatro arquivos de configuração (CLAUDE.md, AGENTS.md, .cursor/rules, .github/copilot-instructions.md) e relata o que encontra, mas nunca escreve ou sobrescreve nenhum deles.

Isso entra em conflito com Serena, GitNexus ou repo-harness se eu já uso um deles? Não. A detecção é somente leitura: o AgenticWorkspace verifica .serena/, um config estilo GitNexus e o diretório .ai/harness/ do repo-harness, relata o que encontra na saída scan/status/init, e nunca lê, escreve ou exclui nada dentro deles.

Como isso realmente se compara ao repo-harness, a alternativa mais estabelecida? Veja a tabela de comparação completa acima para a análise completa e datada. Em resumo: o repo-harness é mais maduro em quase todos os eixos mensuráveis agora (mais versões publicadas, mais estrelas no GitHub, um adaptador Codex funcional, cinco idiomas de documentação e um escopo mais amplo de planejador-MCP-mais-execução-Codex). O que o AgenticWorkspace faz de diferente é uma arquitetura de plugin menor, com duas interfaces, e uma verificação de compatibilidade explícita e somente leitura para o próprio diretório .ai/harness/ do repo-harness. Se o repo-harness já funciona para você, não há razão nesta tabela para mudar.

O que acontece se init for interrompido no meio? A próxima execução de init detecta o marcador .init-in-progress restante ou um workspace.json ausente/malformado e ou solicita que você repare, redefina ou aborte (terminal interativo), ou retorna um erro JSON estruturado com código de saída 2 (modo não interativo ou --json) em vez de sobrescrever ou retomar silenciosamente.

Por que o adaptador Codex ou Cursor ainda não está implementado? Ambos estão registrados na interface de plugin Adapter com isImplemented: false e uma string describe() real e honesta em vez de um no-op silencioso. O Claude Code foi construído primeiro porque esse é o adaptador contra o qual o workflow deste próprio repositório foi construído e testado. Contribuições implementando qualquer um são bem-vindas, veja Estendendo o AgenticWorkspace.

Existe um dashboard hospedado ou um nível pago? Não neste repositório. Esta CLI é a camada gratuita, local e comparável ao MIT (Apache-2.0). Não há componente hospedado aqui para se inscrever.

Qual é a licença disso, e posso usar comercialmente? Apache License 2.0 (veja LICENSE). Ela permite uso comercial, modificação, uso privado e distribuição, e inclui uma concessão expressa de patente, sujeita à preservação da licença e do aviso de direitos autorais e sem garantia. Existe uma versão em Python? Sim — um port genuíno em Python (não um wrapper em torno do binário Node), com o mesmo formato de CLI, a mesma saída .workspace/, e o mesmo contrato de plugin MemoryBackend/Adapter, além de sua própria superfície de biblioteca importável (Adapter e MemoryBackend como classes abc.ABC). Consulte python/README.md para o passo a passo de instalação e uso específico para Python.

Contribuindo

Consulte CONTRIBUTING.md para a configuração de desenvolvimento, a lista de verificação pré-PR e instruções concretas para adicionar um novo MemoryBackend ou Adapter. Alterações sensíveis à segurança (qualquer coisa que toque em scripts shell gerados) devem passar pelo módulo de sanitização compartilhado descrito lá.

Licença

Apache 2.0. Consulte LICENSE.