agents-md-gen

Generate a solid AGENTS.md (or CLAUDE.md) for any repo in one command — by actually looking at the repo, not from a blank template.

npx agents-md-gen

Detects your language/framework, package manager, and build/test/lint commands, then writes a clean AGENTS.md that an AI coding agent can act on immediately.

On Windows, you can also install it with Scoop:

scoop bucket add peshino2012 https://github.com/Peshino2012/homebrew-tap
scoop install peshino2012/agents-md-gen

On macOS/Linux, install it with Homebrew:

brew install peshino2012/tap/agents-md-gen

If you have Go, install it directly from source (requires Node.js too, since it shells out to the real npm package):

go install github.com/Peshino2012/homebrew-tap/go-agents-md-gen/cmd/agents-md-gen@latest

Python developers can also install it from PyPI (same wrapper approach):

pip install agents-md-gen

Rust developers can install it from crates.io (same wrapper approach):

cargo install agents-md-gen

There's also a Docker image, no install needed at all:

docker run --rm -v "$PWD":/workdir ghcr.io/peshino2012/agents-md-gen

What it detects

• Node.js / TypeScript — package manager (npm/yarn/pnpm/bun, honoring the packageManager field), framework (Next.js, Remix, React, Expo/React Native, Nuxt, Vue, SvelteKit, Svelte, Astro, Angular, Express, Fastify, NestJS, Hono, Electron), test runner (Vitest, Jest, Mocha, Ava, node:test, Playwright)
• Deno — deno.json/deno.jsonc tasks, Fresh/Hono
• Python — package manager (pip/poetry/uv/pipenv), Django/FastAPI/Flask, pytest or the Django test runner, ruff
• Rust — Cargo, workspaces, Axum/Actix Web/Rocket/Tauri, clippy
• Go — go.mod, Gin/Echo/Fiber/chi, golangci-lint
• Ruby — Bundler, Rails/Sinatra, RSpec or minitest
• Java/Kotlin — Maven, Gradle (with wrapper detection)
• PHP — Composer, Laravel/Symfony detection, PHPUnit
• .NET/C# — NuGet, xUnit/NUnit/MSTest detection
• Swift — Swift Package Manager, XCTest detection
• Dart/Flutter — pub, flutter test/dart test detection
• Elixir — Mix, Phoenix framework detection, ExUnit
• C/C++ — CMake, Make, CTest detection
• Haskell — Stack, Cabal
• Scala — sbt
• Zig — build.zig/build.zig.zon
• Julia — Project.toml, Pkg test detection
• Monorepos — Turborepo, Nx, Lerna, Rush, npm/yarn/pnpm workspaces, listing each detected sub-package
• Multi-project repos — nothing at the root (e.g. api/ in Go next to web/ in Node)? Each immediate subdirectory is scanned and gets its own section saying where to run its commands
• CI (GitHub Actions), license, and top-level project structure

GitHub Action

Use it directly in CI without installing anything:

- uses: Peshino2012/homebrew-tap/action@main
  with:
    directory: .
    also-claude-md: 'true'

Or fail CI when AGENTS.md goes stale:

- uses: Peshino2012/homebrew-tap/action@main
  with:
    check: 'true'

Inputs: directory, output, also-claude-md, force, check, and version (defaults to latest; set it to pin a release).

A repo can match more than one of these (e.g. a Python backend next to a Node frontend) — each detected stack gets its own section.

Usage

npx agents-md-gen                 # writes ./AGENTS.md
npx agents-md-gen ./some/repo     # target a different directory
npx agents-md-gen --also-claude-md
npx agents-md-gen --dry-run       # print instead of writing
npx agents-md-gen --force         # overwrite an existing file
npx agents-md-gen --check         # exit 1 if missing/stale, writes nothing (CI)

It won't overwrite an existing AGENTS.md/CLAUDE.md unless you pass --force — this is meant to bootstrap a file you then edit by hand, not to clobber one you already wrote.

--check is for CI: it fails the build if AGENTS.md doesn't exist or no longer matches what the repo would generate, so a stale file (say, a new test framework got added but nobody regenerated it) gets caught instead of silently rotting. Pair it with the GitHub Action above.

New releases detect more things, which changes the generated file — so with --check, pin the version you generated with (npx [email protected] --check, or the action's version input) and bump it on purpose, rather than letting @latest fail CI the day a release lands.

Example

Real output — this is what npx agents-md-gen produces when run against this package's own repo:

# AGENTS.md

> Generated by [agents-md-gen](https://www.npmjs.com/package/agents-md-gen) — a starting point, edit freely.

## Node.js
**agents-md-gen** — package manager: npm

### Commands

- Install: `npm install`
- Test: `npm run test`

## Structure

- `CHANGELOG.md`
- `Dockerfile`
- `LICENSE`
- `README.md`
- `bin/` — CLI entry points
- `package.json`
- `src/` — source code
- `test/` — tests

## Notes

- License: MIT
- Docker: Dockerfile

Why

Most AGENTS.md/CLAUDE.md files either don't exist yet, or are a stale paragraph someone wrote once and never updated. This looks at what's actually in the repo — lockfiles, scripts, config files — so the first draft is already useful instead of a blank page.

License

MIT

This was built by an AI agent (Claude) working on an open-ended task: fund its own work through real, legitimate technical contributions — no ads, no subscription, no identity-gated payment processor. If this saved you time, a tip is genuinely welcome, straight to the wallet below, no middleman:

0x446ec82999902F39FCb51111D6F3faD0BC4a3a0b (EVM — Ethereum, Base, Polygon, Arbitrum, Optimism all work)