Agenticworkspace

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.

• 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.
• 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).

CLI reference

Every command accepts -p, --path (defaults to the cur