Skip to content
workspace.json
Blog

Getting Started

workspace.json is the open specification for structured AI agent codebase intelligence. A machine-generated JSON file committed to your repository — it gives AI coding agents structured facts about your codebase without requiring them to read every file.

TL;DR: Run npx agents-audit in your repository right now. You’ll get a hygiene score for your AGENTS.md and, if present, your agents.workspace.json.

What You’ll Have After This Guide

Section titled “What You’ll Have After This Guide”
  • A passing npx agents-audit run in your repo
  • Understanding of the workspace.json format
  • CI validation set up with GitHub Actions
  • A minimal agents.workspace.json committed to git

1. Install agents-audit

Section titled “1. Install agents-audit”

No installation required — run directly with npx:

Terminal window
npx agents-audit

Or install globally:

Terminal window
npm install -g agents-audit

agents-audit runs in any repository. It doesn’t require workspace.json to be present — it will audit your AGENTS.md and tell you what’s missing.

2. Run Your First Audit

Section titled “2. Run Your First Audit”

From your repository root:

Terminal window
cd your-repo
npx agents-audit

Example output:

  workspace.json — agents-audit v0.3.0


  ┌─────────────────────────────────┐
  │  Hygiene Score: 74 / 100   C   │
  └─────────────────────────────────┘


  findings


  ● [error]   missing-file-reference     src/utils.ts referenced in AGENTS.md not found
  ● [warning]  section-staleness          "Architecture" section not updated in 42 days
  ○ [info]    pattern-zero-match         glob pattern "tests/**" matches 0 files


  3 findings  (1 error, 1 warning, 1 info)

The score drops below 70 if any error-severity findings exist.

3. Create a Minimal workspace.json

Section titled “3. Create a Minimal workspace.json”

The minimum valid agents.workspace.json for v0.3 requires all four sections:

{
  "manual": {},
  "generated": {
    "specVersion": "0.3",
    "generatedAt": "2026-05-12T00:00:00.000Z",
    "by": { "name": "your-tool", "version": "1.0.0" }
  },
  "agents": {},
  "health": {}
}

Create it at .agents/agents.workspace.json:

Terminal window
mkdir -p .agents
cat > .agents/agents.workspace.json << 'EOF'
{
  "manual": {},
  "generated": {
    "specVersion": "0.3",
    "generatedAt": "2026-05-12T00:00:00.000Z",
    "by": { "name": "manual", "version": "0.0.0" }
  },
  "agents": {},
  "health": {}
}
EOF

Commit it:

Terminal window
git add .agents/agents.workspace.json
git commit -m "chore: add agents.workspace.json"

Richer fields add value

Section titled “Richer fields add value”

A minimal file is valid and useful. The manual section is the best place to start adding human-authored context:

{
  "manual": {
    "description": "TypeScript monorepo with pnpm workspaces",
    "techStack": ["TypeScript", "Next.js", "pnpm"],
    "fragileFiles": [
      { "path": "packages/contracts/src/index.ts", "reason": "All consumers depend on this" }
    ]
  },
  "generated": {
    "specVersion": "0.3",
    "generatedAt": "2026-05-12T00:00:00.000Z",
    "by": { "name": "your-tool", "version": "1.0.0" }
  },
  "agents": {},
  "health": {}
}

See the full spec for all available fields. The JSON Schema can validate your file against the spec.

4. Validate Your File

Section titled “4. Validate Your File”

Validate schema compliance:

Terminal window
npx agents-audit

agents-audit will report any schema violations alongside its hygiene findings.

For schema-only validation using the published JSON Schema, use any JSON Schema validator with https://www.workspacejson.dev/schema/v1.json.

5. Set Up CI Validation

Section titled “5. Set Up CI Validation”

Add this step to your GitHub Actions workflow:

name: Audit


on: [push, pull_request]


jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4


      - name: Audit AGENTS.md and workspace.json
        run: npx --yes agents-audit --fail-on=error

The --fail-on=error flag exits non-zero on error-severity findings, making the step a blocking CI gate. Warnings and info findings do not block.

Next Steps

Section titled “Next Steps”