Spec
Clear boundaries for human and machine authored context.
The spec separates manual guidance from generated intelligence so tools can reason about codebases without replacing the developer's instructions.
AI Agent Codebase Intelligence Standard
Open standard for agent context
Structured codebase intelligence for AI agents.
workspace.json gives codebases a machine-readable layer of context so AI tools, CI, and contributors stay aligned with what is actually in the repository.
Schema
Published JSON Schema with a stable validation contract.
Integrations can validate structure, enforce required fields, and keep generated output aligned with the documented contract.
Audit
Reference tooling for generating workspace.json from any codebase.
agents-audit scans a repository and emits a conformant workspace.json document under .agents/agents.workspace.json. Pair with a daemon for behavioral intelligence over time.
From the blog
All posts →spec
workspace.json vs AGENTS.md: Prescriptive vs Descriptive Context
A direct comparison of the two leading AI codebase context formats and why the distinction matters for agent reliability.
What it is
workspace.json is a JSON file that describes a codebase to AI agents. It captures file structure, conventions, framework versions, and fragility signals derived from observing how the codebase is actually used — behavioral codebase intelligence derived from the commit record, not from reading the source. Tools generate it, agents read it, developers commit it, and the team shares one view of reality.
It's workspace-local intelligence: scoped to the repository, version-controlled with the code, and consumed at the point where agents make decisions. Apache 2.0 licensed and proposed as a complement to AGENTS.md.
Why it exists
AGENTS.md gives AI coding tools a place to read instructions. Those instructions are prose, written by humans, and they age quickly. A codebase changes; the file describing it should change with it.
workspace.json is for the descriptive layer: what is true about the code right now. It's regenerated by tools that observe the codebase, so it stays current. AI agents read both AGENTS.md and workspace.json: prescriptive context plus descriptive context.
How it relates to AGENTS.md
The two files are designed to compose:
- AGENTS.md: what agents should do, in prose
- workspace.json: what is true about the codebase, in structured data
A repo can have both, neither, or either. Tools that consume AGENTS.md continue to work unchanged. Tools that also consume workspace.json get richer context.