Metadata-Version: 2.5
Name: agentize-cli
Version: 0.8.0
Summary: Generate AGENTS.md from a repo's actual config — evidence-based, no guessing.
Project-URL: Homepage, https://github.com/ahm3d-karim/agentize
Project-URL: Repository, https://github.com/ahm3d-karim/agentize
Project-URL: Issues, https://github.com/ahm3d-karim/agentize/issues
Author-email: Ahmad Karim <28020258@lums.edu.pk>
License-Expression: MIT
License-File: LICENSE
Keywords: AGENTS.md,agents,ai,cli,codebase,developer-tools,documentation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# agentize

[![CI](https://img.shields.io/github/actions/workflow/status/ahm3d-karim/agentize/ci.yml?branch=main&label=CI&logo=github)](https://github.com/ahm3d-karim/agentize/actions)
[![License: MIT](https://img.shields.io/github/license/ahm3d-karim/agentize)](https://github.com/ahm3d-karim/agentize/blob/main/LICENSE)

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):**

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

**Option 2 — pip:**

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

**Option 3 — single file, no install at all:**

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

**Option 4 — from source:**

```bash
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

```bash
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:

```bash
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:

```bash
agentize --version   # → agentize 0.8.0
```

## Example output

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

```markdown
# 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:

```bash
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):

```bash
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:

```bash
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:

```bash
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).

```bash
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`):

```bash
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

```bash
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:

```bash
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

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