microsoft/cates

microsoft/cates

Description: Coding Agent Token Economics Standard

Language: TypeScript

License: MIT

Stars: 4

Forks: 0

Open issues: 0

Created: 2026-05-18T18:08:44Z

Pushed: 2026-06-03T13:33:28Z

Default branch: main

Fork: no

Archived: no

README:

CATES Configuration Analyzer

> Score coding-agent configurations for token efficiency, security, and CATES conformance — zero LLM calls required.

This is the reference implementation for the Coding Agent Token Economics Standard (CATES). It is vendor-neutral and analyzes common coding-agent configuration surfaces, including instructions, prompt libraries, MCP configs, setup steps, hooks, and editor settings.

---

🚀 Quick Start

Install

CATES is distributed as an npm package and a Docker image. Pick one:

# 1) Run it once with npx (nothing to install)
npx cates-analyzer .

# 2) Install globally (recommended for repeat use)
npm install -g cates-analyzer
cates-analyzer .

# 3) Add it as a dev dependency in a project
npm install --save-dev cates-analyzer
npx cates-analyzer .

# 4) Run it in Docker (no Node.js required locally)
docker run --rm -v "$PWD:/work" cates-analyzer:latest .

Requires Node.js >= 20 for the npm install paths. The Docker image ships its own runtime plus git and gh.

Use it

# Analyze current directory
cates-analyzer .

# Analyze a specific repo
cates-analyzer /path/to/repo

# JSON output for CI
cates-analyzer . --format json

# SARIF output for code scanning systems
cates-analyzer . --format sarif

# Repository URL, branch folder, file, or pull request
# (auto-detected — also works as `cates-analyzer review `)
cates-analyzer https://github.com/OWNER/REPO
cates-analyzer https://github.com/OWNER/REPO/tree/main/path/to/folder
cates-analyzer https://github.com/OWNER/REPO/pull/123

# Quieter pretty output (drops the banner; keeps all data)
cates-analyzer . --quiet

# Shell completion
cates-analyzer completion bash > /usr/local/etc/bash_completion.d/cates-analyzer
cates-analyzer completion zsh > "${fpath[1]}/_cates-analyzer"

Exit codes:

| Code | Meaning | | --- | --- | | 0 | Analysis succeeded; all CI gates passed | | 1 | CATES gate failed (--min-score, --require-level, --fail-on, --max-always-loaded, or conformance) | | 2 | Usage error (invalid flag, missing argument, parse failure) |

When running from this source checkout before publishing/installing the package, use one of these forms:

npm run --silent review -- https://github.com/OWNER/REPO
npm run --silent cates -- review https://github.com/OWNER/REPO
npx tsx src/cli/index.ts review https://github.com/OWNER/REPO

Do not run tsc review ... or npm run typecheck -- review ...; those commands invoke the TypeScript compiler and it will treat review and the URL as files to compile.

🐳 Docker

A small, non-root Alpine image is the easiest way to get a consistent toolchain across Windows, macOS, and Linux (plus the right git and gh versions baked in).

# Build locally
docker build -t cates-analyzer .

# Analyze the current directory (bind-mount it as /work)
docker run --rm -v "$PWD:/work" cates-analyzer .

# Review a public repo
docker run --rm cates-analyzer review https://github.com/OWNER/REPO

# Review a private repo (token never written to disk)
docker run --rm -e GH_TOKEN cates-analyzer review https://github.com/OWNER/REPO

# JSON to stdout, piped into your tooling
docker run --rm -v "$PWD:/work" cates-analyzer . --format json > report.json

Windows PowerShell users substitute ${PWD} for $PWD.

The image runs as a non-root user, uses a read-only root filesystem, and ships with tini as PID 1 so it behaves cleanly under container orchestrators.

☸️ Helm chart

The chart in [deploy/helm/cates](deploy/helm/cates/README.md) deploys CATES as a CronJob (default) or one-shot Job. It supports NetworkPolicies, a persistent reports volume, and a ConfigMap-mounted .cates.yml policy.

helm install cates ./deploy/helm/cates \
-n cates --create-namespace \
--set image.tag=1.0.0 \
--set githubToken.value=$GH_TOKEN \
--set-json 'args=["demo","--limit","25","--format","json"]'

See [deploy/helm/cates/README.md](deploy/helm/cates/README.md) for production values, Workload Identity setup, and PVC-backed reports.

🌐 CATES Service (hosted UI + HTTP API)

Don't want to install the CLI? Use the CATES Service — a hosted companion that lets you score a primitive in two ways:

1. Paste an instruction file, prompt, MCP config, agent definition, or .cursorrules directly into the browser. 2. Scan a GitHub URL — repo, folder, file, or pull request.

Behind the scenes the service runs the exact same analyzer as the CLI (analyze() / analyzeInMemory()), so a score from the service is identical to a score from cates-analyzer on the same bytes. There are no LLM calls, no telemetry, and no content logging — submitted text is analyzed in-process and discarded; repos fetched via "Scan" are cloned shallowly into a temp directory that is removed as soon as the score is returned.

HTTP API

| Method | Endpoint | Purpose | | --- | --- | --- | | POST | /api/analyze | In-memory analysis. Body: { files: [{path, content}], policy?, tokenizer? }. | | POST | /api/scan | GitHub-URL analysis. Body: { url, policy?, tokenizer? }. | | GET | /api/rules | Full RULE_CATALOG plus service limits, for UIs and tooling. | | GET | /api/healthz | Liveness probe. | | GET | /api/readyz | Readiness probe. |

All endpoints accept and return JSON. The AnalysisResult shape returned by the analyze and scan endpoints is the same type the CLI emits with --format json — every existing report consumer (dashboard, CI gates, SARIF converter) works unchanged.

Service limits (per request)

| Limit | Value | | --- | --- | | Max files per request | 50 | | Max bytes per file | 100 KB | | Max total payload | 1 MB | | Per-IP rate limit | 60 requests / minute |

Limits are exposed live at GET /api/rules so UIs and CI integrations can display them or pre-validate.

Configuration parity

Every toggle and policy field from [⚙️ Configuring CATES](#%EF%B8%8F-configuring-cates) is accepted in the policy field of the request body:

{
"files": [
{ "path": ".github/copilot-instructions.md", "content": "..." }
],
"policy": {
"dimensions": { "security": { "enabled": false } },
"rules": { "TE004": {…