{
  "markdown": "<!-- mcp-name: io.github.RudrenduPaul/agenticworkspace -->\n# AgenticWorkspace\n\n[![CI](https://github.com/RudrenduPaul/AgenticWorkspace/actions/workflows/ci.yml/badge.svg)](https://github.com/RudrenduPaul/AgenticWorkspace/actions/workflows/ci.yml)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)\n[![npm version](https://img.shields.io/npm/v/agenticworkspace-cli.svg)](https://www.npmjs.com/package/agenticworkspace-cli)\n[![Node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](./package.json)\n[![PyPI version](https://img.shields.io/pypi/v/agenticworkspace-cli.svg)](https://pypi.org/project/agenticworkspace-cli/)\n\nPoint it at any repo. It detects the stack, writes a `.workspace/` directory with progressive\ncontext and session handoffs, and installs a working Claude Code adapter, all in one command.\n\n![AgenticWorkspace init: npx agenticworkspace-cli init scans a repo and scaffolds a .workspace/ directory with a Claude Code adapter, recorded from the real published npm package](./docs/demo.gif)\n\n```bash\nnpx agenticworkspace-cli init\n```\n\nThis is a v0.1 release. Zero installs, zero GitHub stars, first release. 99/99 JavaScript tests\nand 132/132 Python tests pass. It does what's described below and nothing more. There's an\nhonest comparison against the other tools already working in this space further down, so you can\ndecide if AgenticWorkspace is actually worth trying before you run it.\n\n## Table of contents\n\n- [Install](#install)\n- [Features](#features)\n- [Quickstart](#quickstart)\n- [CLI reference](#cli-reference)\n- [The `.workspace/` directory](#the-workspace-directory)\n- [Library API reference](#library-api-reference)\n- [Adapter status](#adapter-status-v01)\n- [Extending AgenticWorkspace](#extending-agenticworkspace)\n- [How this compares to repo-harness and harnesskit](#how-this-compares-to-repo-harness-and-harnesskit)\n- [What and why](#what-and-why)\n- [Development](#development)\n- [FAQ](#faq)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Install\n\nAgenticWorkspace ships two independent, equally first-class packages that\nimplement the same scan/scaffold/adapter pipeline and read/write the same\n`.workspace/` directory shape -- pick whichever fits your toolchain, or\ninstall both. Neither is deprecated in favor of the other.\n\n```bash\n# npm -- JavaScript/TypeScript CLI + library (live today, v0.1.3)\nnpx agenticworkspace-cli init\n```\n\n```bash\n# PyPI -- Python CLI + library (live today, v0.1.1)\npip install agenticworkspace-cli\nagenticworkspace init --path /path/to/your/repo\n```\n\nTo install from source instead:\n\n```bash\ngit clone https://github.com/RudrenduPaul/AgenticWorkspace.git\ncd AgenticWorkspace/python\npip install -e .\nagenticworkspace init --path /path/to/your/repo\n```\n\nFor repeat use with the npm package, install it globally:\n\n```bash\nnpm install -g agenticworkspace-cli\nagenticworkspace init\n```\n\nThe Python package's CLI entry point is also `agenticworkspace` (e.g.\n`agenticworkspace init --path ./my-app`); see\n[`python/README.md`](./python/README.md) and\n[docs/getting-started.md](./docs/getting-started.md) for the Python-specific\nwalkthrough.\n\nTo build the TypeScript package from source instead:\n\n```bash\ngit clone https://github.com/RudrenduPaul/AgenticWorkspace.git\ncd AgenticWorkspace\nnpm install\nnpm run build\nnode dist/agenticworkspace/cli.js init\n```\n\n## Features\n\nEverything below is verified against the actual source in this repo, not aspirational.\n\n- **Real stack detection** -- language (JavaScript/TypeScript, Python, lighter-weight signals for\n  Rust/Go/Ruby), package manager (npm/pnpm/yarn), and monorepo package count, read from real\n  manifest files (`src/agenticworkspace/scan/stack-detector.ts`).\n- **Non-destructive by default** -- checks for `CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, and\n  `.github/copilot-instructions.md` and never overwrites them\n  (`src/agenticworkspace/scan/config-detector.ts`).\n- **Detects other agent-memory tooling without touching it** -- looks for a `.serena/` directory, a\n  GitNexus-style config, or repo-harness's own `.ai/harness/` directory, reports what it finds, and\n  never reads or writes any of them (`src/agenticworkspace/memory-backends/`).\n- **A real, working Claude Code adapter** -- writes actual hook scripts for session start,\n  pre-tool-call, and session-end handoff generation, wired into\n  `.workspace/adapters/claude-code/settings.json`\n  (`src/agenticworkspace/adapters/claude-code/install.ts`).\n- **Structured JSON output on every subcommand** -- `init`, `scan`, `status`, `adapter install`, and\n  `handoff new` all support `--json`, including on error paths (a nonexistent `--path`, a missing\n  workspace, an unimplemented adapter), so a calling agent never has to parse human-readable text\n  or guess at exit codes.\n- **Two documented plugin interfaces, not a hardcoded pipeline** -- `MemoryBackend`\n  (`src/agenticworkspace/memory-backends/types.ts`) and `Adapter`\n  (`src/agenticworkspace/adapters/types.ts`). Adding a new tool means implementing one interface\n  and registering it (`registry.ts` in each folder); no changes to CLI or scan code are required.\n  See [Extending AgenticWorkspace](#extending-agenticworkspace) below.\n- **Shell-injection-safe hook generation** -- every scanned value (module names, paths) that ends\n  up embedded in a generated shell script passes through an allowlist and quoting check first\n  (`src/agenticworkspace/util/sanitize.ts`), covered by 30 dedicated unit tests (confirmed by\n  running the suite directly, including the parameterized rejection cases).\n- **Partial-state recovery** -- an interrupted or malformed prior `init` run is detected and\n  surfaced (interactive repair/reset/abort prompt, or a structured JSON error with a dedicated exit\n  code in `--json` mode) instead of being silently overwritten or resumed\n  (`src/agenticworkspace/state/partial-state.ts`).\n## Quickstart\n\nA real run against a small two-file JavaScript repo (target path shortened to `/Users/you/my-app`\nfor readability, every field value below is the actual output):\n\n```bash\n$ agenticworkspace init --json --path ./my-app\n\n{\n  \"ok\": true,\n  \"agenticworkspace_version\": \"0.1.1\",\n  \"scanned_at\": \"2026-08-04T06:18:25.620Z\",\n  \"target\": \"/Users/you/my-app\",\n  \"stack\": {\n    \"language\": \"javascript\",\n    \"package_manager\": \"npm\",\n    \"monorepo\": false,\n    \"packages\": 1\n  },\n  \"existing_config\": {\n    \"claudeMd\": false,\n    \"agentsMd\": false,\n    \"cursorRules\": false,\n    \"copilotInstructions\": false,\n    \"anyDetected\": false\n  },\n  \"memory_backends\": [\n    { \"name\": \"serena\", \"detected\": false, \"description\": \"Serena memory/context tool (.serena/ directory)\" },\n    { \"name\": \"gitnexus\", \"detected\": false, \"description\": \"GitNexus-style config (.gitnexus/ or gitnexus.config.json)\" },\n    { \"name\": \"repo-harness\", \"detected\": false, \"description\": \"repo-harness (.ai/harness/ directory) -- detected only, never modified\" }\n  ],\n  \"context\": { \"root_context_kb\": 0.6, \"budget_kb\": 12, \"modules\": [] },\n  \"adapters\": { \"claude_code\": { \"installed\": true, \"hook_schema_version\": \"2026-07-01\" } },\n  \"workspace_dir\": \"/Users/you/my-app/.workspace\"\n}\n```\n\nThe `agenticworkspace_version` field in that output is a version string tracked separately from\nthe package's own npm/PyPI version (they can drift; treat it as an internal schema marker, not the\npackage version you installed).\n\nThat single run wrote seven real files on disk:\n\n```\n.workspace/workspace.json\n.workspace/context/root-context.md\n.workspace/adapters/claude-code/settings.json\n.workspace/adapters/claude-code/adapter-meta.json\n.workspace/adapters/claude-code/hooks/session-start.sh\n.workspace/adapters/claude-code/hooks/pre-tool-call.sh\n.workspace/adapters/claude-code/hooks/session-end-handoff.sh\n```\n\nDrop `--json` for a human-readable version of the same run:\n\n```bash\n$ agenticworkspace init --path ./my-app\n\nAgenticWorkspace v0.1 -- Repo-to-Agent-Workspace Converter\nTarget: /Users/you/my-app\n\nScanning repository...\n[OK] Stack detected: javascript, npm\n[--] No existing agent-config files found\n[--] No memory/context tool detected\n\nWriting .workspace/ scaffold...\n  .workspace/workspace.json                created\n  .workspace/context/root-context.md        created (0.6KB of 12KB budget)\n  .workspace/handoff/                       created (empty, ready for first session)\n\nInstalling Claude Code adapter...\n  .workspace/adapters/claude-code/settings.json         written\n  .workspace/adapters/claude-code/hooks/session-start.sh  written\n  .workspace/adapters/claude-code/hooks/pre-tool-call.sh  written\n  .workspace/adapters/claude-code/hooks/session-end-handoff.sh  written\n\nWorkspace ready. Next Claude Code session in this repo will load root-context.md automatically\nand write a handoff file on exit.\n```\n\nChecking workspace health and writing a session handoff on that same repo, real output:\n\n```bash\n$ agenticworkspace status --path ./my-app\n\nAgenticWorkspace status\nTarget: /Users/you/my-app\nLast scan: 2026-08-04T06:18:25.620Z\n\nStack: javascript, npm, 1 package(s)\nContext budget: 0.6KB of 12KB (0 module block(s))\nHandoffs: 0 file(s), most recent: none\nClaude Code adapter: installed, schema 2026-07-01, current\nOther backends detected: none\n\n$ agenticworkspace handoff new \"test session\" --path ./my-app\n\nHandoff written: .workspace/handoff/2026-08-04-0618.md\n```\n\nSee [docs/usage.gif](./docs/usage.gif) for a recorded run of `handoff new` and `status` together.\n\n## Features\n\nEverything below is verified against the actual source in this repo, not aspirational.\n\n- **Real stack detection** -- language (JavaScript/TypeScript, Python, lighter-weight signals for\n  Rust/Go/Ruby), package manager (npm/pnpm/yarn), and monorepo package count, read from real\n  manifest files (`src/agenticworkspace/scan/stack-detector.ts`).\n- **Non-destructive by default** -- checks for `CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, and\n  `.github/copilot-instructions.md` and never overwrites them\n  (`src/agenticworkspace/scan/config-detector.ts`).\n- **Detects other agent-memory tooling without touching it** -- looks for a `.serena/` directory, a\n  GitNexus-style config, or repo-harness's own `.ai/harness/` directory, reports what it finds, and\n  never reads or writes any of them (`src/agenticworkspace/memory-backends/`).\n- **A real, working Claude Code adapter** -- writes actual hook scripts for session start,\n  pre-tool-call, and session-end handoff generation, wired into\n  `.workspace/adapters/claude-code/settings.json`\n  (`src/agenticworkspace/adapters/claude-code/install.ts`).\n- **Structured JSON output on every subcommand** -- `init`, `scan`, `status`, `adapter install`, and\n  `handoff new` all support `--json`, including on error paths (a nonexistent `--path`, a missing\n  workspace, an unimplemented adapter), so a calling agent never has to parse human-readable text\n  or guess at exit codes.\n- **Two documented plugin interfaces, not a hardcoded pipeline** -- `MemoryBackend`\n  (`src/agenticworkspace/memory-backends/types.ts`) and `Adapter`\n  (`src/agenticworkspace/adapters/types.ts`). Adding a new tool means implementing one interface\n  and registering it (`registry.ts` in each folder); no changes to CLI or scan code are required.\n  See [Extending AgenticWorkspace](#extending-agenticworkspace) below.\n- **Shell-injection-safe hook generation** -- every scanned value (module names, paths) that ends\n  up embedded in a generated shell script passes through an allowlist and quoting check first\n  (`src/agenticworkspace/util/sanitize.ts`), covered by 30 dedicated unit tests.\n- **Partial-state recovery** -- an interrupted or malformed prior `init` run is detected and\n  surfaced (interactive repair/reset/abort prompt, or a structured JSON error with a dedicated exit\n  code in `--json` mode) instead of being silently overwritten or resumed\n  (`src/agenticworkspace/state/partial-state.ts`).\n\n## CLI reference\n\nEvery command accepts `-p, --path <path>` (defaults to the current directory) and `--json`\n(structured output instead of the human-readable default). Reference below is the actual\n`--help` output from a locally built `agenticworkspace` binary.\n\n| Command | Description |\n|---|---|\n| `agenticworkspace init` | Scan the repo and write the `.workspace/` scaffold plus the Claude Code adapter. Idempotent -- safe to re-run. |\n| `agenticworkspace scan` | Detect stack and existing agent-tooling surface only. No writes. |\n| `agenticworkspace status` | Report workspace health: stack, context budget usage, handoff count, adapter staleness. |\n| `agenticworkspace adapter install <name>` | (Re)install a single adapter's hook wiring, e.g. `claude-code`. Returns `adapter_not_implemented` for `codex` or `cursor`. |\n| `agenticworkspace handoff new <message>` | Write a new timestamped session handoff file under `.workspace/handoff/`. |\n\nExit codes are stable across `--json` and human-readable modes, so a script can branch on them\nwithout parsing text. Verified directly: `adapter install codex` exits `3` with a \"NOT YET\nIMPLEMENTED\" message, and `status` against a target with no `.workspace/` exits `4`.\n\n| Code | Meaning |\n|---|---|\n| `0` | Success |\n| `1` | General error (bad input, unexpected filesystem failure) |\n| `2` | Partial/malformed `.workspace/` state detected |\n| `3` | Adapter not yet implemented (`codex`, `cursor`) |\n| `4` | No `.workspace/` found (run `init` first) |\n\n## MCP Server\n\nThe Python package ships a Model Context Protocol (MCP) server, so an MCP-capable agent (Claude\nDesktop, Claude Code, or any other MCP client) can call AgenticWorkspace as a tool instead of\nshelling out to the CLI and parsing text itself.\n\n```bash\npip install \"agenticworkspace-cli[mcp]\"\n```\n\nAdd it to your MCP client config (stdio transport):\n\n```json\n{\n  \"mcpServers\": {\n    \"agenticworkspace\": {\n      \"command\": \"agenticworkspace-mcp\"\n    }\n  }\n}\n```\n\nIt exposes a single tool, `run(args: list[str]) -> dict`, that shells out to the installed\n`agenticworkspace` CLI with the given argument list and returns its parsed result -- every\nsubcommand (`init`, `scan`, `status`, `adapter install`, `handoff new`) is reachable through it, so\nthe MCP surface never drifts out of sync with the CLI as new subcommands are added. Every failure\nmode (missing binary, timeout, non-zero exit, unparsable output) comes back as a `{\"error\": ...}`\ndict instead of raising. Example call and result:\n\n```\nrun([\"scan\", \"--json\", \"--path\", \"/path/to/repo\"])\n-> {\"ok\": true, \"target\": \"/path/to/repo\", \"stack\": {\"language\": \"javascript\", ...}, ...}\n```\n\n## The `.workspace/` directory\n\n```\n.workspace/\n  workspace.json              manifest: detected stack, adapters installed, schema version\n  context/\n    root-context.md           progressive root context, budget-targeted (~12KB)\n    modules/\n      auth.md                 per-module capability block, loaded on demand\n      api.md\n  handoff/\n    2026-07-13-1421.md         one file per session, timestamped\n  adapters/\n    claude-code/\n      settings.json           hook entries wired into Claude Code's settings schema\n      hooks/\n        session-start.sh       loads root-context.md + relevant module blocks\n        pre-tool-call.sh        lightweight guard, extendable per project\n        session-end-handoff.sh writes the next handoff/ file automatically\n```\n\n## Library API reference\n\nBoth packages export their scan/scaffold/adapter logic for programmatic use in addition to the\nCLI binary. Signatures below are grepped directly from source.\n\n### TypeScript (`agenticworkspace-cli`, `src/agenticworkspace/index.ts`)\n\n```typescript\nimport {\n  detectStack,\n  detectExistingConfig,\n  memoryBackendRegistry,\n  detectAllMemoryBackends,\n  adapterRegistry,\n  getAdapter,\n  runInitEngine,\n  readManifest,\n  writeManifest,\n  sanitizeForShellEmbedding,\n  validateAgainstAllowlist,\n  shellQuote,\n} from \"agenticworkspace-cli\";\n\nasync function detectStack(repoPath: string): Promise<StackDetectionResult>;\nasync function detectExistingConfig(repoPath: string): Promise<ExistingConfigResult>;\nasync function runInitEngine(repoPath: string, workspaceDir: string): Promise<InitEngineResult>;\nfunction getAdapter(name: string): Adapter | undefined;\nasync function readManifest(workspaceDir: string): Promise<WorkspaceManifest | null>;\nasync function writeManifest(workspaceDir: string, manifest: WorkspaceManifest): Promise<void>;\nfunction sanitizeForShellEmbedding(\n  rawValue: unknown,\n  warn?: SanitizeWarning,\n  options?: SanitizeForShellOptions,\n): string | null;\nfunction validateAgainstAllowlist(rawValue: unknown): SanitizeResult;\nfunction shellQuote(value: string): string;\n```\n\n`MemoryBackend` and `Adapter` are exported as TypeScript types for anyone implementing a new\nplugin (`src/agenticworkspace/memory-backends/types.ts`, `src/agenticworkspace/adapters/types.ts`).\n\n### Python (`agenticworkspace-cli` on PyPI, `python/src/agenticworkspace/__init__.py`)\n\n```python\nfrom agenticworkspace import (\n    adapter_registry,\n    get_adapter,\n    memory_backend_registry,\n    detect_all_memory_backends,\n    Adapter,\n    MemoryBackend,\n    AGENTICWORKSPACE_VERSION,\n)\n```\n\n`Adapter` and `MemoryBackend` are `abc.ABC` classes here rather than TypeScript interfaces --\nimplement one, add an instance to `adapter_registry` or `memory_backend_registry` (plain Python\nlists), and no CLI or scan code changes are required. The package ships a `py.typed` marker, so\ntype checkers pick up its stubs without extra configuration.\n\n## Adapter status (v0.1)\n\n| Adapter | Status |\n|---|---|\n| Claude Code | Implemented, works end to end |\n| Codex | Registered, not yet implemented |\n| Cursor | Registered, not yet implemented |\n\n![AgenticWorkspace adapter management: installing and inspecting the Claude Code adapter's hook wiring via the adapter subcommand, recorded from the real published npm package](./docs/demo-adapters.gif)\n\n## Extending AgenticWorkspace\n\nAgenticWorkspace is built around two plugin interfaces, not one project doing everything itself:\n\n- `MemoryBackend` (`src/agenticworkspace/memory-backends/types.ts`) -- detects whether a repo\n  already has a memory/context tool wired in. Detection must stay read-only.\n- `Adapter` (`src/agenticworkspace/adapters/types.ts`) -- wires the `.workspace/` scaffold into a\n  specific coding tool: install, staleness check, and a human-readable description.\n\nAdding support for a new tool means implementing one of these interfaces and registering an\ninstance in that folder's `registry.ts`; no changes to the CLI or scan code are required. See\n`src/agenticworkspace/adapters/codex/` and `.../cursor/` for the shape a not-yet-implemented stub\ntakes (`isImplemented: false` plus a real `describe()` string), and `.../claude-code/` for a fully\nworking reference implementation.\n\nThe Python package (`pip install agenticworkspace-cli`) implements the same two interfaces as\n`abc.ABC` classes with the same registration contract (`memory_backend_registry` /\n`adapter_registry`, plain Python lists) -- see\n[docs/integrations/custom-plugin.md](./docs/integrations/custom-plugin.md) for a worked example in\nboth languages.\n\n## How this compares to repo-harness and harnesskit\n\nRepo-local context and session-handoff tracking for coding agents is not a new idea. Before\nbuilding this, we checked what's already shipping. Two npm packages cover overlapping ground, and\ntheir current state (checked 2026-08-03) matters more than any of our own claims about them:\n\n| | **AgenticWorkspace** v0.1.3 (npm) / v0.1.1 (PyPI) | **repo-harness** v0.13.0 | **harnesskit** v0.1.1 |\n|---|---|---|---|\n| npm activity | 3 published versions (0.1.1 -> 0.1.3), created 2026-07-15, most recently published 2026-08-04 | 46 published versions, created 2026-05-28, last published 2026-08-03 (same day as this check) | 2 published versions, last published 2026-03-20 (about 4.5 months stale as of this check) |\n| GitHub | 0 stars, 0 forks (new repo) | 402 stars, 29 forks, pushed 2026-08-03 | GitHub repo now returns 404, cannot inspect source |\n| Claude Code adapter | Implemented end to end: real hook scripts + `settings.json` wiring, installed by `init` in the same run that creates the workspace | Implemented: `~/.claude/settings.json` hook adapter | Unverified, could not inspect source or README (npm page blocked our fetch, GitHub repo gone) |\n| Codex adapter | Registered in the adapter interface, `install()` throws \"not yet implemented\" -- honest stub, not a silent no-op | Implemented: `~/.codex/hooks.json` adapter | Unverified |\n| Cursor adapter | Registered, same honest-stub pattern as Codex | Not mentioned anywhere in the current README (a prior comparison found it referenced in architecture docs; that reference is gone as of this check) | Unverified |\n| Progressive context loading | Budget-targeted root context file (~12KB) plus per-module capability blocks, loaded on demand | ~12KB stable root context plus ~1KB capability contracts loaded only for files actually being touched, backed by a CodeGraph structural index we do not build | Unverified |\n| Session handoff files | Timestamped file per session under `handoff/` | `.ai/harness/handoff/` directory plus `tasks/current.md`, derived from workflow artifacts | Unverified |\n| CLI JSON output | Every subcommand (`scan`, `status`, `adapter install`, `handoff`) supports `--json`, including error paths | Has JSON output on at least `--dry-run --json` and `state-snapshot --json` | Unverified |\n| Detects other tools without touching them | Yes: checks for `.serena/`, a GitNexus-style config, and repo-harness's own `.ai/harness/` directory, reports what it finds, never reads or writes any of them | Not checked -- outside scope of what we reviewed | Unverified |\n| Plugin/extension model | Two documented TypeScript interfaces (`MemoryBackend`, `Adapter`); adding a tool means implementing one and registering it, no CLI changes needed | Not verified from the README alone; would need to read source to confirm | Unverified |\n| Hosted multi-repo dashboard | Does not exist. Not planned as part of this OSS CLI. | Does not exist, self-hosted file-backed workflow only | Unverified |\n| Documentation languages | English only | English (primary), plus Simplified Chinese, Japanese, French, Spanish | Unverified |\n\nWhat we could verify came from `npm view`, the GitHub API, and repo-harness's own README (fetched\ndirectly). We did not install and run repo-harness against a real repo ourselves, so anything\nmarked \"implemented\" for it is a README claim we read, not a claim we reproduced firsthand.\nEverything marked \"unverified\" for harnesskit stayed that way because its GitHub repository no\nlonger resolves and its npm page blocked automated fetches; we are not going to guess at what a\ntool does from a description string. (A PyPI package also named `harnesskit` exists, but it is a\ndifferent, unrelated project by a different author -- a fuzzy string-replace tool for LLM coding\nagents -- and we are not counting it here.)\n\nrepo-harness's own scope has grown since we last checked it: its README now centers on a\nChatGPT-driven MCP planning sidecar handing off to Codex for execution, on top of the\nClaude/Codex hook adapters this table already covers. That is a materially bigger surface than\n\"repo-local context and handoff tracking,\" and worth knowing before you compare the two tools\nproject-to-project rather than feature-to-feature.\n\nThe honest read: repo-harness is more mature than AgenticWorkspace on almost every dimension in\nthis table right now. It already has a working Claude Code adapter, a working Codex adapter, and\nfive languages of documentation. It has been iterating fast (46 versions in a little over two\nmonths). If you already use it and it works for you, there's no reason to switch.\n\nWhat we actually built differently: a plugin architecture with two small, documented interfaces\n(`MemoryBackend` for detecting other tools, `Adapter` for wiring into a specific coding agent)\ninstead of one project doing everything itself, and an explicit compatibility check that detects\nrepo-harness's own `.ai/harness/` directory and reports it rather than silently duplicating or\nconflicting with it. Beyond that, right now, this is a new, unproven CLI going up against a more\nestablished one. We're not going to dress that up.\n\nOne more thing worth naming: Claude Code itself now ships a first-party `MEMORY.md`-based memory\nsystem and team memory stores, plus a `post-session` lifecycle hook that can snapshot uncommitted\nwork. It doesn't scan a repo's stack or install a Claude-Code-specific adapter the way\nAgenticWorkspace does, but the gap between \"what the platform does natively\" and \"what a tool like\nthis adds\" is narrower than it was when this category started, and it's worth watching before\nassuming any of this tooling stays necessary.\n\n## What and why\n\nCoding agents lose context the moment a session ends, and every repo needs its own manual setup\nbefore an agent can work in it well: what CLAUDE.md or AGENTS.md file to write, how to hand off\npartial work to the next session, which hooks to wire up. That setup is repetitive, easy to get\nwrong, and rarely kept up to date as a project's stack changes.\n\nAgenticWorkspace automates the parts of that setup that are mechanical and repo-agnostic: figuring\nout what stack a repo uses, writing a progressive context file sized to stay inside a token budget\ninstead of the model's entire codebase, and installing real hooks so a Claude Code session\ngenerates a handoff note automatically instead of relying on a human to write one down. It does not\ntry to be a memory database, a semantic code index, or a hosted dashboard. It is a scaffolding CLI:\nit writes files once, in a format any of those other tools could later read or extend, and then\ngets out of the way.\n\nWhy build another one of these when repo-harness already exists and has more traction (see the\ncomparison table above)? Because the honest answer is: not to displace it. This project exists to\ntest a narrower, Claude-Code-first version of the same idea with a plugin architecture that keeps\ndetection and adapter code decoupled from day one, and to be upfront in public about exactly how it\nstacks up against the tool that got there first.\n\n## Development\n\n```bash\ngit clone https://github.com/RudrenduPaul/AgenticWorkspace.git\ncd AgenticWorkspace\nnpm install\nnpm run build\nnpm test\n```\n\n99/99 tests pass as of this release. Before opening a pull request, run `npm run lint`,\n`npm run typecheck`, `npm run test:coverage`, and `npm run build` -- the same steps CI runs on\nNode 18.x and 20.x.\n\nFor the Python package instead:\n\n```bash\ncd python\npython3 -m venv .venv && source .venv/bin/activate\npip install -e \".[dev]\"\npytest\n```\n\n132/132 tests pass as of the Python package's initial release. See\n[`python/README.md`](./python/README.md) for the Python-specific development notes.\n\n## FAQ\n\n**What is AgenticWorkspace, and what makes it different from writing a CLAUDE.md file by hand?**\nIt is a repo-to-agent-workspace converter: a single command (`agenticworkspace init`) scans a\nrepo's stack, writes a progressive, token-budgeted context file, and installs a working Claude\nCode adapter with real hook scripts, all in one non-destructive run. The differentiator is that\nthis is automated and repo-agnostic rather than a template you copy and edit by hand, and it is\nbuilt around two documented plugin interfaces (`MemoryBackend`, `Adapter`) instead of one\nhardcoded pipeline, so adding a new coding-agent adapter or memory backend does not require\ntouching the CLI or scan code.\n\n**What are the install and platform requirements?**\nThe npm package requires Node.js 18 or later (`\"engines\": { \"node\": \">=18.0.0\" }` in\n`package.json`). The Python package requires Python 3.9 or later (`requires-python = \">=3.9\"` in\n`python/pyproject.toml`) and is classified `Operating System :: OS Independent` on PyPI. Both\npackages are plain Node/Python with no native or OS-specific dependencies; day-to-day development\nand testing happen on macOS and Linux, and Windows has not been separately verified by the\nmaintainers.\n\n**Does this modify my existing CLAUDE.md, AGENTS.md, or .cursor/rules?**\nNo. `init` checks for all four config files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`,\n`.github/copilot-instructions.md`) and reports what it finds, but never writes to or overwrites any\nof them.\n\n**Does this conflict with Serena, GitNexus, or repo-harness if I already use one of them?**\nNo. Detection is read-only: AgenticWorkspace checks for `.serena/`, a GitNexus-style config, and\nrepo-harness's `.ai/harness/` directory, reports what it finds in `scan`/`status`/`init` output, and\nnever reads, writes, or deletes anything inside them.\n\n**How does this actually compare to repo-harness, the most established alternative?**\nSee the [full comparison table](#how-this-compares-to-repo-harness-and-harnesskit) above for the\ncomplete, dated breakdown. In short: repo-harness is more mature on almost every measurable axis\nright now (more published versions, more GitHub stars, a working Codex adapter, five documentation\nlanguages, and a broader MCP-planner-plus-Codex-execution scope). What AgenticWorkspace does\ndifferently is a smaller, two-interface plugin architecture and an explicit, read-only\ncompatibility check for repo-harness's own `.ai/harness/` directory. If repo-harness already works\nfor you, there is no reason in this table to switch.\n\n**What happens if `init` gets interrupted halfway through?**\nThe next `init` run detects the leftover `.init-in-progress` marker or a missing/malformed\n`workspace.json` and either prompts you to repair, reset, or abort (interactive terminal), or\nreturns a structured JSON error with exit code `2` (non-interactive or `--json` mode) instead of\nsilently overwriting or resuming.\n\n**Why isn't the Codex or Cursor adapter implemented yet?**\nBoth are registered in the `Adapter` plugin interface with `isImplemented: false` and a real, honest\n`describe()` string rather than a silent no-op. Claude Code was built first because that is the\nadapter this repo's own workflow was built and tested against. Contributions implementing either are\nwelcome, see [Extending AgenticWorkspace](#extending-agenticworkspace).\n\n**Is there a hosted dashboard or paid tier?**\nNot in this repository. This CLI is the free, local, MIT-comparable (Apache-2.0) layer. There is no\nhosted component here to sign up for.\n\n**What license is this, and can I use it commercially?**\nApache License 2.0 (see [LICENSE](./LICENSE)). It permits commercial use, modification, private\nuse, and distribution, and includes an express patent grant, subject to preserving the license and\ncopyright notice and carrying no warranty.\n\n**Is there a Python version?**\nYes -- a genuine Python port (not a wrapper around the Node binary), with the same CLI shape, the\nsame `.workspace/` output, and the same `MemoryBackend`/`Adapter` plugin contract, plus its own\nimportable library surface (`Adapter` and `MemoryBackend` as `abc.ABC` classes). See\n[`python/README.md`](./python/README.md) for the Python-specific install and usage walkthrough.\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for the development setup, the pre-PR checklist, and\nconcrete instructions for adding a new `MemoryBackend` or `Adapter`. Security-sensitive changes\n(anything that touches generated shell scripts) must go through the shared sanitization module\ndescribed there.\n\n## License\n\nApache 2.0. See [LICENSE](./LICENSE).\n",
  "bytes": 31515,
  "sha": "cef8f4d999b38bfefbf488a2858fe5d26beb42db1d3e371ddaaa7caab893057a",
  "repo_slug": "rudrendupaul/agenticworkspace",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rudrendupaul_agenticworkspace_af5ed7de/readme"
}