agentize

Generate AGENTS.md (and optionally CLAUDE.md / .cursorrules) from a codebase's actual config — every command sourced from a real file, nothing invented.

Works offline. Zero dependencies. Requires Python 3.11+.

Install

Pick whichever fits your setup — all of these are copy-paste ready.

Option 1 — uv (recommended, one command):

uv tool install --from git+https://github.com/ahm3d-karim/agentize.git agentize-cli
agentize --help

Option 2 — pip:

pip install git+https://github.com/ahm3d-karim/agentize.git
agentize --help

Option 3 — single file, no install at all:

curl -fsSL -o agentize.py https://raw.githubusercontent.com/ahm3d-karim/agentize/main/agentize.py
python agentize.py --help

Option 4 — from source:

git clone https://github.com/ahm3d-karim/agentize.git
cd agentize
uv tool install .
agentize --help

Windows note: if agentize isn't recognized after installing, run uv tool update-shell, then close and reopen your terminal. Still stuck? Add C:\Users\<you>\.local\bin to your PATH — that's where uv (and pip, in user mode) put tool binaries.

Name note: the PyPI distribution is agentize-cli (the bare agentize name is taken), but the command stays agentize in every install path above.

Quick start

agentize            # interactive menu: generate here / GitHub PRs / AI polish / pick a repo
agentize .          # write AGENTS.md for the current folder
agentize ../other   # any folder
agentize . --stdout # preview without writing
agentize . --check  # CI-friendly: exit 0 if AGENTS.md is current, 1 if stale or missing

The bare menu's option 5 ("Select repo") lists every git repo in the tree (depth ≤ 3) so you can generate for a subfolder without cd-ing around. GitHub mode checks AGENTS.md existence and clones in parallel — large accounts process in seconds, not minutes.

Non-interactive usage:

agentize .                 # write AGENTS.md in the current repo
agentize path/to/repo      # ...or any other repo
agentize . --stdout        # preview without writing anything
agentize . --claude        # also write CLAUDE.md
agentize . --cursor        # also write .cursor/rules/agentize.mdc (Cursor's current format)
agentize . --gemini        # also write GEMINI.md
agentize . --all           # write every format (AGENTS.md + CLAUDE.md + GEMINI.md + .mdc)
agentize . --force         # overwrite an existing AGENTS.md
agentize . --check         # exit 0 if current, 1 if stale/missing (never writes)
agentize . --check --update  # regenerate the managed block in place; exit 1 if changed
agentize . --diff          # show a unified diff of AGENTS.md vs the fresh render
agentize . --verify        # audit every command listed in AGENTS.md against the repo
agentize . --explain "npm run build"  # show where a command was sourced from
agentize . --install-hook  # install a pre-commit hook that blocks on stale AGENTS.md

Then open the generated AGENTS.md, sanity-check the commands, commit it. Done.

Verify the install worked with:

agentize --version   # → agentize 0.8.0

Example output

agentize . writes an AGENTS.md like this (abridged):

# agentize

> Auto-generated by agentize. Every command below is sourced from
> real config files — review, then keep this file updated as the repo evolves.

> Notes above the `<!-- agentize:start -->` marker are yours to keep;
> everything between the markers is machine-owned and regenerated.

<!-- agentize:start -->

**Stack:** Python

## Setup commands

- Install dependencies: `pip install -e .`

## Testing

- Run all tests: `python -m unittest discover -s tests`

## Command reference (sources)

| Command | Purpose | Source |
|---|---|---|
| `pip install -e .` | install dependencies (editable) | pyproject.toml present |
| `agentize:main` | `agentize` script | pyproject.toml:project.scripts.agentize |
| `python -m unittest discover -s tests` | CI step | .github/workflows/ci.yml |

---
_Generated by agentize 0.8.0 — check the sources above before trusting any command._
<!-- agentize: fingerprint 5b2c… -->
<!-- agentize:end -->

Every command in the table is traceable to a real file — that's the point.

Checking freshness (--check)

Keep AGENTS.md honest in CI or pre-commit hooks:

agentize . --check   # exit 0 if AGENTS.md is up to date
agentize . --check   # exit 1 if it is stale or missing (prints how many lines differ)

--check re-renders AGENTS.md from the current config and compares it to what's on disk — it never writes. It compares only the managed block between the <!-- agentize:start --> / <!-- agentize:end --> markers: hand-written notes above the block (and commit-history sections below it) never cause false staleness. A marker-less file must match byte-for-byte, so pre-marker files fail with a migration hint. Add --claude / --cursor / --gemini to check those files too, and it follows nested AGENTS.md files in monorepo workspaces. Because it returns a real exit code, it drops straight into any CI pipeline.

Self-healing CI (black/prettier convention — exit 1 when it changed something):

agentize . --check --update   # regenerate the managed block in place

Audit the claims themselves — every command in the table must still be derivable from the repo:

agentize . --verify            # exit 1 on any stale/invented command
agentize . --explain "npm run build"   # source file + role for one command
agentize . --diff              # unified diff vs the fresh render

First run

The first time you open the menu, agentize checks your setup (Python, uv, gh) and offers to install anything missing — only after you say yes. Nothing is installed or connected by default. GitHub sign-in is also opt-in: pick GitHub mode and it offers gh auth login (device flow) or a token paste.

Commit history context

When generating for a git repo, agentize can include a "Recent activity" section so agents know what's in flight. Interactive mode asks (defaults: since yesterday, authors all); non-interactive uses flags:

agentize . --since 7d                # commits from the last 7 days
agentize . --since yesterday --authors "Alice, Bob"

GitHub mode: AGENTS.md as pull requests

Connect your GitHub, pick repos (yours or anyone's), and agentize opens a PR adding AGENTS.md to each — the cheat sheet, delivered. Repos you don't own get an automatic fork; runs are idempotent (re-running finds the open PR instead of duplicating it).

agentize --github                       # interactive: pick from your repos
agentize --github --repos ahm3d-karim/agentize,octocat/Hello-World
agentize --github --repos my-tool       # bare names match your account
agentize --github --dry-run             # generate only, push nothing
agentize --github --notify discord      # DM the summary to your Discord bot

Credentials, in order of preference: your existing gh CLI login (zero setup), GITHUB_TOKEN env var, or a saved token (agentize --github prompts on first use — scope repo). Nothing is stored unless you paste a token, and tokens never appear in URLs or git config.

Why

AI coding agents read AGENTS.md to learn a project's commands and conventions — but most generated ones hallucinate. agentize extracts commands from package.json scripts, pyproject.toml, Makefile targets, and CI workflow run: steps, then annotates each with its source so you can audit every line before committing.

AI polish (bring your own key)

agentize itself never calls a model — every command is extracted from real files. But you can optionally polish the prose with your own LLM key (OpenAI-compatible endpoints, key stored locally in ~/.agentize.json):

agentize --llm                        # interactive provider picker
agentize --llm --provider openai      # skip the picker
agentize --llm --provider openrouter --model anthropic/claude-sonnet-4
agentize --llm --provider custom --base-url http://localhost:11434/v1 --model llama3.2

Providers: anthropic, openai, openrouter, gemini, xai, deepseek, groq, mistral, ollama (local, no key), custom. Keys come from the provider's env var (e.g. ANTHROPIC_API_KEY) or a one-time prompt — they never leave your machine except to the provider's own API.

The model writes only an Overview paragraph from the extracted evidence — commands and structure stay 100% evidence-based; the model is forbidden from inventing anything. The interactive menu has it as option 4.

What it extracts

Signal	Source
Install / dev / build / test / lint commands	package.json scripts, pyproject.toml scripts, Makefile targets
What CI actually runs	.github/workflows/*.yml run: steps
Package manager	lockfiles (pnpm-lock.yaml, uv.lock, Cargo.lock, …)
Stack & frameworks	manifest contents (Next.js, React, Django, FastAPI, …)
Test / lint tooling	vitest, jest, pytest, eslint, ruff, biome, …
TypeScript strict mode	tsconfig.json
Required env vars	.env.example keys
Project structure map	top-level dirs with role heuristics
Gotchas & PR rules	CONTRIBUTING.md sections

Testing

python -m unittest discover -s tests

CI: the suite runs on Linux, Windows, and macOS (Python 3.11/3.12/3.13) via GitHub Actions on every push and pull request. A separate job builds the wheel and smoke-tests installing it into a fresh venv.

Publishing

Maintainers ship a release from the repo root with:

uv build
uv publish

The distribution name is agentize-cli; the wheel is dependency-free — agentize uses only the Python standard library, so the published wheel has zero runtime dependencies.

Roadmap

• GitHub mode: connect, pick repos, PR AGENTS.md each (v0.2)
• LLM polish mode: optional synthesis of prose sections from the evidence JSON (never touches commands) (v0.4)
• Nested AGENTS.md for monorepo workspaces (v0.7)
• --check mode for CI (fail if AGENTS.md is stale vs config) (v0.7)
• --watch regeneration on config change