Braxis: Auto-generate and track AI agent readiness (0-100 score and history)

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.

Auto-generate AI agent context files. Keep them in sync with your code. Your 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. Braxis solves this: one command generates four context files that stay in sync with your codebase. Before Braxis: Day 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 After Braxis: Every 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 - ✅ One Command - Generate all context files with braxis generate - ✅ Zero Config - Works out of the box, no setup needed - ✅ Auto-Score - Measure your project's AI agent readiness 0-100 - ✅ Score History - Track improvements over time with trends & analytics - ✅ LLM Recommendations - AI-powered suggestions using Claude API optional - ✅ Multi-Language - Supports Python, JavaScript, TypeScript, Go, Rust, Java, and more - ✅ CI/CD Ready - GitHub Actions workflow included - ✅ Pre-commit Hooks - Validate before every commit - ✅ Safe & Reliable - Input validation, atomic writes, comprehensive error handling - ✅ Well-Tested - 30+ unit tests with 100% pass rate - ✅ No Dependencies - Pure Python, zero external packages LLM features optional - ✅ Production-Grade - Used in real projects, actively maintained Basic installation core features pip install braxis With LLM support for AI recommendations pip install braxis llm For LLM-powered recommendations: export ANTHROPIC API KEY='sk-ant-...' Get your API key: https://console.anthropic.com https://console.anthropic.com cd /path/to/your/project braxis generate That's it. Braxis creates: your-project/ ├── AGENTS.md Universal agent instructions ├── CLAUDE.md Claude Code optimized ├── .cursorrules Cursor IDE rules ├── .agentic-config.json Machine-readable metadata └── your existing files cat AGENTS.md git add AGENTS.md CLAUDE.md .cursorrules .agentic-config.json git commit -m "chore: add AI agent context files" git push In Claude Code: Automatically reads CLAUDE.md In Cursor: Copy .cursorrules into Cursor Settings → Rules In any agent: Reads AGENTS.md universal format Automatically regenerate context files on every push using GitHub Actions. Braxis includes a ready-to-use workflow. Copy it to your repo: mkdir -p .github/workflows cp /path/to/braxis/.github/workflows/braxis-score.yml .github/workflows/ git add .github/workflows/braxis-score.yml git commit -m "chore: add braxis auto-update workflow" git push Or manually create .github/workflows/braxis-score.yml : name: Braxis Score Check on: push: branches: main, develop paths: - ' .py' - 'package.json' - 'pyproject.toml' - 'setup.py' jobs: score: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v4 with: python-version: '3.11' - run: pip install braxis - run: braxis score - run: braxis generate - name: Create Pull Request for updates uses: peter-evans/create-pull-request@v5 with: commit-message: 'chore: regenerate braxis context files' title: 'chore: update agent context files' branch: braxis/auto-update Result: Every push automatically regenerates context files and creates a PR if needed. ✨ Validate context files before every commit using pre-commit. pip install pre-commit pre-commit install The hooks will run automatically on git commit . Copy the example config to your project: cp /path/to/braxis/.pre-commit-config.example.yaml .pre-commit-config.yaml Then install: pip install pre-commit pre-commit install Now braxis will validate your project before each commit 🔐 Track your project's AI agent readiness score over time. View all historical scores braxis history View scores with trends and direction indicators braxis history --trends Example output: ============================================================ Score History for myproject ============================================================ 1. 2026-10-01 - 65/100 AI-Native 2. 2026-10-05 - 72/100 AI-Native 3. 2026-10-10 - 78/100 AI-Native-Plus Trend: 📈 +13 points ============================================================ Features: - Automatic score persistence on every braxis score run - Project-specific tracking stored in ~/.braxis/history/ - Trend indicators: 📈 improving 📉 declining ➡️ stable - Configurable history limits - Timestamps and tier information included Get intelligent, actionable recommendations from Claude AI. Setup: Install with LLM support pip install braxis llm Set your API key export ANTHROPIC API KEY='sk-ant-...' Usage: braxis recommendations Example output: ============================================================ LLM-Powered Recommendations for myproject ============================================================ 1. Add Comprehensive Test Suite Why it matters: Testing is the foundation of reliable code. Current state: Only 7% testing coverage How to implement: - Start with pytest fixtures for common patterns - Aim for 80%+ coverage on core modules - Run: pytest --cov to measure progress 2. Implement Input Validation Framework Why it matters: Validation prevents bugs and security issues Current state: No systematic validation detected How to implement: - Use Pydantic for request validation - Add schema validation to all API endpoints - Example: from pydantic import BaseModel ... more recommendations ... Features: - Uses Claude Opus 5.5 for high-quality analysis - 5-7 actionable recommendations per run - Concrete implementation steps for each suggestion - Focuses on improving Agent Readiness Score - Gracefully handles missing API keys - Optional dependency braxis works without it Braxis welcomes contributions Read CONTRIBUTING.md https://github.com/jaykrishna316/braxis/blob/main/CONTRIBUTING.md for: - Setup instructions - Development workflow - Testing guidelines - Code style guide - PR process Quick start: git clone https://github.com/YOUR USERNAME/braxis.git cd braxis python3 -m venv venv source venv/bin/activate pip install -e . python3 -m unittest test braxis -v Create .agentic-config.json : { "name": "MyApp", "description": "A production API service", "exclude patterns": "node modules/ ", ".venv/ ", "build/ " , "custom conventions": { "error handling": "Always use try/except and log", "async patterns": "All I/O must be async", "validation": "Use Pydantic models for inputs" }, "critical files": "src/main.py", "src/api/routes.py", "README.md" } AGENTS.md - Universal format read by any AI agent CLAUDE.md - Optimized for Claude Code .cursorrules - Rules for Cursor IDE .agentic-config.json - Machine-readable metadata Check how ready your codebase is for AI agents: braxis score Example output: ============================================================ Agent Readiness Score: 71/100 ============================================================ Breakdown: Architecture 10/100 ██░░░░░░░░░░░░░░░░░░ Testing 7/100 █░░░░░░░░░░░░░░░░░░ Dependencies 12/100 ██░░░░░░░░░░░░░░░░░ Conventions 10/100 ██░░░░░░░░░░░░░░░░░░ Entry Points 4/100 ░░░░░░░░░░░░░░░░░░░ Security 10/100 ██░░░░░░░░░░░░░░░░░░ Build 10/100 ██░░░░░░░░░░░░░░░░░░ Documentation 8/100 █░░░░░░░░░░░░░░░░░░ Tier: AI-Native Detected: Languages: python Build System: Python pip/setuptools Test Frameworks: pytest, unittest Test Files: 1 Critical Files: 0 Recommendations: Increase test coverage Add input validation and security checks | Score | Tier | Meaning | |---|---|---| | 90-100 | Agent-Optimized | Production-ready for AI agents | | 80-89 | AI-Native-Plus | Excellent agent compatibility | | 60-79 | AI-Native | Good agent support | | 30-59 | Agent-Aware | Basic agent compatibility | | 0-29 | Not Ready | Needs improvements | - Architecture - Critical files, entry points, project structure - Testing - Test coverage and test framework detection - Dependencies - Build system and dependency management - Conventions - Code patterns, error handling, type hints - Entry Points - Main functions and executable files - Security - Input validation, security checks, config management - Build - Build files and dependency tracking - Documentation - README and project documentation python3 braxis.py score --path /path/to/project Check version braxis --version Score your project's agent readiness braxis score braxis score --path /path/to/project Score a specific project Generate context files braxis generate braxis generate --path /path/to/project Inspect project analysis braxis inspect braxis inspect --path /path/to/project Validate context files exist braxis validate braxis validate --path /path/to/project View score history braxis history braxis history --path /path/to/project braxis history --trends Show trends with emoji indicators braxis history --path /path/to/project --trends Get LLM-powered recommendations requires: export ANTHROPIC API KEY='sk-ant-...' braxis recommendations braxis recommendations --path /path/to/project Braxis is production-grade with enterprise-level quality standards: - Input Validation - Validates project paths and file inputs with clear error messages - Atomic File Writing - Uses temporary files and atomic operations to prevent partial writes - Error Handling - Comprehensive error handling with informative feedback - Path Normalization - Converts relative paths to absolute paths safely - Comprehensive Tests - 30+ unit tests covering all major functionality - Test Coverage - 100% pass rate across all test suites - Automated Testing - GitHub Actions runs tests on every commit - Pre-commit Hooks - Validates before every commit - Code Style - Follows PEP 8 standards - Zero Dependencies - No external packages required Run all tests python3 -m unittest test braxis -v Run specific test class python3 -m unittest test braxis.TestValidateProjectPath -v Check test coverage pip install coverage coverage run -m unittest test braxis coverage report Status: All 30 tests passing ✅ | Feature | Braxis | CursorRules | .cursorrules | Other Tools | |---|---|---|---|---| | Auto-generates context | ✅ Four formats | ❌ Manual | ❌ Manual | Varies | | Scores readiness | ✅ 0-100 with 5 tiers | ❌ No | ❌ No | ❌ Limited | | Tracks history | ✅ Over time with trends | ❌ No | ❌ No | ❌ No | | AI recommendations | ✅ Claude-powered | ❌ No | ❌ No | ❌ Limited | | Multi-language | ✅ 15+ languages | ❌ Limited | ❌ Limited | Varies | | CI/CD integration | ✅ GitHub Actions ready | | | Varies | | Zero dependencies | ✅ Core only | ✅ Yes | ✅ Yes | Varies | | Production-tested | ✅ 30+ tests | | | Varies | | Atomic file ops | ✅ Safe writes | ❌ No | ❌ No | ❌ No | | Active updates | ✅ Latest Claude models | | | Varies | The difference: Braxis goes beyond rules files. It continuously analyzes your codebase, scores your readiness, tracks progress, and provides AI-driven guidance—all automatically. - Python 3.8+ - Zero external dependencies - Works on macOS, Linux, Windows - Report Issues - GitHub Issues https://github.com/jaykrishna316/braxis/issues - Discussions - GitHub Discussions https://github.com/jaykrishna316/braxis/discussions - Contributing - See CONTRIBUTING.md https://github.com/jaykrishna316/braxis/blob/main/CONTRIBUTING.md bash New developer clones repo $ braxis score Agent Readiness: 78/100 AI-Native-Plus They immediately understand the project structure, conventions, and quality baseline Opens AGENTS.md in Claude Code - instant context bash Initial state $ braxis score Score: 45/100 Agent-Aware After 2 weeks of improvements $ braxis history --trends 📈 +28 points Team celebrates progress with visual trend data bash Every commit triggers workflow $ braxis score $ braxis generate PR created with updated context files Agents always have latest project info bash $ braxis recommendations Get AI-powered guidance on what to improve Prioritize high-impact changes Measure progress with braxis history AI agents need current context to work effectively. Without it, they: - ❌ Miss recent code patterns - ❌ Violate project conventions - ❌ Make outdated suggestions - ❌ Waste your time with hallucinations Braxis solves this automatically: 1. Generates context files from real code analysis 2. Scores your readiness for AI agents 0-100 3. Tracks improvements over time with trends 4. Recommends actionable next steps via Claude AI One command. Always in sync. Always improving. ✨ MIT - Free to use in personal and commercial projects See LICENSE https://github.com/jaykrishna316/braxis/blob/main/LICENSE for details. Upcoming features in development: - 🚧 Custom scoring rules engine - 🚧 Project comparison & benchmarking - 🚧 Web dashboard for visualization - 🚧 Score forecasting & predictions - 🚧 Integration with more IDE platforms Have a feature request? Open an issue https://github.com/jaykrishna316/braxis/issues/new Braxis — Keep your agents aligned. Keep your code context current. Continuously analyze. Automatically improve. Always sync. ✨ Made with ❤️ for AI-native development by developers, for developers.