AgenticWorkspace

Point it at any repo. It detects the stack, writes a .workspace/ directory with progressive context and session handoffs, and installs a working Claude Code adapter, all in one command.

npx agenticworkspace-cli init

This is a v0.1 release. Zero installs, zero GitHub stars, first release. 99/99 JavaScript tests and 132/132 Python tests pass. It does what's described below and nothing more. There's an honest comparison against the other tools already working in this space further down, so you can decide if AgenticWorkspace is actually worth trying before you run it.

Table of contents

• Install
• Features
• Quickstart
• CLI reference
• The .workspace/ directory
• Library API reference
• Adapter status
• Extending AgenticWorkspace
• How this compares to repo-harness and harnesskit
• What and why
• Development
• FAQ
• Contributing
• License

Install

AgenticWorkspace ships two independent, equally first-class packages that implement the same scan/scaffold/adapter pipeline and read/write the same .workspace/ directory shape -- pick whichever fits your toolchain, or install both. Neither is deprecated in favor of the other.

# 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

To install from source instead:

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

For repeat use with the npm package, install it globally:

npm install -g agenticworkspace-cli
agenticworkspace init

The Python package's CLI entry point is also agenticworkspace (e.g. agenticworkspace init --path ./my-app); see python/README.md and docs/getting-started.md for the Python-specific walkthrough.

To build the TypeScript package from source instead:

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

Features

Everything below is verified against the actual source in this repo, not aspirational.

• Real stack detection -- language (JavaScript/TypeScript, Python, lighter-weight signals for Rust/Go/Ruby), package manager (npm/pnpm/yarn), and monorepo package count, read from real manifest files (src/agenticworkspace/scan/stack-detector.ts).
• Non-destructive by default -- checks for CLAUDE.md, AGENTS.md, .cursor/rules, and .github/copilot-instructions.md and never overwrites them (src/agenticworkspace/scan/config-detector.ts).
• Detects other agent-memory tooling without touching it -- looks for a .serena/ directory, a GitNexus-style config, or repo-harness's own .ai/harness/ directory, reports what it finds, and never reads or writes any of them (src/agenticworkspace/memory-backends/).
• A real, working Claude Code adapter -- writes actual hook scripts for session start, pre-tool-call, and session-end handoff generation, wired into .workspace/adapters/claude-code/settings.json (src/agenticworkspace/adapters/claude-code/install.ts).
• Structured JSON output on every subcommand -- init, scan, status, adapter install, and handoff new all support --json, including on error paths (a nonexistent --path, a missing workspace, an unimplemented adapter), so a calling agent never has to parse human-readable text or guess at exit codes.
• Two documented plugin interfaces, not a hardcoded pipeline -- MemoryBackend (src/agenticworkspace/memory-backends/types.ts) and Adapter (src/agenticworkspace/adapters/types.ts). Adding a new tool means implementing one interface and registering it (registry.ts in each folder); no changes to CLI or scan code are required. See Extending AgenticWorkspace below.
• Shell-injection-safe hook generation -- every scanned value (module names, paths) that ends up embedded in a generated shell script passes through an allowlist and quoting check first (src/agenticworkspace/util/sanitize.ts), covered by 30 dedicated unit tests (confirmed by running the suite directly, including the parameterized rejection cases).
• Partial-state recovery -- an interrupted or malformed prior init run is detected and surfaced (interactive repair/reset/abort prompt, or a structured JSON error with a dedicated exit code in --json mode) instead of being silently overwritten or resumed (src/agenticworkspace/state/partial-state.ts).

Quickstart

A real run against a small two-file JavaScript repo (target path shortened to /Users/you/my-app for readability, every field value below is the actual output):

$ 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"
}

The agenticworkspace_version field in that output is a version string tracked separately from the package's own npm/PyPI version (they can drift; treat it as an internal schema marker, not the package version you installed).

That single run wrote seven real files on disk:

.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

Drop --json for a human-readable version of the same run:

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

Checking workspace health and writing a session handoff on that same repo, real output:

$ 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

See docs/usage.gif for a recorded run of handoff new and status together.

Features

Everything below is verified against the actual source in this repo, not aspirational.

Read the full README on GitHub →