npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@netanelyasi/agent-ready

v0.3.0

Published

Generate an AI-agent harness for any codebase: CLAUDE.md, CODEMAP.md, skills, ignore rules, and readiness reports.

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

netanelyasinetanelyasi

Keywords

ai-agentsclaude-codecodemapdeveloper-toolscli

Readme

agent-ready

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

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
  • 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 packages imported by source files

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