agenticworkspace-cli 0.1.1

CLI that converts any repo into an agent-ready workspace: detects your stack, scaffolds progressive context and session handoffs, installs a real Claude Code adapter. Extensible plugin architecture for memory backends and coding-agent adapters.

agenticworkspace-cli (Python)

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.

Why this exists

Coding agents lose context the moment a session ends, and every repo needs its own manual setup before an agent can work in it well: what CLAUDE.md or AGENTS.md file to write, how to hand off partial work to the next session, which hooks to wire up. AgenticWorkspace automates the mechanical, repo-agnostic parts of that setup: detecting what stack a repo uses, writing a progressive context file sized to stay inside a token budget, and installing real hooks so a Claude Code session generates a handoff note automatically. This package is the Python distribution -- a genuine, independent port, not a wrapper around the Node binary.

Install

Not yet live on PyPI. This Python package is built, tested (132/132 pytest tests passing), and verified end-to-end from a real built wheel in a fresh virtualenv -- publishing itself is blocked by PyPI's own new-project-creation anti-abuse rate limit (429 Too many new projects created) on this account, confirmed across two upload attempts. That is an account-level PyPI throttle, not a problem with this code; it will be retried once the limit clears. Until then:

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

Once published, the intended install is:

pip install agenticworkspace-cli

or with uv:

uv add agenticworkspace-cli

The npm package (agenticworkspace-cli, TypeScript) is unaffected and already live -- see Install in the project README.

The complementary JS/TS distribution installs the same way on the npm side: npx agenticworkspace-cli init (no install needed) or npm install -g agenticworkspace-cli -- see the project README for that package. Both are first-class, maintained together; neither is deprecated in favor of the other.

Quickstart

agenticworkspace init --path ./my-app

Real output against a small JavaScript repo:

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.

Add --json for structured output any calling agent can parse directly:

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

Or call the library directly (the agent-native path):

from agenticworkspace import detect_stack, run_init_engine

stack = detect_stack("./my-app")
print(stack.language, stack.package_manager, stack.monorepo.is_monorepo)

result = run_init_engine("./my-app", "./my-app/.workspace")
print(result.manifest["context"]["rootContextKb"], "KB of root context written")

CLI reference

Every command accepts -p, --path <path> (defaults to the current directory) and --json (structured output instead of the human-readable default).

Command	Description
agenticworkspace init	Scan the repo and write the .workspace/ scaffold plus the Claude Code adapter. Idempotent -- safe to re-run.
agenticworkspace scan	Detect stack and existing agent-tooling surface only. No writes.
agenticworkspace status	Report workspace health: stack, context budget usage, handoff count, adapter staleness.
agenticworkspace adapter install <name>	(Re)install a single adapter's hook wiring, e.g. claude-code. Returns exit code 3 for codex or cursor (not yet implemented).
agenticworkspace handoff new <message>	Write a new timestamped session handoff file under .workspace/handoff/.

Exit codes are stable across --json and human-readable modes:

Code	Meaning
0	Success
1	General error (bad input, unexpected filesystem failure)
2	Partial/malformed .workspace/ state detected
3	Adapter not yet implemented (codex, cursor)
4	No .workspace/ found (run init first)

How it works

target path -> stack detector + config detector + memory-backend registry
   -> module candidate detection (monorepo packages, or src/* subdirectories)
   -> progressive context generation (~12KB root-context.md budget)
   -> Claude Code adapter install (sanitized hook scripts + settings.json)
   -> workspace.json manifest written

Every scanned value (module names) that ends up embedded into a generated shell script passes through an allowlist check plus POSIX shell quoting first (agenticworkspace/util/sanitize.py) -- see docs/concepts.md for the full pipeline and the two plugin interfaces (MemoryBackend, Adapter) this package reimplements as genuine Python code.

Extending AgenticWorkspace

Two documented plugin interfaces, reimplemented faithfully from the TypeScript original's contract:

• MemoryBackend (agenticworkspace.memory_backends.types.MemoryBackend) -- detects whether a repo already has a memory/context tool wired in. Detection must stay read-only.
• Adapter (agenticworkspace.adapters.types.Adapter) -- wires the .workspace/ scaffold into a specific coding tool: install, staleness check, and a human-readable description.

Add support for a new tool by implementing one of these abc.ABC classes and appending an instance to that package's registry list (memory_backend_registry or adapter_registry) -- no changes to the CLI or scan code are required, same extension contract the npm package documents. See docs/integrations/custom-plugin.md for a worked example.

Adapter status (v0.1)

Adapter	Status
Claude Code	Implemented, works end to end
Codex	Registered, not yet implemented
Cursor	Registered, not yet implemented

Security

The plugin-loading mechanism in both distributions is a real code-execution surface worth naming plainly: a MemoryBackend or Adapter you register runs as regular imported Python code with your process's full permissions -- AgenticWorkspace does not sandbox plugins, the same way it does not sandbox the target repo's own source files it reads during detection. Only register plugins you trust the source of, same as any other Python import. Detection logic in every first-party backend is read-only by contract (see each backend's docstring); the one first-party adapter that writes files (Claude Code) passes every scanned value through the shared sanitization module (agenticworkspace/util/sanitize.py, allowlist plus shell quoting) before embedding it into a generated shell script. See SECURITY.md for the disclosure process. Honest note: this project does not currently publish SLSA provenance, Sigstore signatures, or an SBOM, and has no OpenSSF Scorecard badge set up -- none of that infrastructure exists yet for either distribution, so it isn't claimed here.

Contributing

See CONTRIBUTING.md for the full guide, covering both the TypeScript and Python codebases.

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

License

Apache 2.0, see LICENSE.