WOOKhoop Agentic Workbench

Understand the source. Review the change. Approve the command. Keep the evidence.

A local framework for supervised AI-assisted development: source citations, versioned skills, durable tasks, exact human approvals and recoverable changes. The Python CLI and SDK own policy and execution; a typed Node adapter and a restricted MCP server use the same implementation.

Get started · Repair a regression · Architecture · Integrations · Evidence and limits · Documentation · Contribute

Public developer preview. Review the source before installation. Registry packages and a stable release are not published. Start with the developer field guide, the historical illustrated PDF guide, or the current preview assessment. Hosted checks are visible in GitHub Actions.

Where it fits

Use Workbench when a development task needs a clear connection between the source you inspected, the change you approved and the check that actually ran.

The core works offline. Optional OpenAI Responses and embeddings require a configured model, an external credential and an explicit network grant. Static analysis is labeled static; lexical, semantic and combined retrieval are identified separately. See how this project's role compares with other tools.

Versioned packages

Version 0.1.0 is the first supervised developer-preview release candidate. Check the release status for registry availability. Once the registry versions are available, the version-pinned commands are:

python -m pip install "agentic-workbench==0.1.0"
npm install --ignore-scripts @agentic-workbench/node@0.1.0

The Node package requires the Python CLI; it does not install Python or bypass its policies. The source and local artifact installation below work independently of registry availability. See 0.1.0 release notes.

Install from a reviewed checkout

Requires Python 3.11+. Guarded source changes and command execution require POSIX. Python-only analysis does not require Node; the optional Node adapter requires Node 24+.

Clone the public source, inspect it, then install into an isolated environment:

git clone https://github.com/ashutosh99sri-cyber/agentic-workbench.git
cd agentic-workbench
python3 -m venv .venv-agentic
.venv-agentic/bin/python -m pip install .
. .venv-agentic/bin/activate
agentic --version
agentic --help

The distribution remains agentic-workbench, the Python import remains agentic_workbench, and the installed console scripts remain agentic and agentic-workbench. WOOKhoop is the presentation brand. The alternate console name is available if another tool already uses agentic.

On Windows, use the environment's Scripts\python.exe and Scripts\agentic.exe; restrict use to the documented read-only subset. Follow the installation tutorial for platform details and clean wheel installation.

Start offline

Choose a project you control and replace the example source path with a real file in that project:

agentic init --root /absolute/path/to/application
agentic scan --root /absolute/path/to/application
agentic explain app.py --root /absolute/path/to/application --provider none
agentic plan "Investigate discount rounding and identify regression checks" \
  --root /absolute/path/to/application --provider none
agentic search "discount total" --root /absolute/path/to/application --provider none
agentic impact app.py --root /absolute/path/to/application
agentic skills --root /absolute/path/to/application

init creates private local state and configuration, preserving an existing valid configuration. Add .agentic/ to the target application's .gitignore: it can contain source results, diffs and original rollback content. Protect state exports and backups as well.

Scan, explanation, planning and dry runs preserve application source; they can write application-owned state. No target dependencies are installed automatically. scan is an offline inventory command and does not accept --provider. Explicit --provider none on supported analysis commands overrides an existing project provider setting.

Ordinary CLI commands emit one version 1 JSON envelope, with ok, data or a structured error. --json is accepted explicitly. MCP uses its separate JSON-RPC stdio protocol.

agentic context "Fix discount rounding" --changed-path app.py \
  --root /absolute/path/to/application
agentic explain discountedTotal --root /absolute/path/to/application \
  --provider none \
  --node-executable /absolute/path/to/node \
  --typescript-package /absolute/host-tools/node_modules/typescript

Repair a regression

The built-in repair workflow is deliberately bounded: 1–20 existing, indexed, writable non-test Python source files, with 1–4 candidate attempts and a default of two. It refuses test machinery, configuration, file creation, deletion and edits outside the host's allowlist.

1. Configure a named check and review its source snapshot. Approve the baseline command separately.
2. If the check reproduces a failure, a provider proposes a candidate for the allowed files.
3. Review the exact diff and digest, then approve that source change.
4. Review the command again for the changed snapshot, then approve verification.
5. A repaired result requires a reproduced failure, an applied approved change and a clean passing command whose snapshot still matches the source.

A baseline that already passes stops before a model request. An unusable startup, timeout or output-limit stop does not count as a reproduced defect. Unknown paid-provider outcomes stop for host review instead of automatic replay.

Configure the check in the target project's .agentic/config.toml. This example uses the Python image reference from the retained acceptance baseline; review its suitability and ensure that exact image is already present in your trusted local daemon:

[commands.unit]
argv = ["python", "-B", "-m", "unittest", "-q"]
image = "python@sha256:e88e9763f943ec1834f992a4b51e0f24500486803e8bc534e5767af9ea65f6ce"
timeout = 60
max_output_bytes = 1048576

The runner never pulls an image. The command must be meaningful for your project and must work with the dependencies already in the chosen image. A passing check establishes that check's outcome; it does not establish that every defect is fixed.

python -m pip install "/absolute/path/to/agentic-workbench[openai]"

agentic repair "Fix percentage discount rounding" \
  --root /absolute/path/to/application --command-id unit --edit-path app.py \
  --max-attempts 2 --provider openai --model YOUR_MODEL --allow-network

agentic repair "Fix percentage discount rounding" \
  --root /absolute/path/to/application --command-id unit --edit-path app.py \
  --max-attempts 2 --provider openai --model YOUR_MODEL --allow-network \
  --task-id TASK_ID --approve-baseline BASELINE_DIGEST

agentic repair "Fix percentage discount rounding" \
  --root /absolute/path/to/application --command-id unit --edit-path app.py \
  --max-attempts 2 --provider openai --model YOUR_MODEL --allow-network \
  --task-id TASK_ID --approve CHANGE_DIGEST

agentic repair "Fix percentage discount rounding" \
  --root /absolute/path/to/application --command-id unit --edit-path app.py \
  --max-attempts 2 --provider openai --model YOUR_MODEL --allow-network \
  --task-id TASK_ID --approve-test TEST_DIGEST

agentic apply PROPOSAL_ID --root /absolute/path/to/application
agentic test --command-id unit --root /absolute/path/to/application
agentic apply --rollback CHANGE_ID --root /absolute/path/to/application

How it works

flowchart LR
  Host["CLI / Python SDK / Node adapter"] --> Runtime["Agents and durable coordinator"]
  MCP["Editor via MCP stdio"] --> Read["Read and proposal review"]
  Read --> Runtime
  Runtime --> Policy["Root scope / grants / secret filtering"]
  Policy --> Source["Selected local source"]
  Runtime --> Index["Inventory / symbols / retrieval"]
  Runtime --> Skills["Versioned skills"]
  Runtime <--> State["Private SQLite state / receipts"]
  Runtime --> Provider["Optional provider with network grant"]
  Provider --> Tools["Validated read tools"]
  Tools --> Policy
  Runtime --> Proposal["Saved proposal / diff / digest"]
  Proposal --> Writer["Guarded writer / recovery journal"]
  Human["Exact host approvals"] --> Writer
  Human --> Runner["Docker or explicit trusted host"]
  Runner --> Verification["Actual command outcome"]
  Verification --> State

The experimental harness supplies typed host tools, capability-aware routing, token/cost reservations, source-bound decision memory and a checkpointed Plan → Execute → Observe → Verify → Reflect loop. execute, trace, cancel, tools, skills and context expose its lifecycle. Custom planners, executors and verifiers remain trusted host code. Read the harness guide, gap analysis and implementation contract.

Use it from your tools

Python SDK

from agentic_workbench import Workbench

with Workbench("/absolute/path/to/application") as wb:
    inventory = wb.scan()
    explanation = wb.explain("app.py")
    plan = wb.plan("Investigate discount rounding")
    matches = wb.search("discount total")  # lexical; offline

This example assumes the project's provider is none, as created by init. Write, execute, trusted-host and network grants are explicit host capabilities. For a write, construct a trusted Grant(write=True), inspect wb.review(...), then call wb.apply(..., approval=review["digest"], dry_run=False). Model instructions, source and skills cannot supply those grants or approvals. Run the offline installed-SDK walkthrough to inspect source analysis, imported proposal planning and exact synthetic change approvals. See the developer adoption guide and CLI/SDK reference.

Node adapter

The Node adapter wraps the installed CLI with typed methods, shell: false, bounded subprocesses, strict envelopes and typed errors. Build/package it locally as described in its guide; no public npm installation is assumed.

import { Workbench } from "@agentic-workbench/node";

const workbench = new Workbench("/absolute/path/to/application", {
  executable: "/absolute/path/to/venv/bin/agentic",
});

const inventory = await workbench.scan();
const explanation = await workbench.explain("app.py");

It provides supported analysis, review, approval and harness bindings while Python retains policy authority. The built-in Python repair workflow is currently exposed through the CLI and Python SDK. Optional provider invocation requires explicit per-call options and credential forwarding; see the adapter's API and environment contract.

MCP and editors

agentic mcp --root /absolute/path/to/application --provider none

The stdio server exposes scan, explain, search, impact, plan, run, status and review. It has no approval, source mutation or test-execution tool. Results can contain source excerpts visible to the editor and its model. Provider/network access remains an explicit host choice.

The editor recipes cover Claude Code, VS Code and Cursor. Retained host evidence establishes only that Claude Code 2.1.300 connected and listed tools; successful task execution in that host, VS Code and Cursor remains unverified. The provider adapter recipe demonstrates trusted registration, budget admission, structured results and unknown-outcome handling with an injected transport.

Evidence and limits

The latest verified development runtime is 4a1f8c56239bb3b63bbf82b6bec543f72dc82222 (17 October 2026): 975 offline Python cases, 8 Docker cases, 3 unique distribution cases checked against both wheel and source consumers, and 13 Node tests passed. All eight roles passed static and official OpenAI SDK mocked transport checks. Changed-path retrieval recovered 8/8 tasks on the regression set and 8/8 on a new independent holdout; query-only selections were identical before and after on all 30 paired tasks. These are local source/workflow results, not live model effectiveness or hosted CI. See the public-preview assessment, validation evidence, and release readiness for limits and publication gates. Older implementation baselines remain historical evidence.

The public repository starts from a reviewed current-source snapshot. Earlier development commits remain local; their hashes above identify historical evidence rather than reachable public commits. The source provenance records the exact inherited runtime file hashes. Runtime permissions and approval controls are unchanged.

The evaluation corpus includes 30 pinned historical Python defects from more-itertools, Click and packaging, with visible reproductions and separate holdout checks. No-patch and known-patch replay validate workflow/grading machinery. Known-patch replay success is not LLM repair success. Live model effectiveness, comparative task success, human-time savings and cost savings have not been established. See the repair evaluation.

Documentation

See AI Hero research and runtime optimization for source-backed engineering choices, local before/after measurements and deferred technologies.

Contribute

Start with CONTRIBUTING.md, the Code of Conduct and SUPPORT.md. Keep changes bounded, distinguish source facts from runtime evidence and report the exact revision, versions and skips behind a result. Use the private reporting process for security-sensitive material.

From a reviewed checkout, contributor checks are:

UV_LINK_MODE=copy uv sync --locked --all-extras
uv run --locked pytest -m "not docker and not distribution"
uv run --locked ruff check src tests scripts
uv run --locked ruff format --check src tests scripts
uv run --locked mypy src/agentic_workbench
uv build
cd adapters/node
npm ci --ignore-scripts
npm run build
npm test

Native parser, clean installed-consumer and actual Docker acceptance have separate prerequisites in the contribution/support guides. Node CLI integration requires AGENTIC_EXECUTABLE pointing to an absolute installed CLI. Ordinary CI does not invoke a paid provider. The benchmark scores source targeting and named facts on the examples; live provider runs are separate explicitly authorized measurements. The example projects deliberately contain a discount regression and are fixtures, not business software.

Licensing and release status

Authored code and bundled instructions are offered under Apache-2.0, subject to the repository's NOTICE, third-party notices and source provenance. The engineering skill's decision order is adapted from the MIT-licensed Ponytail. The owner confirmed distribution and WOOKhoop brand rights for this source preview. Branding does not change package identifiers or third-party rights.

v0.1.0 is the selected first developer-preview release. Registry availability is reported separately in the release notes; a tag or GitHub release alone does not establish a PyPI/npm upload. Later releases require their own exact-commit acceptance and release authorization. Follow the publication record and release procedure and roadmap.