AgentReady

Preflight security checks before you give Claude Code, Codex, Cursor, MCP tooling, or another AI coding agent access to a software project.

npx @hephaestus-devkit/agentready quickstart .
npx @hephaestus-devkit/agentready scan .
npx @hephaestus-devkit/agentready badge .

AgentReady runs locally. It does not upload your code, findings, baseline, or configuration.

Why It Exists

AI coding agents can read files, run scripts, modify CI, and connect to MCP servers. AgentReady focuses on the trust boundary just before that access is granted: it shows which repository risks should be fixed, reviewed, ignored, or baselined before an agent works in the project.

The project is intentionally small: a Node.js CLI with zero runtime dependencies, machine-readable reports, CI support, and starter agent boundary files.

Capabilities

• CLI commands: scan, quickstart, init, doctor, baseline, debt, badge, config validate, list-rules, and version
• Agent Readiness Score (0–100) with shields.io badge generation
• Text, JSON, Markdown, and SARIF report output
• GitHub composite action support through action.yml
• Baseline support for reviewed legacy findings, including diff and prune
• Report controls for PR-friendly grouping, summary-only output, and scan-size caps
• Zero runtime dependencies — the scanner itself has no supply chain risk
• Verified with npm run market:check, including tests, self-scan, config validation, npm package dry-run, tarball smoke, link checks, and public-surface cleanup checks

Example Output

AgentReady Report
Root: /path/to/project
Generated: 2026-07-26T09:00:00.000Z
Duration: 48ms
Files scanned: 184
Status: action required
Config: /path/to/project/.agentready.json
CI fail threshold: medium
Summary: high=1 medium=2 low=1 info=0

Top risks:
- [HIGH] .env:2 Secret-like assignment is present
- [MEDIUM] .github/workflows/agent.yml:12 GitHub Actions grants contents write permission

Next steps:
- Fix high severity findings before giving an AI agent broad repository access.
- Save a markdown report with agentready scan . --format markdown --output agentready-report.md for review.

What It Checks

• Known secret formats and generic secret-like assignments in sensitive files, sensitive directories, and agent-readable templates
• Risky package scripts, shell scripts, Dockerfile/Makefile-style project files, and GitHub Actions run commands
• Overbroad GitHub Actions permissions, pull_request_target, inherited secrets, floating action references, and unsafe pull_request_target checkout patterns
• MCP configurations with shell tools, broad filesystem access, inline secret values, authorization forwarding, OAuth client settings, remote URLs, private network URLs, or cloud metadata endpoints
• Missing AGENTS.md and .agentignore boundaries
• Python reproducibility issues such as unpinned requirements

Install

Requires Node.js 20 or newer. Start without installing:

npx @hephaestus-devkit/agentready quickstart .
npx @hephaestus-devkit/agentready scan .
pnpm dlx @hephaestus-devkit/agentready scan .
yarn dlx @hephaestus-devkit/agentready scan .
bunx @hephaestus-devkit/agentready scan .

Install in a project:

npm install -D @hephaestus-devkit/agentready
npx @hephaestus-devkit/agentready scan .

Use this repository directly during development:

npm install
npm link
agentready scan .

Common Workflows

Preview the recommended setup path without writing files:

agentready quickstart .

Initialize project boundaries:

agentready init .
agentready init . --preset strict --with-ci
agentready init . --dry-run

Create a report:

agentready scan . --format markdown --output agentready-report.md
agentready scan . --format markdown --group-by category --max-findings 25
agentready scan . --summary-only
agentready scan . --max-file-size 1048576
agentready scan . --format sarif --output agentready.sarif

Use CI mode:

agentready scan . --ci
agentready scan . --ci --fail-on high
agentready scan . --ci --format sarif --output agentready.sarif

Adopt in a legacy project:

agentready scan .
agentready baseline .
agentready baseline diff .
agentready debt .
agentready scan . --baseline .agentready-baseline.json --ci
agentready baseline prune .

Inspect rules:

agentready list-rules
agentready list-rules --category github-actions
agentready list-rules --severity high

Validate configuration:

agentready config validate .

GitHub Actions

name: agentready

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  security-events: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: Hephaestus-DevKit/[email protected]
        with:
          fail-on: medium
          format: sarif
          output: agentready.sarif
          upload-sarif: true

See CI usage for report-only, baseline, and direct npx modes.

Agent Readiness Score

AgentReady calculates a readiness score from 0 to 100 based on scan findings:

agentready badge .
agentready badge . --format json
agentready badge . --format markdown

Agent Readiness Score: 92/100 (ready)
Badge URL: https://img.shields.io/badge/AgentReady-Score_92-brightgreen
Markdown: ![AgentReady Score: 92](https://img.shields.io/badge/AgentReady-Score_92-brightgreen)

| Score | Grade | Meaning | |-------|-------|---------| | 90–100 | ready | Safe for agent access | | 70–89 | acceptable | Minor issues to address | | 50–69 | needs-work | Several risks require attention | | 30–49 | at-risk | Significant security gaps | | 0–29 | critical | Not safe for agent access |

Add the badge to your project README to show agent readiness status.

Output Formats

agentready scan . --format text
agentready scan . --format json
agentready scan . --format markdown
agentready scan . --format sarif

Text output is optimized for humans. JSON and SARIF are intended for automation and CI.

Configuration

AgentReady automatically reads agentready.config.json or .agentready.json from the scanned project root.

{
  "$schema": "https://raw.githubusercontent.com/Hephaestus-DevKit/agentready/main/schema/agentready.schema.json",
  "baselinePath": ".agentready-baseline.json",
  "failOn": "medium",
  "ignorePaths": ["fixtures/**"],
  "ignoreRules": ["python.unpinned_requirement"],
  "severityOverrides": {
    "package.lifecycle_script": "low"
  },
  "maxFileBytes": 524288
}

Documentation

• Getting started
• Examples
• Evaluation
• CLI reference
• Reports
• Configuration
• Baseline
• Rules
• CI usage
• Supply chain
• Repository settings
• Privacy
• Troubleshooting
• Maintainer guide
• Release checklist
• Changelog

Contributing and Security

See CONTRIBUTING.md for development workflow and rule guidelines. See SECURITY.md for vulnerability reporting and secret-handling guidance.

License

MIT