{"slug": "braxis-auto-generate-and-track-ai-agent-readiness-0-100-score-and-history", "title": "Braxis: Auto-generate and track AI agent readiness (0-100 score and history)", "summary": "Braxis launched as a Python tool that generates and keeps four AI agent context files — AGENTS.md, CLAUDE.md, .cursorrules, and .agentic-config.json — in sync with a codebase via the `braxis generate` command, and scores a project's AI agent readiness on a 0-100 scale with tracked history. The tool installs via `pip install braxis`, supports Python, JavaScript, TypeScript, Go, Rust, and Java, ships a GitHub Actions workflow that regenerates files and opens a pull request on every push, and offers optional LLM recommendations through the Claude API with an ANTHROPIC_API_KEY. Braxis reports 30+ unit tests at a 100% pass rate and zero external dependencies for its core features.", "body_md": "**Auto-generate AI agent context files. Keep them in sync with your code.**\n\nYour AI agents (Claude Code, Cursor, Copilot) read from `AGENTS.md` to understand your project. When your code changes, that file gets stale. Agents miss patterns, violate conventions, hallucinate.\n\nBraxis solves this: **one command generates four context files that stay in sync with your codebase.**\n\nBefore Braxis:\n\nDay 1: Agent reads stale AGENTS.md from 2 weeks ago Sees old directory structure Doesn't know about new error handling pattern Makes bad suggestions based on outdated info\n\nAfter Braxis:\n\nEvery push: GitHub Actions runs Braxis Analyzes current codebase Regenerates AGENTS.md, CLAUDE.md, .cursorrules, .agentic-config.json Creates PR with updates Your agents always see current reality\n\n- ✅ **One Command** - Generate all context files with`braxis generate`\n- ✅ **Zero Config** - Works out of the box, no setup needed\n- ✅ **Auto-Score** - Measure your project's AI agent readiness (0-100)\n- ✅ **Score History** - Track improvements over time with trends & analytics\n- ✅ **LLM Recommendations** - AI-powered suggestions using Claude API (optional)\n- ✅ **Multi-Language** - Supports Python, JavaScript, TypeScript, Go, Rust, Java, and more\n- ✅ **CI/CD Ready** - GitHub Actions workflow included\n- ✅ **Pre-commit Hooks** - Validate before every commit\n- ✅ **Safe & Reliable** - Input validation, atomic writes, comprehensive error handling\n- ✅ **Well-Tested** - 30+ unit tests with 100% pass rate\n- ✅ **No Dependencies** - Pure Python, zero external packages (LLM features optional)\n- ✅ **Production-Grade** - Used in real projects, actively maintained\n\n```\n# Basic installation (core features)\npip install braxis\n\n# With LLM support (for AI recommendations)\npip install braxis[llm]\n```\n\nFor LLM-powered recommendations:\n\n```\nexport ANTHROPIC_API_KEY='sk-ant-...'\n```\n\nGet your API key: [https://console.anthropic.com](https://console.anthropic.com)\n\n```\ncd /path/to/your/project\nbraxis generate\n```\n\nThat's it. Braxis creates:\n\nyour-project/ ├── AGENTS.md (Universal agent instructions) ├── CLAUDE.md (Claude Code optimized) ├── .cursorrules (Cursor IDE rules) ├── .agentic-config.json (Machine-readable metadata) └── (your existing files)\n\n```\ncat AGENTS.md\ngit add AGENTS.md CLAUDE.md .cursorrules .agentic-config.json\ngit commit -m \"chore: add AI agent context files\"\ngit push\n```\n\n**In Claude Code:** Automatically reads `CLAUDE.md`\n**In Cursor:** Copy `.cursorrules` into Cursor Settings → Rules\n**In any agent:** Reads `AGENTS.md` (universal format)\n\nAutomatically regenerate context files on every push using GitHub Actions.\n\nBraxis includes a ready-to-use workflow. Copy it to your repo:\n\n```\nmkdir -p .github/workflows\ncp /path/to/braxis/.github/workflows/braxis-score.yml .github/workflows/\ngit add .github/workflows/braxis-score.yml\ngit commit -m \"chore: add braxis auto-update workflow\"\ngit push\n```\n\nOr manually create `.github/workflows/braxis-score.yml`:\n\n```\nname: Braxis Score Check\n\non:\n  push:\n    branches: [ main, develop ]\n    paths:\n      - '**.py'\n      - 'package.json'\n      - 'pyproject.toml'\n      - 'setup.py'\n\njobs:\n  score:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-python@v4\n        with:\n          python-version: '3.11'\n      - run: pip install braxis\n      - run: braxis score\n      - run: braxis generate\n      - name: Create Pull Request for updates\n        uses: peter-evans/create-pull-request@v5\n        with:\n          commit-message: 'chore: regenerate braxis context files'\n          title: 'chore: update agent context files'\n          branch: braxis/auto-update\n```\n\n**Result:** Every push automatically regenerates context files and creates a PR if needed. ✨\n\nValidate context files before every commit using pre-commit.\n\n```\npip install pre-commit\npre-commit install\n```\n\nThe hooks will run automatically on `git commit`.\n\nCopy the example config to your project:\n\n```\ncp /path/to/braxis/.pre-commit-config.example.yaml .pre-commit-config.yaml\n```\n\nThen install:\n\n```\npip install pre-commit\npre-commit install\n```\n\nNow braxis will validate your project before each commit! 🔐\n\nTrack your project's AI agent readiness score over time.\n\n```\n# View all historical scores\nbraxis history\n\n# View scores with trends and direction indicators\nbraxis history --trends\n```\n\n**Example output:**\n\n```\n============================================================\nScore History for myproject\n============================================================\n\n1. 2026-10-01 - 65/100 (AI-Native)\n2. 2026-10-05 - 72/100 (AI-Native)\n3. 2026-10-10 - 78/100 (AI-Native-Plus)\n\nTrend: 📈 +13 points\n\n============================================================\n```\n\n**Features:**\n\n- Automatic score persistence on every `braxis score` run\n- Project-specific tracking (stored in `~/.braxis/history/` )\n- Trend indicators: 📈 (improving) 📉 (declining) ➡️ (stable)\n- Configurable history limits\n- Timestamps and tier information included\n\nGet intelligent, actionable recommendations from Claude AI.\n\n**Setup:**\n\n```\n# Install with LLM support\npip install braxis[llm]\n\n# Set your API key\nexport ANTHROPIC_API_KEY='sk-ant-...'\n```\n\n**Usage:**\n\n```\nbraxis recommendations\n```\n\n**Example output:**\n\n```\n============================================================\nLLM-Powered Recommendations for myproject\n============================================================\n\n1. Add Comprehensive Test Suite\n   Why it matters: Testing is the foundation of reliable code.\n   Current state: Only 7% testing coverage\n   How to implement:\n   - Start with pytest fixtures for common patterns\n   - Aim for 80%+ coverage on core modules\n   - Run: pytest --cov to measure progress\n\n2. Implement Input Validation Framework\n   Why it matters: Validation prevents bugs and security issues\n   Current state: No systematic validation detected\n   How to implement:\n   - Use Pydantic for request validation\n   - Add schema validation to all API endpoints\n   - Example: from pydantic import BaseModel\n\n[... more recommendations ...]\n```\n\n**Features:**\n\n- Uses Claude Opus 5.5 for high-quality analysis\n- 5-7 actionable recommendations per run\n- Concrete implementation steps for each suggestion\n- Focuses on improving Agent Readiness Score\n- Gracefully handles missing API keys\n- Optional dependency (braxis works without it)\n\nBraxis welcomes contributions! Read [CONTRIBUTING.md](https://github.com/jaykrishna316/braxis/blob/main/CONTRIBUTING.md) for:\n\n- Setup instructions\n- Development workflow\n- Testing guidelines\n- Code style guide\n- PR process\n\n**Quick start:**\n\n```\ngit clone https://github.com/YOUR_USERNAME/braxis.git\ncd braxis\npython3 -m venv venv\nsource venv/bin/activate\npip install -e .\npython3 -m unittest test_braxis -v\n```\n\nCreate `.agentic-config.json`:\n\n```\n{\n  \"name\": \"MyApp\",\n  \"description\": \"A production API service\",\n  \"exclude_patterns\": [\n    \"node_modules/**\",\n    \".venv/**\",\n    \"build/**\"\n  ],\n  \"custom_conventions\": {\n    \"error_handling\": \"Always use try/except and log\",\n    \"async_patterns\": \"All I/O must be async\",\n    \"validation\": \"Use Pydantic models for inputs\"\n  },\n  \"critical_files\": [\n    \"src/main.py\",\n    \"src/api/routes.py\",\n    \"README.md\"\n  ]\n}\n```\n\n**AGENTS.md** - Universal format read by any AI agent\n\n**CLAUDE.md** - Optimized for Claude Code\n\n**.cursorrules** - Rules for Cursor IDE\n\n**.agentic-config.json** - Machine-readable metadata\n\nCheck how ready your codebase is for AI agents:\n\n```\nbraxis score\n```\n\n**Example output:**\n\n```\n============================================================\nAgent Readiness Score: 71/100\n============================================================\n\nBreakdown:\n\n Architecture          10/100 [██░░░░░░░░░░░░░░░░░░]\n Testing                7/100 [█░░░░░░░░░░░░░░░░░░]\n Dependencies          12/100 [██░░░░░░░░░░░░░░░░░]\n Conventions           10/100 [██░░░░░░░░░░░░░░░░░░]\n Entry Points           4/100 [░░░░░░░░░░░░░░░░░░░]\n Security              10/100 [██░░░░░░░░░░░░░░░░░░]\n Build                 10/100 [██░░░░░░░░░░░░░░░░░░]\n Documentation          8/100 [█░░░░░░░░░░░░░░░░░░]\n\nTier: AI-Native\n\nDetected:\n Languages: python\n Build System: Python (pip/setuptools)\n Test Frameworks: pytest, unittest\n Test Files: 1\n Critical Files: 0\n\nRecommendations:\n * Increase test coverage\n * Add input validation and security checks\n```\n\n| Score | Tier | Meaning | \n|---|---|---|\n| 90-100 | **Agent-Optimized** | Production-ready for AI agents | \n| 80-89 | **AI-Native-Plus** | Excellent agent compatibility | \n| 60-79 | **AI-Native** | Good agent support | \n| 30-59 | **Agent-Aware** | Basic agent compatibility | \n| 0-29 | **Not Ready** | Needs improvements | \n\n- **Architecture** - Critical files, entry points, project structure\n- **Testing** - Test coverage and test framework detection\n- **Dependencies** - Build system and dependency management\n- **Conventions** - Code patterns, error handling, type hints\n- **Entry Points** - Main functions and executable files\n- **Security** - Input validation, security checks, config management\n- **Build** - Build files and dependency tracking\n- **Documentation** - README and project documentation\n\n```\npython3 braxis.py score --path /path/to/project\n# Check version\nbraxis --version\n\n# Score your project's agent readiness\nbraxis score\nbraxis score --path /path/to/project  # Score a specific project\n\n# Generate context files\nbraxis generate\nbraxis generate --path /path/to/project\n\n# Inspect project analysis\nbraxis inspect\nbraxis inspect --path /path/to/project\n\n# Validate context files exist\nbraxis validate\nbraxis validate --path /path/to/project\n\n# View score history\nbraxis history\nbraxis history --path /path/to/project\nbraxis history --trends                 # Show trends with emoji indicators\nbraxis history --path /path/to/project --trends\n\n# Get LLM-powered recommendations (requires: export ANTHROPIC_API_KEY='sk-ant-...')\nbraxis recommendations\nbraxis recommendations --path /path/to/project\n```\n\nBraxis is production-grade with enterprise-level quality standards:\n\n- **Input Validation** - Validates project paths and file inputs with clear error messages\n- **Atomic File Writing** - Uses temporary files and atomic operations to prevent partial writes\n- **Error Handling** - Comprehensive error handling with informative feedback\n- **Path Normalization** - Converts relative paths to absolute paths safely\n\n- **Comprehensive Tests** - 30+ unit tests covering all major functionality\n- **Test Coverage** - 100% pass rate across all test suites\n- **Automated Testing** - GitHub Actions runs tests on every commit\n- **Pre-commit Hooks** - Validates before every commit\n- **Code Style** - Follows PEP 8 standards\n- **Zero Dependencies** - No external packages required\n\n```\n# Run all tests\npython3 -m unittest test_braxis -v\n\n# Run specific test class\npython3 -m unittest test_braxis.TestValidateProjectPath -v\n\n# Check test coverage\npip install coverage\ncoverage run -m unittest test_braxis\ncoverage report\n```\n\n**Status:** All 30 tests passing ✅\n\n| Feature | Braxis | CursorRules | .cursorrules | Other Tools | \n|---|---|---|---|---|\n| **Auto-generates context** | ✅ Four formats | ❌ Manual | ❌ Manual | Varies | \n| **Scores readiness** | ✅ 0-100 with 5 tiers | ❌ No | ❌ No | ❌ Limited | \n| **Tracks history** | ✅ Over time with trends | ❌ No | ❌ No | ❌ No | \n| **AI recommendations** | ✅ Claude-powered | ❌ No | ❌ No | ❌ Limited | \n| **Multi-language** | ✅ 15+ languages | ❌ Limited | ❌ Limited | Varies | \n| **CI/CD integration** | ✅ GitHub Actions ready |  |  | Varies | \n| **Zero dependencies** | ✅ Core only | ✅ Yes | ✅ Yes | Varies | \n| **Production-tested** | ✅ 30+ tests |  |  | Varies | \n| **Atomic file ops** | ✅ Safe writes | ❌ No | ❌ No | ❌ No | \n| **Active updates** | ✅ Latest Claude models |  |  | Varies | \n\n**The difference:** Braxis goes beyond rules files. It continuously analyzes your codebase, scores your readiness, tracks progress, and provides AI-driven guidance—all automatically.\n\n- Python 3.8+\n- Zero external dependencies\n- Works on macOS, Linux, Windows\n\n- **Report Issues** -[GitHub Issues](https://github.com/jaykrishna316/braxis/issues)\n- **Discussions** -[GitHub Discussions](https://github.com/jaykrishna316/braxis/discussions)\n- **Contributing** - See[CONTRIBUTING.md](https://github.com/jaykrishna316/braxis/blob/main/CONTRIBUTING.md)\n\n``` bash\n# New developer clones repo\n$ braxis score\nAgent Readiness: 78/100 (AI-Native-Plus)\n\n# They immediately understand the project structure, conventions, and quality baseline\n# Opens AGENTS.md in Claude Code - instant context\nbash\n# Initial state\n$ braxis score\nScore: 45/100 (Agent-Aware)\n\n# After 2 weeks of improvements\n$ braxis history --trends\n📈 +28 points\n\n# Team celebrates progress with visual trend data\nbash\n# Every commit triggers workflow\n$ braxis score\n$ braxis generate\n# PR created with updated context files\n# Agents always have latest project info\nbash\n$ braxis recommendations\n# Get AI-powered guidance on what to improve\n# Prioritize high-impact changes\n# Measure progress with `braxis history`\n```\n\nAI agents need current context to work effectively. Without it, they:\n\n- ❌ Miss recent code patterns\n- ❌ Violate project conventions\n- ❌ Make outdated suggestions\n- ❌ Waste your time with hallucinations\n\nBraxis solves this automatically:\n\n1. **Generates** context files from real code analysis\n2. **Scores** your readiness for AI agents (0-100)\n3. **Tracks** improvements over time with trends\n4. **Recommends** actionable next steps via Claude AI\n\nOne command. Always in sync. Always improving. ✨\n\nMIT - Free to use in personal and commercial projects\n\nSee [LICENSE](https://github.com/jaykrishna316/braxis/blob/main/LICENSE) for details.\n\nUpcoming features in development:\n\n- 🚧 Custom scoring rules engine\n- 🚧 Project comparison & benchmarking\n- 🚧 Web dashboard for visualization\n- 🚧 Score forecasting & predictions\n- 🚧 Integration with more IDE platforms\n\nHave a feature request? [Open an issue](https://github.com/jaykrishna316/braxis/issues/new)\n\n**Braxis** — Keep your agents aligned. Keep your code context current.\n\nContinuously analyze. Automatically improve. Always sync. ✨\n\nMade with ❤️ for AI-native development by developers, for developers.", "url": "https://wpnews.pro/news/braxis-auto-generate-and-track-ai-agent-readiness-0-100-score-and-history", "canonical_source": "https://github.com/jaykrishna316/braxis", "published_at": "2026-10-02 02:15:56+00:00", "updated_at": "2026-10-02 02:45:43.908291+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "agent-protocols"], "entities": ["Braxis", ".cursorrules", "Claude Code", "Cursor", "GitHub Actions"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/braxis-auto-generate-and-track-ai-agent-readiness-0-100-score-and-history", "markdown": "https://wpnews.pro/news/braxis-auto-generate-and-track-ai-agent-readiness-0-100-score-and-history.md", "text": "https://wpnews.pro/news/braxis-auto-generate-and-track-ai-agent-readiness-0-100-score-and-history.txt", "jsonld": "https://wpnews.pro/news/braxis-auto-generate-and-track-ai-agent-readiness-0-100-score-and-history.jsonld"}}