AGENTS.md/CLAUDE.md generator and ExecPlan harness for Codex, Claude Code, Cursor, Antigravity, OpenCode and other coding agents. Use api keys or authenticate with Codex
# Add to your Claude Code skills
git clone https://github.com/trevor-nichols/agentrules-architectYour multi-provider AI code analysis and AGENTS.md generator 🚀
Demo • Highlights • Features • Requirements • Installation • Codex Runtime • CLI • Configuration • Architecture • Outputs • Development

No comments yet. Be the first to share your thoughts!
Version 3 rebrands the project from CursorRules Architect to AgentRules Architect to match the standardized AGENTS.md contract used across modern AI coding agents. The rename comes with a fresh Typer-powered CLI, a persistent configuration service, broader provider support across Anthropic, OpenAI, Google, DeepSeek, xAI, and the local Codex app-server runtime, and a tooling layer that keeps the six-phase analysis reliably consistent yet flexibly extensible to your project's unique needs.
python -m agentrules entry points.agentrules launches an interactive main menu with subcommands for analyze, configure, and keys.~/.config/agentrules/config.toml (override with AGENTRULES_CONFIG_DIR).codex app-server with ChatGPT auth via CODEX_HOME (no AgentRules-stored OpenAI API key required).ToolManager adapts JSON tool schemas for each provider; Tavily web search is available to researcher agents with one toggle.AGENTS.md, SNAPSHOT.md (enabled by default), .cursorignore, optional .agent/ scaffold templates, and per-phase markdown/json snapshots.All CLI entry points ultimately execute the AnalysisPipeline orchestrator (src/agentrules/core/pipeline) that wires the six analysis phases together and streams progress events to the Rich console.
core/analysis/phase_1.py) inventories the repo tree, surfaces tech stack signals, and collects dependency metadata that later phases reuse.core/analysis/phase_2.py) asks the configured model to draft an XML-ish agent plan, then parses it into structured agent definitions (with a safe fallback extractor).core/analysis/phase_3.py) spins up specialized architects per agent definition, hydrates them with file excerpts, and runs them in parallel; if no plan exists it falls back to three default agents.core/analysis/phase_4.py) stitches together Phase 3 findings, elevates cross-cutting insights, and flags follow-up prompts for the final steps.core/analysis/phase_5.py) produces a canonical report object that downstream tooling (rules generator, metrics, exporters) consumes.core/analysis/final_analysis.py) produces the narrative summary that drives AGENTS.md, output toggles, and console highlights.The pipeline captures metrics (elapsed time, agent counts) and hands them to the output writer so offline runs and full analyses share the same persistence path.
codex) for codex app-server integrationsrc/agentrules/config/agents.py.anthropic, openai, google-genai>=1.51.0, tavily-python, tiktoken, rich, typer, questionary, platformdirs, pathspec, python-dotenv, protobuf.pytest, pytest-asyncio, pytest-mock, flask, ruff, pyright.pip install -U agentrules
git clone https://github.com/trevor-nichols/agentrules-architect.git
cd agentrules-architect
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
Need a one-liner? Use the helper script:
./scripts/bootstrap_env.sh # set PYTHON_BIN=/abs/path/to/python to override interpreter
agentrules --version
agentrules analyze /path/to/project
Prefer module execution during development? Invoke the CLI with Python’s module flag—the package ships a __main__ entry point:
python -m agentrules analyze /path/to/project
Need to install directly from GitHub instead of PyPI?
pip install "git+https://github.com/trevor-nichols/agentrules-architect.git#egg=agentrules"
Need to validate against TestPyPI specifically?
pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple agentrules==3.4.1
Run the interactive configurator to store credentials securely:
agentrules configure
~/.config/agentrules/config.toml (override with AGENTRULES_CONFIG_DIR).agentrules configure --provider openai for quick single-key updates.agentrules keys
AgentRules supports Codex as a local runtime provider via codex app-server, separate from API-key providers.
agentrules -> Settings -> Codex runtimecodex by default)CODEX_HOME strategy (managed or inherit)Sign in with ChatGPT to authenticate runtime-backed model access.After runtime setup, choose Codex presets under Settings -> Model presets per phase.
See docs/codex-runtime.md for complete setup, auth flow, model catalog behavior, and live smoke instructions.
agentrules – interactive main menu (analyze, configure models/outputs, check keys).agentrules analyze /path/to/project – full six-phase analysis.agentrules analyze /path/to/project --rules-filename CLAUDE.md – one-run override for output rules filename.agentrules snapshot generate [path] – create (or refresh) SNAPSHOT.md in the current directory by default.agentrules snapshot sync [path] – sync an existing snapshot as project files evolve (also creates if missing).agentrules execplan new \"Title\" – create a new ExecPlan markdown file under .agent/exec_plans/active/<slug>/.agentrules execplan complete EP-YYYYMMDD-NNN [--date YYYYMMDD] – move a full ExecPlan directory under .agent/exec_plans/complete/YYYY/MM/DD/EP-YYYYMMDD-NNN_<slug>/.agentrules execplan list [--path] – list active ExecPlans with compact milestone progress (completed/total).agentrules execplan milestone new EP-YYYYMMDD-NNN \"Title\" [--ms N] – create a milestone under a specific ExecPlan (auto sequence by default, or explicit MS### when provided).agentrules execplan milestone list EP-YYYYMMDD-NNN [--active-only] – list milestones for one ExecPlan.agentrules execplan milestone complete EP-YYYYMMDD-NNN --ms <N> – move an active milestone sequence into the milestones/complete/ directory.agentrules execplan milestone remaining EP-YYYYMMDD-NNN [--path] – show active milestones left for one ExecPlan.agentrules execplan-registry [build|check|update] – manage .agent/exec_plans/registry.json from ExecPlan front matter.agentrules scaffold sync [--check|--force] – sync .agent/PLANS.md and .agent/templates/MILESTONE_TEMPLATE.md with packaged defaults.agentrules configure --models – assign presets per phase with guided prompts; the Ph