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

> Source: <https://github.com/jaykrishna316/braxis>
> Published: 2026-10-02 02:15:56+00:00

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