@kodus/agent-readiness

Is your codebase ready for AI agents?

@kodus/agent-readiness — the open-source alternative to Factory.ai's Agent Readiness.

Evaluate how ready your codebase is for autonomous AI coding agents like Claude Code, Cursor, GitHub Copilot, and Codex. 39 automated checks, 7 pillars, 10+ languages. One command:

bunx @kodus/agent-readiness .

Quick Demo

$ bunx @kodus/agent-readiness .

  @kodus/agent-readiness v0.1.2

  Repository: my-project
  Project types: node
  ──────────────────────────────────────────

  Maturity Level: 3 - Structured ███████████░░░░░ 65%

  ┌───────────────────────┬────────┬───────┐
  │ Pillar                │ Score  │ Status│
  ├───────────────────────┼────────┼───────┤
  │ 🎨 Style & Linting   │  4/6   │  67%  │
  │ 🧪 Testing           │  3/6   │  50%  │
  │ 📚 Documentation      │  5/8   │  63%  │
  │ 🔧 Dev Environment   │  4/5   │  80%  │
  │ ⚙️  CI/CD             │  4/6   │  67%  │
  │ 💚 Code Health        │  1/3   │  33%  │
  │ 🔒 Security           │  3/5   │  60%  │
  └───────────────────────┴────────┴───────┘

  Recommendations:
  [LOW]  Add .editorconfig for consistent formatting
  [MED]  Configure test coverage reporting
  [MED]  Add architecture decision records

Why Agent Readiness Matters

AI coding agents like Claude Code, Cursor, GitHub Copilot, OpenAI Codex, and Devin are transforming how software gets built. But their effectiveness depends heavily on how your codebase is structured.

Repos with clear conventions, solid test suites, good documentation, and consistent CI/CD pipelines let AI agents work autonomously with fewer errors and hallucinations. Repos without these foundations force agents into guesswork.

Agent readiness is the measure of how well your codebase supports autonomous AI coding. Factory.ai popularized this concept, but their solution is proprietary and cloud-only. @kodus/agent-readiness brings the same evaluation to everyone -- open source, free, and running entirely on your machine.

Why Open Source?

Factory.ai popularized the concept of "Agent Readiness" — but their solution is proprietary, cloud-only, and tied to their own AI agents.

We believe every team deserves to know how ready their codebase is, without sending code to third-party servers or paying for a score. @kodus/agent-readiness runs entirely on your machine, works with any AI agent, and is free forever.

@kodus/agent-readiness vs Factory.ai

Feature	@kodus/agent-readiness	Factory.ai
Open Source	MIT License	Proprietary
Pricing	Free forever	Token-based billing
Vendor lock-in	None -- agent-agnostic	Tied to Factory Droids
Self-hosted	Runs locally on your machine	Cloud only
Data privacy	Your code never leaves your machine	Sent to their servers
Customizable	Fully configurable via .kodus-readiness.yml	Limited
CI/CD integration	--ci + --min-level flags	API only
Languages	Node, Python, Go, Rust, Java, Kotlin, C#, Ruby, PHP, Swift	Limited

Features

• 39 automated checks across 7 pillars of codebase readiness
• 5 maturity levels from Foundational to Autonomous
• Interactive web dashboard with radar charts and detailed breakdowns
• AI-powered analysis (optional) via --ai flag for deeper code evaluation
• Multi-language support: Node.js, Python, Go, Rust, Java, Kotlin, C#/.NET, Ruby, PHP, Swift
• Monorepo detection: npm/yarn/pnpm workspaces, Lerna, Nx, Turborepo
• CI/CD gates with --ci and --min-level for quality enforcement
• Fully configurable via .kodus-readiness.yml
• JSON output for programmatic integrations

Quick Start

Run it instantly with no installation:

# Using bun
bunx @kodus/agent-readiness .

# Using npx
npx @kodus/agent-readiness .

# Evaluate a specific repository
bunx @kodus/agent-readiness /path/to/repo

# With AI-powered analysis
bunx @kodus/agent-readiness . --ai --api-key sk-your-key

# JSON output for integrations
bunx @kodus/agent-readiness . --format json

# CI mode with minimum level gate
bunx @kodus/agent-readiness . --ci --min-level 3

The 7 Pillars

Agent readiness is evaluated across seven pillars, each covering a critical aspect of codebase health for AI agents:

Pillar	Description	Checks
🎨 Style & Linting	Consistent code style and static analysis enforcement	Linter, formatter, type checker, pre-commit hooks, editorconfig, naming conventions
🧪 Testing	Presence, breadth, and automation of your test suite	Test framework, test files, test script, coverage config, E2E tests, test quality
📚 Documentation	Quality and breadth of documentation for humans and AI	README, contributing guide, API docs, CODEOWNERS, AI context files, architecture docs, README quality, agent-friendliness
🔧 Dev Environment	Reproducible, well-documented developer setup	Lock file, containerization, env documentation, setup scripts, version pinning
⚙️ CI/CD	Continuous integration and delivery pipeline coverage	CI config, CI runs tests, CI runs linters, build automation, deploy pipeline, branch protection
💚 Code Health	Dependency freshness, dead code, and bundle hygiene	Outdated deps detection, dead code detection, bundle analysis
🔒 Security	Security posture including scanning and secret detection	License, security scanning, secrets detection, security policy, dependency update automation

Maturity Levels

Your codebase is assigned a maturity level based on which criteria pass at each tier. You must pass at least 80% of criteria at a level to advance to the next.

Level	Name	Description
1	Foundational	Basic setup and essential files present (README, license, lock file, editorconfig)
2	Guided	Core tooling configured -- linters, formatters, test frameworks, CI basics
3	Structured	Good practices established -- type checking, pre-commit hooks, security policies, containerization
4	Optimized	Advanced practices -- coverage reporting, E2E tests, deploy pipelines, security scanning
5	Autonomous	Maximum AI agent readiness -- AI context files, architecture docs, naming conventions, bundle analysis

CLI Usage

Usage: agent-readiness [path] [options]

Arguments:
  path                   Path to the repository to evaluate (default: current directory)

Options:
  --ai                   Enable AI-powered criteria evaluation
  --api-key <key>        API key for AI evaluations (or set KODUS_API_KEY / OPENAI_API_KEY)
  --ci                   Run in CI mode (non-interactive, exit code reflects level)
  --format <format>      Output format: "text" or "json" (default: "text")
  --min-level <n>        Minimum maturity level required (1-5). Exits with code 1 if below threshold
  --no-color             Disable colored output
  --no-web               Disable the web dashboard
  --init                 Generate a .kodus-readiness.yml config file and exit
  -V, --version          Show version number
  -h, --help             Show help

Environment Variables

Variable	Description
KODUS_API_KEY	API key for AI-powered evaluations
OPENAI_API_KEY	Fallback API key for AI evaluations
CI	When set to "true", automatically enables CI mode

Web Dashboard

After running an evaluation, an interactive web dashboard opens automatically in your browser. It provides:

• Radar chart visualizing scores across all 7 pillars
• Detailed criterion breakdown with pass/fail status and messages
• Recommendations prioritized by impact and effort
• Project overview including detected languages and monorepo structure

To disable the dashboard, use the --no-web flag:

bunx @kodus/agent-readiness . --no-web

Configuration

Generate a default configuration file:

bunx @kodus/agent-readiness --init

This creates a .kodus-readiness.yml in your repository root:

# Toggle entire pillars on or off
pillars:
  style-linting: true
  testing: true
  documentation: true
  dev-environment: true
  ci-cd: true
  code-health: true
  security: true

# Fine-grained toggles for individual criteria
criteria:
  # Style & Linting
  linter: true
  formatter: true
  type-checker: true
  pre-commit-hooks: true
  editorconfig: true
  naming-conventions: true

  # Testing
  test-framework: true
  test-files-exist: true
  test-script: true
  coverage-config: true
  e2e-tests: true
  test-quality: true

  # Documentation
  readme: true
  contributing: true
  api-docs: true
  codeowners: true
  ai-context: true
  architecture-docs: true
  readme-quality: true
  docs-agent-friendliness: true

  # Dev Environment
  lock-file: true
  containerization: true
  env-documentation: true
  setup-script: true
  version-pinned: true

  # CI/CD
  ci-config: true
  ci-runs-tests: true
  ci-runs-linters: true
  build-automated: true
  deploy-pipeline: true
  branch-protection: true

  # Code Health
  no-outdated-deps: true
  dead-code-detection: true
  bundle-analysis: true

  # Security
  license: true
  security-scanning: true
  secrets-detection: true
  security-policy: true
  dep-update-automation: true

# Thresholds
thresholds:
  # Minimum percentage of criteria that must pass to reach a level (default: 0.8)
  # level-pass: 0.8

# AI Settings
# aiEnabled: false
# apiKey: ""           # Or set KODUS_API_KEY env variable
# apiBaseUrl: ""       # Custom endpoint for the LLM API

CLI flags always override config file values.

CI/CD Integration

Use @kodus/agent-readiness as a quality gate in your CI pipeline. The --ci flag enables non-interactive mode, and --min-level fails the build if your codebase doesn't meet the required maturity level.

GitHub Actions

name: Agent Readiness Check

on: [push, pull_request]

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

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - name: Check AI Agent Readiness
        run: bunx @kodus/agent-readiness . --ci --min-level 3

With AI-Powered Analysis

      - name: Check AI Agent Readiness (with AI)
        run: bunx @kodus/agent-readiness . --ci --min-level 3 --ai
        env:
          KODUS_API_KEY: ${{ secrets.KODUS_API_KEY }}

Exit Codes

Code	Meaning
0	Passed -- maturity level meets or exceeds --min-level
1	Failed -- maturity level is below --min-level

AI-Powered Analysis

Four criteria use AI for deeper evaluation that goes beyond file detection:

Criterion	What It Evaluates
naming-conventions	File and function naming consistency (kebab-case, camelCase, PascalCase)
test-quality	Whether tests are meaningful, well-structured, and cover key functionality
readme-quality	README effectiveness -- project purpose, setup, usage, contributing instructions
docs-agent-friendliness	Whether documentation helps AI agents understand and navigate the codebase

Enable AI analysis:

# Using --api-key flag
bunx @kodus/agent-readiness . --ai --api-key sk-your-key

# Using environment variable
export KODUS_API_KEY=sk-your-key
bunx @kodus/agent-readiness . --ai

Uses an OpenAI-compatible API. Configure a custom endpoint in .kodus-readiness.yml:

aiEnabled: true
apiKey: "sk-your-key"
apiBaseUrl: "https://your-custom-endpoint.com/v1"

Without --ai, AI-powered criteria are skipped (not counted as failures).

All Checks

39 checks across 7 pillars, covering 10+ languages (Node.js, Python, Go, Rust, Java, Kotlin, C#, Ruby, PHP, Swift). 4 checks use optional AI analysis for deeper evaluation.

View all 39 criteria across 7 pillars

🎨 Style & Linting

Criterion	Level	AI	What It Detects
editorconfig	1	No	.editorconfig file
linter	2	No	ESLint, Biome, Ruff, golangci-lint, detekt, ktlint, Checkstyle, PMD, SpotBugs, clippy, StyleCop, Roslyn analyzers, RuboCop, PHPStan, Psalm, PHP_CodeSniffer, SwiftLint
formatter	2	No	Prettier, Biome, Black, Ruff, gofmt, ktlint, ktfmt, Spotless, google-java-format, rustfmt, dotnet format (built-in), RuboCop, PHP-CS-Fixer, SwiftFormat
type-checker	3	No	TypeScript strict, mypy, pyright, Kotlin/Go/Java/Rust/C#/Swift (built-in static types)
pre-commit-hooks	3	No	Husky, Lefthook, pre-commit, lint-staged
naming-conventions	5	Yes	File/function naming patterns and consistency

🧪 Testing

Criterion	Level	AI	What It Detects
test-framework	2	No	Jest, Vitest, pytest, Go test, JUnit, TestNG, Kotest, Rust #[test], xUnit/NUnit/MSTest, RSpec, Minitest, PHPUnit, XCTest
test-files-exist	2	No	*.test.*, *.spec.*, test_*.py, *_test.go, *Test.kt, *Test.java, tests/*.rs, *Test.cs, *_spec.rb, *Test.php, *Tests.swift
test-script	2	No	package.json, Makefile, Gradle, Maven, Cargo, dotnet test, Rakefile, composer.json, swift test
coverage-config	4	No	nyc, Jest, Vitest, .coveragerc, JaCoCo, Kover, tarpaulin, cargo-llvm-cov, Coverlet, SimpleCov, PHPUnit coverage
e2e-tests	4	No	Playwright, Cypress, E2E/integration directories
test-quality	5	Yes	Test meaningfulness and coverage of key functionality

📚 Documentation

Criterion	Level	AI	What It Detects
readme	1	No	README.md with substantive content (>500 chars)
contributing	2	No	CONTRIBUTING.md
api-docs	3	No	OpenAPI/Swagger specs, JSDoc/TypeDoc config
codeowners	3	No	CODEOWNERS file
ai-context	3	No	CLAUDE.md, .cursorrules, copilot-instructions.md
architecture-docs	4	No	Architecture docs, ADRs
readme-quality	5	Yes	README effectiveness and completeness
docs-agent-friendliness	5	Yes	Whether docs help AI agents understand the codebase

🔧 Dev Environment

Criterion	Level	AI	What It Detects
lock-file	1	No	package-lock.json, bun.lockb, yarn.lock, go.sum, Cargo.lock, gradle.lockfile, packages.lock.json, Gemfile.lock, composer.lock, Package.resolved
env-documentation	2	No	.env.example, .env.template
setup-script	2	No	Makefile targets, setup scripts, dev script, Gradle wrapper, Maven wrapper, .sln (dotnet), Rakefile
version-pinned	2	No	.nvmrc, .python-version, .tool-versions, mise.toml, .sdkmanrc, .java-version, rust-toolchain.toml, .ruby-version, .php-version, .swift-version, global.json
containerization	3	No	Dockerfile, docker-compose, devcontainers

⚙️ CI/CD

Criterion	Level	AI	What It Detects
ci-config	2	No	GitHub Actions, GitLab CI, CircleCI, Jenkins, Travis
ci-runs-tests	3	No	Test commands in CI workflows (npm/yarn/pnpm/bun test, Jest, Vitest, pytest, go test, Gradle, Maven, cargo test, dotnet test, bundle exec rspec/rake, phpunit, composer test, swift test)
ci-runs-linters	3	No	Lint commands in CI workflows (ESLint, Biome, Ruff, golangci-lint, ktlint, detekt, Spotless, Checkstyle, PMD, cargo clippy, cargo fmt, dotnet format, rubocop, phpstan, psalm, phpcs, swiftlint)
build-automated	3	No	Build scripts and CI build steps (npm/yarn build, Gradle, Maven, go build, cargo build, docker build, poetry build, dotnet build/publish, swift build, xcodebuild)
deploy-pipeline	4	No	Deploy/release jobs, Vercel, Netlify, Fly.io, Terraform
branch-protection	4	No	Branch protection rules and settings

💚 Code Health

Criterion	Level	AI	What It Detects
no-outdated-deps	3	No	Lock file freshness across all languages (npm, yarn, pnpm, bun, Gradle, Poetry, Pipfile, go.sum, Cargo.lock, packages.lock.json, Gemfile.lock, composer.lock, Package.resolved)
dead-code-detection	4	No	Knip, unused-exports ESLint plugin, detekt, vulture (Python), cargo-udeps (Rust), SpotBugs/FindBugs (Java), Roslynator (C#), debride/reek (Ruby), PHPMD (PHP)
bundle-analysis	5	No	webpack-bundle-analyzer, @next/bundle-analyzer, size-limit

🔒 Security

Criterion	Level	AI	What It Detects
license	1	No	LICENSE file
security-policy	3	No	SECURITY.md
dep-update-automation	3	No	Dependabot, Renovate, Gradle versions plugin
security-scanning	4	No	CodeQL, Snyk, Trivy, Semgrep, SonarQube, OWASP dependency-check, cargo-audit, SecurityCodeScan (C#), brakeman/bundler-audit (Ruby), roave/security-advisories (PHP)
secrets-detection	4	No	gitleaks, detect-secrets in pre-commit or CI

Contributing

Contributions are welcome! Here's how to get started:

# Clone the repo
git clone https://github.com/kodus-ai/agent-readiness.git
cd agent-readiness

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run the web dashboard in dev mode
bun run dev:web

# Type check
bun run typecheck

# Lint
bun run lint

# Build everything
bun run build:all

To add a new criterion, create a check function in the appropriate pillar file under src/pillars/ and register it in the pillar's criteria array.

License

MIT -- see LICENSE for details.

Built with care by Kodus · GitHub