Documentation

Workspai docs

Everything you need to create, understand, and govern software workspaces from the CLI, CI, and VS Code.

Learn the Workspace Intelligence architectureOpen Workspai.dev for concepts, contracts, architecture maps, guides, and reference material.

Quick start

Install the CLI, create or adopt your first governed workspace, then open the same evidence in VS Code.

$npm install -g workspai

Install the Workspai CLI

Run npm install -g workspai, or use npx workspai for an install-free first run.

Open npm

Create or adopt a workspace

Create a workspace, or run npx workspai adopt . inside an existing project. Workspai connects it without moving the source.

Add the VS Code extension

Install Workspai from the Marketplace, open the workspace, and use the same model, evidence, and repair paths inside your editor.

Open Marketplace

Workspace identity baseline

Workspai keeps managed workspaces in ~/.workspai/workspacesand uses one shared workspace identity for CLI, CI, VS Code, and agent surfaces. Create, adopt, import, list, and sync commands all resolve that same boundary. Connected projects receive a portable context lens plus a gitignored machine-local link, so users and agents can run workspace-aware commands from the project itself.

Workspai CLI

The open-source CLI owns the deterministic workspace layer. Bootstrap workspaces, adopt repositories, scaffold kits, produce evidence, and enforce the versioned intelligence chain from the terminal or CI.

Canonical enterprise gate

workspai workspace intelligence run --for-agent generic --strict --json

This executes Model → Diff → Impact → Doctor Evidence → Contract Evidence → Analyze Evidence → Readiness Evidence → Verify → Agent Context → Agent Grounding → Explain in contract order. A strict run succeeds only when its required evidence is ready, and writes the complete result to .workspai/reports/workspace-intelligence-run-last-run.json.

Command and schema baseline: Workspai CLI 0.65.0

$npm install -g workspai

$npx workspai my-workspace --yes --profile polyglot

$npx workspai bootstrap --profile polyglot

$npx workspai create project nextjs my-web --yes

$npx workspai workspace intelligence run --for-agent generic --strict --json

Or run instantly with npx workspai …. Full CLI reference

Give the work a measurable finish line

npx workspai goal "Prepare this workspace for release" --for-agent generic

The natural-language front door compiles intent into a workspai.goal-pack.v1 pack and workspai.goal-agent-handoff.v1 handoff. Verified Goals preserve release, dependency-security, or coverage success criteria across CLI, CI, IDE, and agent sessions. Planning records the goal; only npx workspai workspace goal verify <goal-id> --json can publish the governed verdict to .workspai/reports/verified-goal-last-run.json.

Enter through the canonical project boundary

npx workspai agent bootstrap --for-agent generic --strict --json

The workspai.agent-entry.v1 entry resolves its governing workspace in canonical-first mode. The workspai.agent-bootstrap-receipt.v1 receipt requires at least 6 bounded read-order items, keeps live source as exact-implementation, and permits verification claims only from cli-evidence-only. Runtime-aware Skills use workspace-operational-skill.v1 and workspace-skills-index.v1 contracts.

Diagnose causally, then repair transactionally

npx workspai doctor workspace --fresh --json=summarynpx workspai workspace repair capabilities --json

Doctor emits the workspai.doctor-diagnosis.v1 diagnosis across 6 required domains. Repair then uses 13 typed adapter families and keeps mutation authority cli-only. Missing tools, unsupported adapters, or risk beyond approval remain decision-required. Compact workspai.doctor-summary.v1 output and the durable workspai.doctor-receipt.v1 receipt preserve verdict, freshness, affected projects, blockers, and the next governed action. The aggregate Studio surface is contract-bound across 32 card kinds; one repair transaction still owns only one causal finding family and one canonical project at a time.

Plan a polyglot fleet before executing it

npx workspai workspace run build --plan --jsonnpx workspai workspace run test --runtime rust --strict --json

Plan mode discovers bounded runtime units without running them. Real test, build, and start stages use npm, Python, Go, Cargo, Maven, Gradle, NuGet, CMake, Meson providers and enforce doctor-workspace and readiness by default. The workspace-run-v1 result is retained at .workspai/reports/workspace-run-last.json. Strict mode turns failed or warning gates into a non-zero exit; verification follows the finding's exact sourceCommand and sourceArtifact instead of guessing a producer.

Ask the Workspace Knowledge Graph first

npx workspai workspace graph search "authentication" --kind endpoint --limit 12 --json

Workspai first reconciles the canonical Workspace Model, then derives and enriches this graph from the projects that model authorizes. The graph is bound to the model's stable structural hash and live project fingerprint, using hybrid-git-content-v2 with git-worktree-v2 or content-merkle-v1 per scope, so stale or mismatched graph evidence is rejected. Scoped search removes low-value query terms, ranks relevant identities deterministically, and keeps repeated logical interfaces together while preserving their individual source proofs. Provider results remain explicit when evidence is partial, skipped, failed, or expected but missing. The agent projection reports an omission budget for entities, relations, relatedEntities, proofs, proofReferences, aliases, attributeValues rather than silently truncating evidence. CMake, Meson, Bazel, and Protobuf providers enrich native and cross-language relationships. Linked proof paths remain portable and omit machine-local absolute paths by default.

Measure without overclaiming

npx workspai workspace eval report --json

Evaluation artifacts preserve observed payload and model-usage evidence. Compare compatible runs instead of presenting one fixture as a universal token-saving claim.

Framework coverage

Workspace Intelligence is framework-agnostic. Existing projects can enter a Workspai workspace through import or adopt regardless of language or framework. The list below defines where Workspai can also create a new project from scratch. The current Create Planner publishes 8 workspace profiles, 8 native kits, and 15 executable official-generator paths.

Existing project

adopt / import

Any readable language or framework can join the workspace architecture without moving or regenerating its source. Workspai registers the project, writes a project-native agent entry point, and includes it in model, graph, context, Doctor, and verification workflows.

Examples: Laravel, Rails, Django, WordPress, Rust, PHP, Kotlin, legacy services, and mixed monorepos.

New project

create

Creating from zero requires a supported native or ecosystem create lane. The current catalog includes backend, frontend, desktop, and extension projects. Official generators resolve their latest stable release, validate declared runtime requirements, and record the result before Workspai synchronizes workspace evidence.

Only the create lanes listed below are promised for new scaffolds today.

Create-from-scratch lanes

RapidKit Core supplies deeper Python-engine kits and backend modules where applicable.

FastAPI

Python 3.11+

fastapi.standardfastapi.ddd

NestJS

Node.js · TypeScript

nestjs.standard

Go / Fiber

Go 1.21+

gofiber.standard

Go / Gin

Go 1.21+

gogin.standard

Spring Boot

Java 17+

springboot.standard

ASP.NET Core

.NET 8+ · C#

dotnet.webapi.clean

Frontend Apps

Node.js · TypeScript

frontend.nextjsfrontend.remixfrontend.vite-reactfrontend.vite-vuefrontend.vite-sveltefrontend.vite-solidfrontend.vite-vanillafrontend.nuxtfrontend.angularfrontend.astrofrontend.sveltekit

Rust / Axum

Rust · Cargo

rust.axum

Desktop Apps

Rust or Node.js · TypeScript

desktop.tauridesktop.electron

VS Code Extension

Node.js · TypeScript

extension.vscode

Laravel

PHP · Composer

php.laravel

Your framework is not listed? Adopt or import the existing project today. More create-from-scratch lanes are planned; see the changelog for updates.

Command reference

All commands are accessible from the VS Code command palette.

⌘⇧P/Ctrl+Shift+P→ type "Workspai:"

Workspace & Navigation

Workspai: Show Welcome

Open the main dashboard webview — project tree, health overview, module inventory, and Studio/Advisor entry points.

Workspai: Select Workspace

Switch the active workspace used by the dashboard, sidebar, Studio, and Advisor.

Workspai: Create Workspace

Create a workspace boundary before adding or importing projects.

Workspai: Create Project

Scaffold a supported kit through the Workspai CLI bridge.

Workspai: Import Project

Bring an existing local project into the active workspace for governance and evidence-backed context.

Workspai: Open Studio

Open the focused repair surface for card fixes, editor issues, and verification handoffs.

Workspai: Run System Check

Automated health check across workspace and projects. Flags missing env vars, broken deps, port conflicts, and kit config issues.

Workspai: Show Logs

Open the Workspai extension output channel to inspect debug and runtime logs.

Workspai: Show Telemetry Summary

Review local workflow outcomes and command evidence without exposing workspace source.

Studio & Advisor sessions

Fix with Workspai

Editor diagnostic action. Opens Studio with file, language, diagnostic, and selected-code evidence.

Explain with Workspai

Editor diagnostic action. Opens Advisor for explanation without applying changes.

Workspai: AI Fix Preview (Lite)

Produces candidate edits for review with No auto-apply behavior.

Workspai: AI Change Impact (Lite)

Summarizes risk level, affected scope, and recommended test targets before a change.

Workspai: AI Smart Route

Routes the current workspace question to the smallest suitable evidence-backed workflow.

Workspai: AI Essentials

Opens the shipped set of scoped AI actions and their review-first boundaries.

Workspai: Analyze Terminal Output with AI

Sends selected terminal output into a scoped diagnosis with evidence and verification guidance.

Workspai: Guided Workspace Memory Setup

Creates reviewable workspace grounding and memory policy for supported agent surfaces.

Workspai: AI Recipe Packs

Opens 11 reusable AI workflows for release readiness, debugging, architecture, and project operations.

Workspai: AI Workspace Command Center

Opens the consolidated AI workflow launcher for the active workspace.

Fix by Workspai

Artifact-card action. Opens a Studio repair session backed by Workspai remediation-plan evidence.

Send to Advisor

Ask about a workspace, project, artifact, or command without leaving the selected scope.

Refresh evidence

Run the relevant Workspai command and reload the card/session from the latest artifact.

Verify after fix

Run the scoped verify command before a card is allowed to look resolved.

Chat Participant

@workspai /ask [question]

Context-aware architecture Q&A grounded in your workspace files, modules, and project structure — not generic LLM answers.

@workspai /debug [error]

Structured Root Cause → Remediation → Prevention flow. Uses your live VS Code editor diagnostics as context.

Studio / Advisor workflows

Studio fixes issues from artifact cards and editor diagnostics. Advisor explains scope and architecture. For Cursor, Claude, Codex, and CI, run workspace agent-sync --write from the Workspai CLI — same workspace evidence, every tool.

Guided Create

"Create workspace billing-platform-wsp, then add FastAPI API + Next.js web"

Project Assistant

"What breaks if I change this settings model?"

Workspace Advisor

"Explain the auth module and its dependencies"

@workspai in Chat

"@workspai /debug Why does this return 500?"

Editor Issue Actions

"Fix with Workspai for this TypeScript diagnostic"

Fix by Workspai

"Open Studio from the blocked Readiness card"

Explain with Workspai

"Explain this import error without applying changes"

Change Impact

"If I change this auth middleware, what breaks?"

Terminal Evidence Review

"Analyze this pytest failure and suggest the verify command"

Agent Context Pack

"Refresh workspace context for agents"

Agent Sync

"Sync AGENTS.md, Copilot, Cursor, Claude, and skills surfaces"

Workspace Playbooks

"Use the release-readiness playbook for this workspace"

Module Advisor

"How do I wire db_postgres with auth_core?"

Command Evidence History

"Show recent doctor, analyze, readiness, and verify outputs"

Wave 2 claim policy

We do not label a capability as stable or retention-driving until it has scope evidence, verification path, telemetry outcomes, and release-gate compliance.

✓Stable requires repeatable behavior and passing release gates.
✓Useful requires clear time-to-value in the Workspai Studio loop.
✓Retention-driving requires production telemetry, not demo-only evidence.

Next practical step

Try Workspai in a real workspace workflow

Install the CLI, try it in a real workspace, then add the extension when you want the same evidence and repair flow inside VS Code.

Install from VS Code Marketplace CLI reference

Want a concrete starting point? Browse workspace examples or follow the evidence-backed product experience.