Braxis: Keep Your AI Agents in Sync with Your Code (Automatically)

Stop correcting AI hallucinations caused by stale context files... jaykrishna316 / braxis The axis of agent knowledge. Auto-generates and keeps in sync AGENTS.md, CLAUDE.md, .cursorrules - context files that AI agents read. 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… The Problem Nobody Talks About You're using Claude Code, Cursor, or Copilot. They're incredible. But here's what happens in practice: Day 1: You create AGENTS.md with your project conventions, directory structure, error handling patterns. Day 2-14: You refactor. Add new error handling. Update conventions. Restructure directories. Your code evolves. Day 15: Your AI agent reads the 2-week-old AGENTS.md and has no idea about any of these changes. Result: ❌ Agent misses new patterns ❌ Agent violates conventions it doesn't know about ❌ Agent makes suggestions that break your current architecture ❌ You waste time correcting hallucinations The fundamental problem: Your AI agents are working with stale documentation. The Aha Moment I realized the solution wasn't just "auto-generate context files." Plenty of tools do that (sort of). The real insight was: If AI agents are your primary interface, you need to measure your codebase readiness for them. ** So I built three things:** 1. Automatic Context File Generation braxis generate Generates four formats simultaneously: AGENTS.md - Universal format any AI can read CLAUDE.md - Optimized for Claude Code .cursorrules - Cursor IDE format .agentic-config.json - Machine-readable metadata One command. Takes 10 seconds. Your agents always have current info. 2. AI Readiness Scoring (0-100) braxis score Analyzes 8 dimensions of your codebase: Architecture 65/100 [████░░░░░░░░░░░░░░░] Testing 45/100 [███░░░░░░░░░░░░░░░░] Dependencies 72/100 [██████░░░░░░░░░░░░░] Conventions 58/100 [█████░░░░░░░░░░░░░░] Entry Points 52/100 [████░░░░░░░░░░░░░░░] Security 68/100 [██████░░░░░░░░░░░░░] Build 71/100 [██████░░░░░░░░░░░░░] Documentation 48/100 [███░░░░░░░░░░░░░░░░] ───────────────────────────── Overall Score: 71/100 (AI-Native) This tells you exactly how AI-friendly your codebase is and where to improve. 3. Track Progress Over Time braxis history --trends Output: Score History for myproject ════════════════════════════════════════ - 2026-10-01 - 65/100 (AI-Native) - 2026-10-15 - 71/100 (AI-Native) - 2026-10-30 - 79/100 (AI-Native-Plus) Trend: 📈 +14 points ════════════════════════════════════════ Every run automatically persists your score. Over time, you see which refactorings actually moved the needle. Teams use this to track quarterly progress. Bonus: Claude-Powered Recommendations export ANTHROPIC_API_KEY='sk-ant-...' braxis recommendations Claude Opus 5.5 analyzes your specific project and generates 5-7 concrete suggestions: - Add Input Validation Framework Why: 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 - Implement Retry Logic Standardization Why: Your retry patterns are inconsistent Locations: - services/api.py:45 (exponential backoff) - services/db.py:128 (fixed retry) Current State: No standard pattern How to implement: - Create a shared retry decorator - Apply consistently across codebase - Example: @retry(max_attempts=3, backoff=exponential) [... 5 more specific, actionable recommendations ...] Each suggestion is grounded in your actual code, not generic tips. How It Works (Technically) - Zero Dependencies (Core) - pip install braxis - # Pure Python, zero external packages - Optional LLM Support - pip install braxis[llm] - export ANTHROPIC_API_KEY='sk-ant-...' - braxis recommendations - # Now you have Claude-powered analysis - Atomic File Writes - Uses temporary files + atomic rename to prevent corruption under concurrent CI/CD runs. Your context files are never partially written. MD5-Based Project Hashing Project-specific hashing stores scores in ~/.braxis/history/scores_{hash}.json. Supports tracking multiple codebases simultaneously without collisions. Production-Grade Quality - 30+ unit tests (100% passing) - Input validation + path normalization - Comprehensive error handling - 15+ language detection - GitHub Actions workflow included Real-World Workflow Day 1: Initial Setup # Install pip install braxis Generate context files braxis generate Check your readiness score braxis score Commit everything git add AGENTS.md CLAUDE.md .cursorrules .agentic-config.json git commit -m "chore: add AI agent context files" git push ** Every Commit After: Automatic Updates** Add .github/workflows/braxis-score.yml: name: Braxis Auto-Update on: push: branches: [ main ] paths: - '**.py' - 'package.json' - 'pyproject.toml' jobs: update: 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 generate - name: Create PR if changed 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. Your agents always see current reality. Why This Matters (For Your Career) If you're using AI agents heavily: - Your agents are only as good as their context - Stale context = hallucinations = wasted time - Braxis fixes this automatically - Your team works 20-30% faster with accurate agent context If you're measuring code quality: - Most metrics (coverage, complexity, lines of code) miss AI-readiness - The readiness score tells you how well AI agents can work in your project - Track it quarterly to see real improvement - Show leadership concrete progress If you're optimizing your codebase: - Most refactoring advice is generic ("add tests," "improve documentation") - Braxis gives you specific, prioritized recommendations for your project - Spend time on high-impact changes only The Numbers - 📊 622-line README with comprehensive docs - 🧪 30+ unit tests (100% pass rate) - 🌍 15+ languages detected (Python, JS, TS, Go, Rust, Java, C#, PHP, Ruby, Kotlin, Scala, Swift, Elixir, Clojure, Shell) - 📈 5 readiness tiers (Not Ready → Agent-Optimized) - 🎯 8 scoring categories analyzed - ⚡ Zero production dependencies - 🔄 GitHub Actions workflow included - 📅 MIT licensed - Free to use, commercial-friendly Get Started (5 Minutes) 1. Install pip install braxis 2. Run it cd /path/to/your/project braxis generate 3. See your score braxis score 4. Commit the files git add AGENTS.md CLAUDE.md .cursorrules .agentic-config.json git commit -m "chore: add AI agent context files" git push 5. Set up auto-updates (optional) Copy .github/workflows/braxis-score.yml to your repo That's it. Your agents now have fresh, accurate context. Want AI Recommendations? Install with LLM support pip install braxis[llm] Set your API key export ANTHROPIC_API_KEY='sk-ant-...' Get your key: https://console.anthropic.com Get Claude's analysis braxis recommendations Claude Opus 5.5 will analyze your project and suggest the 5-7 highest-impact improvements with concrete implementation steps. What Sets It Apart Most tools generate one static file once. Braxis: Feature ** Braxis ** Other Tools Auto-generates context 4 formats 1 format (usually) Scores readiness 0-100 with trends ❌ No Tracks history Yes, automatically. ❌ No AI recommendations Claude-powered ❌ Limited Multi-language 15+ languages Limited CI/CD integration GitHub Actions ready Manual Zero dependencies Core only Often 5+ Production-tested 30+ unit tests Varies Open Source & MIT Licensed Everything is on GitHub. No corporate lock-in. No proprietary models. Just pure Python doing what it does best. GitHub: https://github.com/jaykrishna316/braxis PyPI: https://pypi.org/project/braxis/ README with examples: https://github.com/jaykrishna316/braxis/blob/main/README.md Questions? What's your biggest frustration with AI agents in your workflow? Drop a comment below-I'd love to hear what breaks or surprises you when you run braxis score on your own project. Give it a star on GitHub if this solves a problem for you. ⭐ Tags Python #OpenSource #AI #AIDeveloperTools #DevTools #CursorAI #ClaudeCode #Automation #CI/CD #DeveloperProductivity Keep your agents aligned. Keep your code context current. One command. Always in sync. 🚀 Top comments (0)