agent-ready

Turn any repository into an AI-agent-ready codebase.

Install · Quick Start · What it Generates · How it Works · Development

agent-ready is a CLI by BrainboxAI that scans a project and generates the harness AI coding agents need to work safely and effectively: context files, code maps, ignore rules, skills, hook templates, and readiness reports.

It is designed for real repositories—not demo apps. Use it on small apps, legacy codebases, monorepos, service folders, or projects that need a clean onboarding layer for Claude Code and other agentic coding tools.

Warning

agent-ready is an experimental early preview. It is useful today, but its repository detection is heuristic and generated files should be reviewed before committing.

Note

Inspired by Anthropic's Claude Code large-codebase guidance
This project was created after studying Anthropic's article:
How Claude Code works in large codebases: best practices and where to start.
agent-ready turns those ideas—lean CLAUDE.md files, codebase maps, skills, hooks, MCP, LSP, scoped context, and subagent-friendly workflows—into a repeatable CLI workflow.

Table of Contents

• Why agent-ready
• Install
• Quick Start
• What it Generates
• How it Works
• Detected Project Signals
• Code Understanding
• Safety Model
• Limitations
• Example Output
• CLI Reference
• Development
• Roadmap
• Brand
• Acknowledgements
• Contributing
• License

Why agent-ready

AI agents perform best when a repository is legible:

• Where should the agent start searching?
• Which files are generated noise?
• Which test/build commands are safe and local?
• Which project rules belong in always-loaded context?
• Which expertise should load only on demand?
• What should the agent never touch without confirmation?

agent-ready turns those answers into files an agent can actually use.

Instead of manually writing a bloated CLAUDE.md, it creates a layered harness:

CLAUDE.md                    # lean root agent guide
CODEMAP.md                   # repository map for navigation
.aiignore                    # noisy paths to avoid
.claude/settings.json        # versioned deny rules
.agent-ready/report.md       # readiness score and findings
.agent-ready/recommendations.md
.agent-ready/hooks/README.md
.claude/skills/*/SKILL.md       # Claude Code-loadable skills
apps/*/CLAUDE.md             # generated for detected monorepo workspaces

Install

Run with npx

npx @netanelyasi/agent-ready analyze .
npx @netanelyasi/agent-ready init . --dry-run

Install globally

npm install -g @netanelyasi/agent-ready
agent-ready analyze .

From source

git clone https://github.com/Brainboxai-IL/agent-ready.git agent-ready
cd agent-ready
npm install
npm run build
node dist/cli.js analyze .

Published package: @netanelyasi/agent-ready. The CLI binary remains agent-ready after global install.

Quick Start

Analyze a project without writing files:

agent-ready analyze /path/to/project

Preview generated files:

agent-ready init /path/to/project --dry-run

Preview generated file contents:

agent-ready init /path/to/project --dry-run --verbose

Run agent-ready init manually from your terminal, not from inside an autonomous coding agent. It writes agent harness files such as CLAUDE.md, .claude/settings.json, and .claude/hooks/*, which some agent security classifiers correctly treat as self-modification.

Generate the harness:

agent-ready init /path/to/project

Overwrite existing generated files intentionally:

agent-ready init /path/to/project --force

By default, existing files are not overwritten. If CLAUDE.md already exists, agent-ready writes:

CLAUDE.md.agent-ready-proposed

What it Generates

CLAUDE.md

A lean root guide for AI agents:

• project overview (extracted from the README tagline/first paragraph, or package.json description)
• project snapshot
• detected stack
• required environment variables (names only, from .env.example-style files)
• important directories
• validation commands
• operating rules
• critical framework/database notes

It is intentionally short. Task-specific expertise is placed in skills instead of loading into every session.

CODEMAP.md

A navigation map for agents before broad search:

• detected entry points
• central files by internal import usage
• representative internal import graph
• external dependencies used in source files
• top-level directory purpose
• workspace/package manifests
• search guidance
• high-signal project structure

.aiignore

Common noise exclusions:

node_modules/
.next/
dist/
build/
coverage/
.turbo/
vendor/
generated/
**/*.generated.*

.claude/settings.json

Versioned deny rules and runnable Claude Code hooks so every developer gets the same baseline safety.

Generated hooks include:

• PreToolUse for Bash — blocks destructive commands such as rm -rf, git reset --hard, git clean -f, and force-pushes.
• PreToolUse for Write|Edit|MultiEdit — blocks edits to generated/noisy paths such as node_modules, dist, build, coverage, .next, vendor, and *.generated.*.
• PostToolUse for Write|Edit|MultiEdit — reminds the agent which local validation command to run after edits.

.claude/skills/*/SKILL.md

On-demand task expertise. Examples:

• codebase-navigation
• validation
• nextjs-hydration
• supabase-debugging
• rtl-ui
• deployment

Skills are generated only when matching project signals are detected.

.claude/hooks/*.mjs

Runnable hook scripts wired by .claude/settings.json:

• .claude/hooks/prevent-destructive.mjs
• .claude/hooks/protect-generated.mjs
• .claude/hooks/suggest-validation.mjs

.agent-ready/hooks/README.md

Human-readable hook policy notes for maintainers. The actual Claude Code hooks are generated under .claude/hooks and wired in .claude/settings.json.

Workspace CLAUDE.md files

In monorepos, agent-ready creates local guides next to detected package manifests, for example:

apps/web/CLAUDE.md
packages/db/CLAUDE.md
services/api/CLAUDE.md

Each one contains local commands and navigation rules for that workspace.

How it Works

agent-ready scans the repository directly from disk. It does not upload code, build embeddings, or require a remote index.

The scanner detects:

1. package manifests and scripts
2. languages and frameworks
3. database/tooling signals
4. deployment infrastructure
5. monorepo/workspace layout
6. important directories
7. noisy/generated paths
8. existing AI harness files

Then it generates a practical agent harness and assigns an Agent Readiness Score.

Important: the score does not give full credit for files that agent-ready generated itself. Generated files are treated as a baseline. They only become readiness signal after maintainers review and customize them.

Detected Project Signals

Current detection includes:

Area	Signals
JavaScript/TypeScript	package.json, lockfiles, scripts, TS/JS files
Frameworks	Next.js, React, Vue, Nuxt, SvelteKit, Vite, Express, NestJS
Other languages	Python, PHP, Java, C#, Go, Rust, C/C++
Databases	Supabase, Prisma, Drizzle, PostgreSQL, MySQL, MongoDB
Monorepos	Turborepo, Nx, pnpm workspaces, package workspaces
Deployment	Docker, GitHub Actions, Vercel, Netlify, Cloudflare Workers
UI traits	Hebrew/RTL detection
Project context	README description/tagline, required env vars from .env.example
Validation	build, test, lint, typecheck, format scripts

Code Understanding

agent-ready is moving beyond boilerplate generation. It now builds a lightweight static map for JavaScript, TypeScript, Python, Go, and Rust projects:

• package/script entry points
• common CLI, server, app, route, Python, Go, and Rust entry files — including projects with no package.json
• manifest-declared entry points: package.json bin, pyproject.toml console scripts, and Cargo.toml [[bin]] paths
• JS/TS imports, including TypeScript source imported with runtime .js specifiers
• Python import / from ... import ... relationships, including relative modules
• Go imports resolved through the local go.mod module path
• Rust mod declarations and basic crate:: / self:: / super:: use paths
• central files ranked by inbound imports
• external (third-party) packages imported by source files, with language standard libraries filtered out

This makes CODEMAP.md useful as a code navigation artifact, not just a formatted directory listing.

Safety Model

agent-ready is conservative by default.

• No overwrite by default — existing files produce *.agent-ready-proposed.
• Dry-run supported — preview before writing.
• Runnable hooks generated — safety checks are wired in .claude/settings.json, not just described in documentation.
• Generated noise is denied — build/vendor/generated paths are excluded and protected by a PreToolUse hook.
• Root context stays lean — deep knowledge goes into skills.
• Local validation preferred — workspace commands are favored over full-repo commands.
• No self-inflating score — generated files are not counted as maintainer-authored readiness until reviewed/customized.

Limitations

agent-ready is intentionally conservative and heuristic.

• Detection can miss custom frameworks, unusual scripts, and non-standard repository layouts.
• Generated files are a strong starting point, not a replacement for maintainer review.
• Static code understanding covers JS/TS plus first-pass Python/Go/Rust import graphs. PHP/Java/C#/C/C++ are detected but do not yet get import graph mapping.
• It does not yet perform deep semantic analysis of README files, CI workflows, environment variables, or architecture docs.
• It does not upload code or call remote AI services.
• It is not affiliated with or endorsed by Anthropic.

Example Output

Agent Ready: my-app
Root: /code/my-app
Score: 72/100
Languages: TypeScript, Python
Frameworks: Next.js, React
Databases/tools: Supabase
Deployment: Docker, GitHub Actions
Monorepo: yes (Turborepo, pnpm workspaces)

Missing:
- No CODEMAP.md / codebase map
- No reusable skills directory

Generating 14 files:
- created: CLAUDE.md
- created: CODEMAP.md
- created: .aiignore
- created: .claude/settings.json
- created: .agent-ready/report.md
- created: .agent-ready/recommendations.md
- created: .agent-ready/hooks/README.md
- created: .claude/skills/codebase-navigation/SKILL.md
- created: .claude/skills/validation/SKILL.md
- created: .claude/skills/nextjs-hydration/SKILL.md
- created: .claude/skills/supabase-debugging/SKILL.md
- created: apps/web/CLAUDE.md
- created: packages/db/CLAUDE.md

CLI Reference

agent-ready analyze [path]

Scan a project and print the readiness summary. Does not write files.

agent-ready init [path]

Scan a project and generate the AI-agent harness.

agent-ready init [path] --dry-run

Show which files would be generated without writing anything.

agent-ready init [path] --dry-run --verbose

Show the generated contents too. Use this before deciding whether to run init for real or manually merge proposed files.

agent-ready init [path] --force

Overwrite existing files instead of writing *.agent-ready-proposed.

When existing harness files are present, default init writes *.agent-ready-proposed files. Review and manually merge them; agent-ready does not assume its generated CLAUDE.md is better than a maintainer-authored one.

Development

Requirements:

• Node.js
• npm

Install dependencies:

npm install

Run in development:

npm run dev -- analyze .
npm run dev -- init . --dry-run

Type-check:

npm run check

Run tests:

npm test

Build:

npm run build

Run compiled CLI:

node dist/cli.js analyze .

Roadmap

Planned improvements:

• deeper config/CI-workflow analysis (README description and .env.example vars already extracted)
• richer monorepo workspace detection
• generated CONTRIBUTING.md and SECURITY.md templates
• optional AI-assisted repository summary mode
• plugin/export presets for Claude Code, Cursor, Codex, and other agents
• CI mode for failing builds when agent readiness drops below a threshold

Brand

agent-ready is built by BrainboxAI.

BrainboxAI builds practical AI-agent infrastructure: tools, workflows, and automation systems that help teams move from ad-hoc prompting to reliable agent operations.

Acknowledgements

agent-ready was created after studying Anthropic's guidance on making large codebases navigable for Claude Code.

Reference article
How Claude Code works in large codebases: best practices and where to start — Anthropic.

The core idea is to turn those best practices into a repeatable CLI workflow:

• scan the repository
• generate lean, layered context
• map the codebase before broad search
• separate reusable expertise into skills
• document hooks, validation paths, MCP, and LSP recommendations
• keep generated/build/vendor noise away from agents

This project is independent and is not affiliated with or endorsed by Anthropic.

Contributing

Contributions are welcome once the public repository is available.

Before opening a pull request:

1. Run npm run check.
2. Run npm run build.
3. Test the CLI on at least one real project with --dry-run.
4. Keep generated context lean; do not move task-specific expertise into root CLAUDE.md templates.

License

MIT © BrainboxAI