jaykrishna316/braxis
The axis of agent knowledge. Auto-generates and keeps in sync AGENTS.md, CLAUDE.md, .cursorrules — context files that AI agents read. - jaykrishna316/braxis
0 stars · 0 forks
README
Braxis
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.
See It In Action 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
✨ Key Features
✅ 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
How To Use Braxis On Your Project (5 minutes) Step 1: Install
Basic installation (core features)
pip install braxisWith LLM support (for AI recommendations)
pip install braxis[llm] Step 2: (Optional) Set Up Claude API For LLM-powered recommendations: export ANTHROPIC_API_KEY='sk-ant-...' Get your API key: https://console.anthropic.com Step 3: Go to Your Project cd /path/to/your/project Step 3: Generate Context Files 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) Step 4: See What It Generated cat AGENTS.md Step 5: Commit to Your Repo git add AGENTS.md CLAUDE.md .cursorrules .agentic-config.json git commit -m "chore: add AI agent context files" git push Step 6: Your Agents Now Use These Files In Claude Code: Automatically reads CLAUDE.md In Cursor: Copy .cursorrules into Cursor Settings → Rules In any agent: Reads AGENTS.md (universal format)🚀 Extended Features Auto-Update with GitHub Actions 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. ✨ Pre-commit Hooks Validate context files before every commit using pre-commit. For Contributors to Braxis: pip install pre-commit pre-commit install The hooks will run automatically on git commit. For Your Projects Using Braxis: 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! 🔐 Score History & Trends Track your project's AI agent readiness score over time.
View all historical scores
braxis historyView 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
LLM-Powered Recommendations 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)
📚 Contributing Braxis welcomes contributions! Read 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
Customize For Your Project (Optional) 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" ] }
What Each File Does 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
Score Your Project See Your Agent Readiness Score 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
Understanding Your Score
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
Score Categories Explained
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
Test a Specific Project python3 braxis.py score --path /path/to/project
All Commands
Check version
braxis --versionScore your project's agent readiness
braxis score braxis score --path /path/to/project # Score a specific projectGenerate context files
braxis generate braxis generate --path /path/to/projectInspect project analysis
braxis inspect braxis inspect --path /path/to/projectValidate context files exist
braxis validate braxis validate --path /path/to/projectView score history
braxis history braxis history --path /path/to/project braxis history --trends # Show trends with emoji indicators braxis history --path /path/to/project --trendsGet LLM-powered recommendations (requires: export ANTHROPIC_API_KEY='sk-ant-...')
braxis recommendations braxis recommendations --path /path/to/projectQuality & Reliability Braxis is production-grade with enterprise-level quality standards: Safety Features
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
Testing & Quality
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 Tests Locally
Run all tests
python3 -m unittest test_braxis -vRun specific test class
python3 -m unittest test_braxis.TestValidateProjectPath -vCheck test coverage
pip install coverage coverage run -m unittest test_braxis coverage report Status: All 30 tests passing ✅Why Braxis Stands Out
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 ⚠️ Manual ⚠️ Manual Varies
Zero dependencies ✅ Core only ✅ Yes ✅ Yes Varies
Production-tested ✅ 30+ tests ⚠️ Limited ⚠️ Limited Varies
Atomic file ops ✅ Safe writes ❌ No ❌ No ❌ No
Active updates ✅ Latest Claude models ⚠️ Varies ⚠️ Varies 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.
Requirements
Python 3.8+ Zero external dependencies Works on macOS, Linux, Windows
Getting Help
Report Issues - GitHub Issues Discussions - GitHub Discussions Contributing - See CONTRIBUTING.md
Real-World Usage Examples Scenario 1: Onboarding New Team Members
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
Scenario 2: Tracking Quality ImprovementsInitial state
$ braxis score Score: 45/100 (Agent-Aware)After 2 weeks of improvements
$ braxis history --trends 📈 +28 pointsTeam celebrates progress with visual trend data
Scenario 3: CI/CD Automated UpdatesEvery commit triggers workflow
$ braxis score $ braxis generatePR created with updated context files
Agents always have latest project info
Scenario 4: Before Starting Major Refactor $ braxis recommendationsGet AI-powered guidance on what to improve
Prioritize high-impact changes
Measure progress with `braxis history`
Why Braxis? 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:
Generates context files from real code analysis Scores your readiness for AI agents (0-100) Tracks improvements over time with trends Recommends actionable next steps via Claude AI
One command. Always in sync. Always improving. ✨
License MIT - Free to use in personal and commercial projects See LICENSE for details.
Roadmap 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
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.