Workspai CLI

Give your AI agent the system, not just the repository

Your AI coding agent wastes time guessing your project structure. Workspai fixes that.

One workspace. One truth. Humans and AI aligned.

Workspace Intelligence for software systems

Workspai is an open-source CLI that gives people and AI tools one governed view of the software system they are changing.

npx workspai adopt .
npx workspai workspace intelligence run --for-agent generic

Two commands. Your project gains a bounded, evidence-backed system view:

Before vs After

Before Workspai	After Workspai
Agent scans thousands of files for context	Agent starts from bounded entry and context artifacts
No dependency map between services	Searchable graph with source-level proof
Broken test blocks release, no one knows why	Doctor localizes the blocker and next target
Every AI session starts from scratch	Sessions resume from durable evidence

Here is what you get:

What it produces	Why it matters
Workspace Model	A canonical inventory of registered projects, detected runtimes, frameworks, and proven dependencies
Knowledge Graph	Searchable relationships between projects, backed by source-level proof
Health & Readiness	Doctor checks, verification gates, and release posture based on evidence, not guesses
Agent Context	Bounded, focused instructions so AI tools read what they need, not the entire repo
Agent Rules	Ready-to-use grounding for Cursor, Copilot, Claude, Codex, Gemini, and more
Agent Skills	Runtime-, polyglot-, test-, and delivery-aware operational playbooks, with portable SKILL.md projections where the host supports Agent Skills
MCP Server	Versioned read-oriented tools for querying evidence, graph, blockers, and context live

generic is the safe default when you do not yet know which agent will use the project: Workspai builds one portable context and prepares discovery adapters for every supported host, without duplicating the Model or Graph.

What the output looks like

The canonical workspace owns the Model, Graph, context, evidence index, and Skills. Each linked project keeps only its portable entry, scoped context, and workspace binding:

your-workspace/
├── .workspai/
│   ├── reports/                       # Model, Graph, verification, context
│   └── skills/                        # evidence-derived playbooks
├── AGENTS.md · .codex/ · .cursor/ · .claude/ · .github/ · .agents/
└── project/.workspai/
    ├── agent-entry.v1.json            # portable project entry
    └── workspace-link.local.json      # machine-local binding

Your agent starts with agent-entry.v1.json, compact workspace context, and the Skills index; it then retrieves task-scoped Graph evidence and targeted source.

Get started · See what you get · How it works · Documentation

Start in two minutes

Use an existing project

Open the project and adopt it:

cd /absolute/path/to/project
npx workspai adopt .

The project stays where it is. Workspai creates or reuses a minimal workspace in the default system location and records a validated local link.

Stay in the same project directory and run Workspace Intelligence:

npx workspai workspace intelligence run --for-agent generic

Workspai now knows which workspace owns the project. You only need --workspace <path> when a moved or ambiguous binding cannot be resolved. The shorter command is intended for a human-readable first run. CI, agents, and other machine consumers should use the strict JSON form shown in How Workspace Intelligence works.

Start new software

Use the guided flow:

npx workspai create

Choose whether to create a workspace, scaffold a project, or add existing software. Project starters are grouped as Backend, Frontend, Desktop, AI Agent, AI Gateway, Extension, and Gaming.

# Optional global installation
npm install -g workspai
workspai --version

Give your agent a goal, not an open-ended prompt

Describe the outcome in plain language from the adopted project:

npx workspai goal "Raise test coverage to 85%" --for-agent generic
npx workspai goal "Raise test coverage to 85%" --runtime cpp --for-agent generic
npx workspai goal "Add retry with exponential backoff" --for-agent generic

Workspai turns it into a bounded, evidence-backed handoff:

Intent → project scope → proof-backed context → governed plan → safe execution

The agent gets a focused objective, not permission to scan or change everything. Workspai keeps approval, verification, and rollback under CLI control. The command prepares governed work; it does not edit source or claim that the outcome is complete. Exact coverage, dependency-security, and release Goals have deterministic CLI verifiers; other outcomes retain CLI safety and rollback while the consumer performs an evidence-backed outcome review. Multi-project scope and polyglot runtime choices are explicit. Interactive users get bounded choices from the canonical Workspace Model; automation gets a machine-readable decision and can use --scope and --runtime.

Learn how Goal Packs work

Make every agent change carry proof

For source-changing work, begin a Goal-bound change before mutation:

npx workspai change begin --json
npx workspai change authorize --change <change-id> --effects filesystem,command --json
npx workspai change effect record --change <change-id> --file effect-receipt.json --json
npx workspai change verify --change <change-id> --strict --json
npx workspai change capsule validate --change <change-id> --json

The resulting capsule binds intent, baseline architecture, authorization, observed effects, predicted-versus-actual Graph changes, verification receipts, and remaining uncertainty. Prediction can guide work but can never prove its own result. Learn how Proof-Carrying Change works.

What happens after the first run

The key outputs for each audience are:

Audience	What to read
AI agent	agent-entry.v1.json (project) → workspace-context-agent.json (workspace)
Developer	Terminal summary, or workspace-explain-last-run.json for diagnosis
CI / automation	workspace-verify-last-run.json (exit code 0 = pass, 2 = blocked)
MCP client	workspace mcp serve (versioned read-oriented tools over JSON-RPC)
IDE extension	Same artifacts + watch events

An agent can prove that it entered through governed evidence before scanning the repository:

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

The receipt validates workspace membership, artifact integrity, Model/Graph freshness, and the active Goal handoff. A blocked receipt prevents architecture claims; it never falls back silently to a broad source scan. Learn about canonical-first agent entry.

A blocked result is useful evidence, not a crashed command. Workspai names what is missing or failing and keeps the generated reports available for inspection.

How Workspace Intelligence works

Workspace sources
       │
       ▼
Canonical Workspace Model
       │
       ▼
Evidence-backed Knowledge Graph
       │
       ▼
Impact · Doctor · Verify · Context · Explain
       │
       ▼
Humans · CI · IDEs · MCP · AI agents

The Workspace Model is the canonical source of truth. The Knowledge Graph is a derived, revision-bound representation of that model. It can add proof-backed detail without becoming a second source of truth or mutating the model that authorized the run.

A missing relationship means not proven by current evidence, not "these projects are independent."

The full contract-backed chain is:

Model → Diff → Impact → Doctor + Contract Verify + Analyze → Readiness
      → Verify → Context → Agent Sync → Explain

Run it with:

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

pipeline --json --strict is the broader release and governance workflow. It complements this chain; it does not replace it.

The deterministic model, graph, and checks do not require an AI API key.

See the evidence-backed graph

The graph connects projects, APIs, packages, tests, infrastructure, ownership, and runtime topology only when current evidence supports the relationship. Every visible relationship can retain proof, while missing relationships stay explicitly unproven.

Query, explain, and export the graph

Everyday workflows

Goal	Command
Use guided setup	npx workspai create
Link a project without moving it	npx workspai adopt .
Initialize workspace and project dependencies	npx workspai init
Refresh the complete system view	npx workspai workspace intelligence run --for-agent generic --strict --json
Turn an outcome into governed work	npx workspai goal "Raise test coverage to 85%"
Prove an agent change from intent to verify	npx workspai change begin --json
Ground an agent before source discovery	npx workspai agent bootstrap --for-agent generic --strict --json
Copy or clone a project into a workspace	npx workspai import <path-or-git-url> --workspace <path>
Diagnose project or workspace health	npx workspai doctor project / npx workspai doctor workspace
Observe CLI and Studio activity	npx workspai live --once --json --projection board
Ask a focused architecture question	npx workspai workspace graph search "authentication service" --limit 12 --json
Verify current evidence	npx workspai workspace verify --strict --json
Inspect a governed repair before execution	npx workspai workspace repair capabilities --json
Refresh agent and IDE context	npx workspai workspace agent-sync --write --preset enterprise --json
Run the broader release gate	npx workspai pipeline --strict --json
Start MCP server for workspace queries	npx workspai workspace mcp serve

For every command and flag, use the Command Reference.

Outputs and integrations

Workspai exposes the same governed data through several stable surfaces:

• human-readable terminal summaries;
• JSON output for scripts and CI;
• versioned artifacts under .workspai/reports/;
• focused context and instructions for AI agents;
• MCP server with versioned read-oriented workspace tools (workspace mcp serve);
• Live activity projections and reports for IDEs and dashboards;
• JSON, JSON-LD, Mermaid, DOT, GraphML, and GEXF graph exports.

The Workspai VS Code extension uses this CLI, so visual and terminal workflows share the same contracts and artifacts.

Requirements

• Node.js >=20.19.0
• npm

Python, Go, Java, .NET, Rust, or PHP are needed only for workflows that use those runtimes. Python is not required for Python-free workspaces or npm-owned project generators.

RapidKit Core is the optional Python engine for Python/Core-dependent kits and modules; Workspai remains the workspace-level CLI.

Documentation

Goal	Guide
Learn the main terms	Glossary
Create, adopt, import, or connect software	Creating workspaces and projects
Query Graph and inspect proof	Workspace Knowledge Graph
Understand the exact decision loop	Workspace Intelligence runner
Run dependency, test, and build stages	Workspace Run
Observe CLI and Studio activity	Workspai Live
Plan, approve, execute, or roll back a repair	Workspace Repair Engine
Set a release, security, or coverage outcome	Verified engineering goals
Compile plain language into a governed plan	Goal Packs
Prove what an agent changed and why	Proof-Carrying Change
Ground an agent in canonical project evidence	Canonical-first agent entry
Measure bounded retrieval and model usage	Evaluation and benchmark
Integrate CI	CI workflows
Find generated files and schemas	Artifact Catalog
Browse all documentation	Documentation index

Troubleshooting

Problem	Next step
The workspace is not detected	Run from the project/workspace or inspect npx workspai project workspace status --json
A check reports stale evidence	Re-run the complete Workspace Intelligence command
A runtime is missing	Install only the runtime required by that project
An agent cannot find current context	Run npx workspai workspace agent-sync --write --refresh-context --json
You need a specific flag	Open the Command Reference

Contributing

Workspai is developed in the open by Chistiq, the intelligence infrastructure company behind RapidKit and Workspai.

Read CONTRIBUTING.md, the Development Guide, and the Security Policy.

License

MIT. See LICENSE.