An open spec for what is true about your code, right now.

v0.4 unstable Apache 2.0

workspace.json is an open, committed record of repository context that tools can generate, validate, and consume.

One artifact, two consumers on separate vendor agent platforms: @workspacejson/codex-mcp for Codex, and Buildomator (formerly gsd-plugin), an independently maintained Claude Code plugin, which reads workspace.json at SessionStart.

Read the spec Comment on the RFC

File path

.agents/workspace.json

Reference impl

@workspacejson/cli

Consumer

Buildomator, an independently maintained Claude Code plugin

The Problem

Your agents read the code. They don't know what it means.

Every codebase has files that everyone is afraid of. The authentication flow that broke twice last year. The webhook handler nobody fully understands. The component that was AI-generated, then patched fourteen times. This information lives in the heads of senior engineers and in Slack threads from six months ago. It does not live anywhere a coding agent can find it.

When an agent picks up a task, it sees a flat repository. It cannot tell that one file has been the source of half your production incidents this quarter, or that changing one type definition cascades into seven others. So it works confidently, and it breaks things confidently.

AGENTS.md helps. It gives agents a place to read instructions. But instructions are prose, written by humans, and they age. A codebase changes; the file describing it in words cannot keep up. There is no mechanism to tell an agent what is true about the repository right now, only what a developer wrote about it at some point in the past.

The Solution

A machine-generated layer of codebase truth.

workspace.json is placed at .agents/workspace.json and committed to version control. Tooling can generate repository context from repository evidence. Agents read it before they act. Developers commit it alongside the code it describes.

File	Role	Author	Updates
AGENTS.md	Prescriptive: what agents should do	Human	By hand
workspace.json	Descriptive: what is currently true	Tooling	Automated

The two files are designed to compose. A repo can have both, either, or neither. Tools that consume AGENTS.md continue to work unchanged. Tools that also consume workspace.json get richer, current context.

Signal Families

Four things your agents should know before they edit anything.

.agents/workspace.json

{
  "manual": {
    "fragileFiles": [
      { "path": "src/config.ts", "reason": "Shared configuration boundary" }
    ],
    "coChangePatterns": [
      { "files": ["src/config.ts", "src/config.test.ts"], "note": "Update together" }
    ]
  },
  "generated": {
    "specVersion": "0.4",
    "generatedAt": "2026-08-03T00:00:00.000Z",
    "by": { "name": "example", "version": "0.0.0" },
    "fileIndex": { "src/config.ts": {} },
    "frameworkManifest": [{ "name": "Astro" }]
  },
  "agents": {},
  "health": {}
}

This is a synthesized stable-profile example, not output attributed to a named producer. Generate an artifact with npx @workspacejson/cli generate . and validate it independently.

Producer identity

The artifact records the generator, its version, and generation time. It does not infer evidence that the producer did not emit.

Discovery

The producer describes the repository topology and the canonical .agents/workspace.json location used by consumers.

Human evidence

Maintainers can record fragile files and co-change patterns without claiming that a generated score is stable or universally available.

Known limits

The demonstrated profile is limited to human fragile-file and co-change notes, plus generated file inventory and framework entries. Other schema fields are not promoted here as an interoperability guarantee.

How It Works

Three steps. No lock-in.

1. Generate. Run npx @workspacejson/cli generate . in any repository. The neutral CLI emits a conformant workspace.json under .agents/.

2. Commit. Add .agents/workspace.json to version control. Every contributor, every CI run, and every agent session now shares the same view of the repository's current state.

3. Consume. Any AI coding agent that reads workspace.json gets structured, current context before it acts. No configuration required beyond knowing where to look.

Note

The spec does not prescribe enforcement or a scoring system. Consumers should only rely on the documented, demonstrated profile and treat other fields as optional evidence.

For Implementers

Build a generator. Build a consumer. Validate against the schema.

The JSON Schema is served at workspacejson.dev/schema/v1.json and validates any generated file in CI. The npm packages expose the schema and validation rules for TypeScript integrations. If you are building a generator or consumer, open an issue in the tracker.

Specification The normative v0.4 document

JSON Schema Validate your workspace.json

Conformance Producer and consumer obligations

Examples Validated, executable files

@workspacejson/spec Schema and TypeScript types

CLI tracker Open an issue

Showcase

A silent zero, found and fixed.

DataHub knows lineage and schema. Git knows which files change together. The join sounds trivial: a dbt model is a file. But when a dbt project lives in a subdirectory, every lookup misses and the join returns zero rows, silently, with no error. Tally is a Change Impact Cockpit that resolves the mismatch, joins catalog context with repository evidence, and attaches a bounded receipt to every claim.

Read the showcase Inspect the evidence

The spec is a starting point, not a finished standard.

v0.4 is a draft. The signal families are defined; the computation methods are intentionally open. What confidence scores should look like, how multiple generators should merge overlapping outputs, what negative space means for files the generator inspected and had nothing to say about: these are open questions with no settled answers yet.

Comment. Argue. Implement a draft.

The spec exists to be torn apart in public.

Read the spec Comment on the RFC