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

Jayakrishna I — Fri, 02 Oct 2026 02:45:29 +0000

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…

View on GitHub

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. ⭐

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. 🚀

DEV Community: Jayakrishna I