FAQ

What is workspace.json?

workspace.json (also called agents.workspace.json) is a machine-generated JSON file committed to version control that provides AI coding agents with structured, behavioral intelligence about a codebase. It describes what is true about the code — fragility scores, framework dependencies, file modification patterns, agent instruction file references — without containing code content itself.

It is an open specification proposed for donation to the Agentic AI Foundation (AAIF).

How is workspace.json different from AGENTS.md?

AGENTS.md is a human-authored prose file of instructions for AI coding agents (prescriptive: “what should agents do”). workspace.json is a machine-generated structured file of codebase facts (descriptive: “what is true about the code”). They compose — a repository with both gives agents the richest context. workspace.json does not replace AGENTS.md; it complements it.

File	Layer	Authored by	Content type
AGENTS.md	Prescriptive	Humans	Prose instructions
workspace.json	Descriptive	Tooling	Structured intelligence

How is workspace.json different from package.json?

package.json is a manifest for JavaScript package metadata — dependencies, scripts, version. workspace.json is a behavioral intelligence file for AI agents — it describes observed codebase characteristics like file fragility scores, framework usage, commit hotspots, and agent instruction file locations.

They serve entirely different purposes. workspace.json is not language-specific and works in any codebase.

How does workspace.json work with AI coding tools?

The same way for all of them: as a structured context layer that complements the tool’s native instruction format. Claude Code reads AGENTS.md; Cursor uses .cursor/rules; Windsurf uses .windsurfrules. workspace.json sits alongside all of these — machine-generated facts about the codebase that would be tedious to maintain in prose: fragility scores, framework map, file modification history.

When any agent has access to agents.workspace.json, it can make better-informed decisions about which files are fragile and what the codebase architecture looks like. The spec is tool-agnostic: any agent that can read a JSON file from .agents/agents.workspace.json benefits.

Is workspace.json the same as .cursor/rules, .clinerules, or .windsurfrules?

No. .cursor/rules, .clinerules, .windsurfrules, and similar files are tool-specific prose instruction files — the prescriptive layer for specific agents. workspace.json is the tool-agnostic, machine-generated descriptive layer for any AI agent.

The workspace.json spec explicitly references these agent instruction files in its agents section so that consumers can discover the full context available in a repository. workspace.json doesn’t replace any of them; it tells agents where to find them.

What is agents-audit?

agents-audit is the reference CLI tool for auditing AGENTS.md hygiene and agents.workspace.json consistency. Run npx agents-audit in any repository. It reads your AGENTS.md, reads agents.workspace.json if present, and produces a hygiene report with a score and actionable findings.

npx agents-audit          # basic audit
npx agents-audit --fail-on=error  # block CI on errors

Install via npm: npm install -g agents-audit

Should I commit workspace.json to git?

Yes. The file is designed to be committed so that the entire team’s tooling shares the same view of the codebase. The schema explicitly excludes anything that should not be committed (secrets, contributor-attributed data, content snippets).

See the spec’s security section for the full list of MUST NOT fields.

How often should workspace.json be regenerated?

As often as your generator supports. Vreko regenerates continuously as it observes the codebase; other generators might run on commit, on a schedule, or on demand. Daily or per-PR regeneration is a reasonable starting point for teams that don’t have a daemon-based generator.

How does workspace.json get populated?

Two tiers of tooling produce workspace.json files. Both produce spec-compliant output; they differ in how they observe the codebase and the fidelity of the signals they produce.

Static analysis (agents-audit CLI)

Run npx agents-audit scan . to generate a workspace.json from git history. aiModificationCount and humanModificationCount are approximated from commit metadata and tool signatures. The scan runs once on explicit invocation — there are no hooks, no background process, no daemon.

npx agents-audit scan .

This is useful immediately, before any daemon is running, and produces valid workspace.json that consumers can read without any additional setup.

Live behavioral observation (daemon)

A local daemon observes file system events in real time and attributes modifications to the tool that triggered them — a Claude Code session, a Cursor edit, a manual terminal save. Counts become empirical as sessions accumulate. The daemon writes only to repositories where workspace.json has been explicitly initialized.

This is how Vreko operates. The live tier produces higher-fidelity aiModificationCount and humanModificationCount signals over time because it attributes changes at the session level rather than inferring them from commit metadata.

Both tiers produce spec-compliant workspace.json files. The static tier is immediately useful with no ongoing process. The live tier produces richer signals as the daemon accumulates observations.

Does workspace.json expose sensitive code?

No, by design. The schema explicitly prohibits committing secrets, PII, content snippets, or absolute paths. The file contains metadata about files (fragility scores, modification counts, framework names) — not the contents of those files. See the spec’s security section for the full list of fields that MUST NOT be committed.

How do I use workspace.json in CI?

Run npx agents-audit as a CI step to validate workspace.json structure and surface hygiene issues. The --fail-on=error flag causes the check to exit non-zero on error-level findings, which makes it suitable as a blocking CI gate.

- name: agents-audit
  run: npx --yes agents-audit --fail-on=error

You can also validate workspace.json against the published JSON Schema at www.workspacejson.dev/schema/v1.json using any standard JSON Schema validator.

How does workspace.json work in a monorepo?

Each package MAY have its own agents.workspace.json in its .agents/ directory, describing that package’s local context. A root-level agents.workspace.json describes the repository as a whole. Consumers should prefer the nearest agents.workspace.json to the files being processed — a tool working in packages/api/ should prefer packages/api/.agents/agents.workspace.json over the root file.

Do I need to install Vreko to use workspace.json?

No. workspace.json is an open specification. You can write a minimal agents.workspace.json by hand, generate it with any tool that implements the spec, or use agents-audit to validate one.

Vreko is the reference implementation — it provides daemon-based behavioral observation to generate richer workspace.json files — but the spec is tool-agnostic and open.

What tools currently support workspace.json?

The reference CLI agents-audit reads workspace.json when present. Vreko generates workspace.json as part of its daemon output. Other implementations are early; see the Implementations page for the current list.

How is the spec governed?

Apache 2.0 license, public RFC process, designed for AAIF donation. See the Governance page for the current status of the AAIF donation proposal.

What is LLM context drift?

LLM context drift happens when the information an agent is working from diverges from the actual state of the codebase — because the prose in AGENTS.md hasn’t been updated, because the agent’s session started before recent commits landed, or because different tools are working from different snapshots of the same repo.

workspace.json addresses drift structurally. Because it’s machine-generated from the live codebase and committed to git, the agent’s view is always tied to a specific commit. A workspace.json generated from HEAD describes HEAD — there is no ambiguity about what state it represents. This is AI coding session coherence: the agent, the developer, and the codebase are looking at the same commit.

What is inter-commit space?

Inter-commit space is the period between commits where a developer is actively working — files are modified, logic is being written, but nothing has been recorded to git history yet. This is where most AI coding session context lives, and it’s the hardest space for agents to reason about accurately.

workspace.json anchors agents to the last committed state and makes the boundary explicit. The agent knows what was true at the last commit and can reason about in-progress changes relative to that baseline — rather than guessing at an ambiguous current state.

Does workspace.json support AI attribution for code changes?

v0.3 does not include a dedicated AI attribution field. The aiModificationCount and humanModificationCount fields in fileIndex are aggregate counts — they record how many times a file was modified by AI-assisted versus human-driven sessions, without identifying which session or contributor.

AI attribution as a structured field is under consideration for a future version. For teams tracking AI contributions now, the combination of workspace.json commit history and standard git log provides a partial record: what the codebase looked like when a session started, what changed, and when.

Why a new spec instead of extending AGENTS.md?

AGENTS.md is the right home for prose instructions. workspace.json addresses a different problem: machine-derived structured intelligence that doesn’t fit the “human writes prose” model. Extending AGENTS.md to include a structured-intelligence section would conflate two different concerns and break the Markdown parseability that makes AGENTS.md useful.

How can my tool support workspace.json?

The spec is at /spec/. The JSON Schema is published at www.workspacejson.dev/schema/v1.json. To list your tool on the Implementations page, open a PR with documentation showing how your tool reads or writes workspace.json.