DevWorkspace

A project-local AI engineering layer for existing repositories. DevWorkspace gives an AI coding agent (Claude Code first) a small, portable, evidence-backed memory of your project, a task and verification discipline, and safety rails, without moving your project, creating an account, or needing an API key.

cd my-project
npx devworkspace init
npx devworkspace analyze

What problem does it solve?

AI coding sessions start cold. The agent re-discovers your architecture, re-reads the same files, forgets decisions, runs the wrong tests, and sometimes declares victory while the build is red. DevWorkspace stores knowledge (not code) in .devworkspace/, keeps it honest (provenance, confidence, staleness), and installs a thin set of instructions that make the agent load context progressively, classify work, verify it, and update memory sparingly.

What it is not

DevWorkspace is not an LLM, an IDE, a Git client, a vector database, a code-graph engine, a test framework, a model router, or a cloud service. It orchestrates tools that already exist:

| Concern | Provided by | | --- | --- | | Structural code understanding | Graphify | | Engineering workflows (spec, plan, build, test, review, ship) | Agent Skills | | Quality, simplification, debt review | Ponytail | | Model routing (optional, not used in V1) | OmniRoute | | Correctness | Your tests |

DevWorkspace decides when and why a workflow applies. Those projects provide how.

Requirements

Node.js 20.11 or newer. Works on Windows, macOS and Linux. Git is optional but strongly recommended.

Install

npx devworkspace init          # no install needed
# or
npm install -g devworkspace
devworkspace init

Quick start

cd my-project
npx devworkspace init          # safe local setup; creates .devworkspace/
npx devworkspace analyze       # deterministic discovery + onboarding prompt

Optionally install the helper tools in one command (it shows what it will do first):

npx devworkspace setup --integrations --dry-run
npx devworkspace setup --integrations --yes

Then:

1. Open .devworkspace/analysis/onboarding-prompt.md.
2. Paste it into Claude Code (or Claude in VS Code) in this project.
3. Let Claude finish and verify the onboarding. It inspects the real repository, runs devworkspace agent install, writes concise knowledge, checks the testing contract and reports unknowns and warnings.
4. Run npx devworkspace doctor. It should say READY.

analyze does not call an AI. A CLI cannot drive an existing Claude chat, so DevWorkspace does the deterministic part itself and hands the reasoning part to Claude through a prompt you paste.

Integrations (Graphify, Agent Skills, Ponytail)

devworkspace setup --integrations installs and verifies them; devworkspace integrations status re-checks the real state at any time; devworkspace doctor reports core workspace health and integration health separately. Only project-local steps run without --yes; installing the Graphify tool for your user, user-scope installs and registry packages need --yes. Existing CLAUDE.md, .claude settings and skills are protected and restored if a tool would damage them. Some tools need a Claude Code restart afterwards, and that is reported as RESTART_REQUIRED rather than success. Details, scopes, limits and what was verified live: docs/integrations.md.

Daily workflow

Just talk to Claude:

Fix the quotation email bug. Add Responsible Person to Leads. Explain how authentication works.

The installed instructions tell Claude to classify the request and apply a proportionate workflow. A question is read-only and runs no tests. A bug gets a regression test, a fix, and the verification your testing contract requires. A refactor records a test baseline first. You can override at any time: "only explain", "don't commit", "don't run e2e". Overrides are honoured and recorded.

Useful commands any time:

devworkspace status        # health, branch, knowledge, active tasks, verification commands
devworkspace context       # what DevWorkspace believes (facts, decisions, testing contract)
devworkspace refresh       # re-check knowledge against the repository; mark stale items
devworkspace doctor        # check workspace, integrations, security, portability

Commands

| Command | Purpose | | --- | --- | | init | Create .devworkspace/ (idempotent, never touches source) | | setup --integrations | Install and verify Graphify, Agent Skills and Ponytail (--dry-run, --yes, --scope, --only) | | integrations | status (observed, never assumed) and repair | | analyze | Deterministic discovery; writes discovery.json, testing contract, onboarding prompt | | agent install | Add the managed instruction block to CLAUDE.md and install the devworkspace skill | | status | Concise overview, read-only (--deep also runs the integration health checks; --json for tooling) | | doctor | Health, security and portability checks (--fix, --strict, --json) | | refresh | Incremental staleness check; writes a refresh prompt when AI re-validation is needed | | context | Show stored knowledge (--topic filters facts and the testing contract; safety rules are always shown; --full) | | fact | add / verify / remove / list project knowledge with provenance | | task | new / list / show / status / update / run / verify / tests / attest with a package-aware completion gate | | testenv | declare / list / revoke a test environment so database-touching checks may run (local, never committed) | | decision | Append-only, human-readable decision records | | session | Save short session summaries (never transcripts) | | export / import | Move portable knowledge between machines safely | | reset | Delete .devworkspace/ to start fresh (--yes to confirm, --include-agent-files to also remove the Claude block/skill) | | migrate | Upgrade workspace files to the current schema, with backups |

Global flags: --json, --cwd <dir>, --dry-run (where it applies), --debug, --no-color, --ascii.

Exit codes: 0 success · 1 failure · 2 usage error · 3 warnings (only with --strict on status/doctor) · 130/143 interrupted. Integrations that are not installed are warnings, never failures, so CI can use devworkspace doctor and fail only on real problems.

Portability

Commit .devworkspace/ (machine-local state in .devworkspace/local/ is ignored by a nested .gitignore). On another computer: clone, then devworkspace doctor. Project identity is a random ID in project.json, never a path, so moving D:\Company\CRM to C:\Projects\CRM changes nothing. Details: docs/portability.md.

Security and privacy

• Credential files (.env*, keys, credentials.*, …) are never read; only their presence is recorded. Secret-looking values are refused by every write path and redacted from logs.
• Repository content is treated as untrusted data, and the generated instructions say so, to resist prompt injection.
• Subprocesses use argument arrays, never a shell. Imports are validated before anything is written.
• DevWorkspace itself sends nothing anywhere and has no telemetry. Generated prompts will, of course, cause your chosen AI agent to read repository files.

Details: docs/security.md.

Limitations (V1)

• Claude Code is the only agent adapter (the boundary exists for others).
• Integration setup needs prerequisites (Python 3.10+ or uv for Graphify; the Claude Code CLI for native plugins, otherwise portable skills with fewer capabilities) and sometimes your approval. It was not run end to end against GitHub on macOS/Linux; see the verification notes in docs/integrations.md.
• DevWorkspace does not build Graphify's graph (that uses the model) or uninstall anything.
• Deep analysis is not attempted for any language; discovery covers manifests, structure and commands for Node, Python, Go, Rust, Java and PHP projects.
• The routing classifier is a keyword heuristic used to propose a type. The agent decides.
• Token savings are not claimed. See docs/benchmarking.md for how to measure them.

Documentation

Getting started · Architecture · Knowledge model · Testing contract · Security & privacy · Integrations · Claude · Routing · Portability · Benchmarking · Troubleshooting · Contributing

License

MIT