ai-brief

🤖 Brief

Brief your AI coding assistants once, update them all.

---

The Problem

You're using Claude Projects, GitHub Copilot, and Cursor. You want them all to follow your project's conventions:

• ✅ Run tests before committing
• ✅ Update docs after code changes
• ✅ Follow your team's architectural patterns

But maintaining 3+ instruction files manually is tedious and error-prone.

The Solution

pip install ai-brief

# One command updates all your AI assistants
brief update "Run pytest before committing any code"

# ✅ .github/copilot-instructions.md updated
# ✅ CLAUDE.md updated
# ✅ AGENTS.md updated
# ✅ .cursorrules updated

---

Installation

# CLI only (recommended for most users)
pip install ai-brief

# CLI + MCP server (for AI assistant integration)
pip install 'ai-brief[mcp]'

# Or install from source
git clone https://github.com/Nas4146/brief.git
cd brief
pip install -e .              # CLI only
pip install -e '.[mcp]'       # CLI + MCP

Requirements: Python 3.9+

Dependencies: Minimal!

• Core (always installed):
  • click>=8.0.0 - CLI framework
  • pyyaml>=6.0.0 - Config file support
  • rich>=13.0.0 - Beautiful terminal output
• Optional (only if you want MCP):
  • mcp>=0.1.0 - Model Context Protocol support

Install what you need:

• Just want the CLI? → pip install ai-brief
• Want AI assistants to use Brief? → pip install 'ai-brief[mcp]'

Verify Installation

# Check CLI is installed
brief --version
# Output: brief, version 0.1.0

# Check MCP server (if installed with [mcp])
which brief-mcp
# Output: /path/to/brief-mcp (if installed)
#         brief-mcp not found (if not installed)

---

Quick Start

# 1. Navigate to your project
cd your-project

# 2. Initialize brief (discovers existing instruction files)
brief init
# ╭───────────────────╮
# │ Initializing brief│
# │ your-project      │
# ╰───────────────────╯
# 
# Found 3 instruction files:
# ✓ AGENTS.md
# ✓ CLAUDE.md
# ✓ .github/copilot-instructions.md

# 3. Add an instruction
brief update "Always use async/await for database calls"
# Preview changes with color-coded diffs
# Confirm with y/n

# 4. Validate everything is consistent
brief validate
# ✅ All instruction files are consistent!

# 5. List all instruction files
brief list
# Displays table with files and sizes

---

Features

• 🔍 Auto-discovery - Finds all instruction files automatically
• 🧠 Context-aware - Understands your project structure and conventions
• ✅ Validation - Ensures consistency across all files
• 🎯 Zero config - Works out of the box, customizable when needed
• 🪶 Lightweight - Minimal dependencies (Click + PyYAML + Rich)
• ✨ Beautiful UI - Professional terminal output with tables, panels, and color coding
• 🔒 Duplicate prevention - Fuzzy matching prevents redundant instructions
• 👀 Preview mode - See exactly what changes before applying
• 🤖 MCP Support - AI assistants can update their own instructions via Model Context Protocol

---

MCP Server (Optional)

Brief includes an optional MCP server that lets AI assistants update their own instruction files.

Note: MCP support is completely optional. The CLI works perfectly without it!

Installation

# Install Brief with MCP support
pip install 'ai-brief[mcp]'

Configuration

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "brief": {
      "command": "brief-mcp"
    }
  }
}

Don't use AI assistants with Brief? Skip this section! The CLI works independently.

See docs/MCP_SERVER.md for full MCP documentation.

---

Supported Files

Brief automatically discovers and updates these instruction files:

---

Commands

brief init

Initialize brief in your project. Discovers existing instruction files and analyzes project structure.

brief init

# Output:
# 🚀 Initializing brief in /Users/you/project
# 📝 Scanning for instruction files...
# ✅ Found 3 instruction file(s):
#    • AGENTS.md
#    • CLAUDE.md
#    • .github/copilot-instructions.md
# 🔍 Analyzing project structure...
#    Languages: Python, TypeScript
#    Frameworks: FastAPI, React
# ✅ Configuration file ready: .brief.yaml

brief update "instruction"

Add a new instruction to all files with context awareness.

brief update "Run tests before committing any code"

# Output:
# 📝 Analyzing project: your-project
# ✨ Updating 3 file(s) with context:
#    Languages: Python
#    Test framework: pytest
# 📊 Adding instruction: "Run tests before committing any code"
#    ✅ AGENTS.md
#    ✅ CLAUDE.md
#    ✅ .github/copilot-instructions.md

brief validate

Check instruction files for consistency across all agent files.

Two validation modes:

1. --check-all (default): Verifies that core instructions/guidance exists across all files

   • Checks if topics mentioned in one file are covered in others
   • Uses fuzzy matching - doesn't require word-for-word matches
   • Helps ensure no agent is missing important guidance

2. --check-latest: Verifies the most recent update was added to all files

   • Finds the most recently modified file
   • Checks if similar content exists in other files
   • Useful after running brief update to verify changes propagated

# Check overall consistency (default)
brief validate

# Check only if latest update is in all files
brief validate --check-latest --no-check-all

# Check both
brief validate --check-latest

# Output with issues:
# 🔍 Validating instructions in: your-project
# 📋 Checking 3 file(s)...
# 
#   File                              Status
#   ────────────────────────────────────────
#   AGENTS.md                           ✗
#   CLAUDE.md                           ✓
#   .github/copilot-instructions.md     ✗
#
# ⚠️  Found 2 issue(s):
#   • Recent update in 'CLAUDE.md' may be missing from: AGENTS.md
#   • 'copilot-instructions.md' may be missing guidance on: testing, error handling
#
# ❌ Found inconsistencies

# Output when consistent:
# ✅ All instruction files are consistent!

brief list

List all discovered instruction files.

brief list

# Output:
# 📋 Instruction files in: your-project
#    ✅ AGENTS.md (2,456 bytes)
#    ✅ CLAUDE.md (1,832 bytes)
#    ✅ .github/copilot-instructions.md (3,120 bytes)
# 📊 Total: 3 file(s)

---

Use Cases

For Solo Developers

Keep your personal AI assistant instructions consistent across tools without manual copy-paste.

For Teams

Onboard new developers faster by baking project conventions into AI tools.

For Open Source

Help contributors understand your project's workflow through AI assistants.

---

Project Structure

your-project/
├── AGENTS.md                          # Custom instructions
├── CLAUDE.md                          # Claude instructions
├── .github/
│   └── copilot-instructions.md       # Copilot instructions
├── .cursorrules                       # Cursor instructions
├── .brief.yaml                        # Brief config (optional)
└── src/
    └── ...

---

Configuration (Optional)

Brief works with zero configuration, but you can customize behavior with .brief.yaml:

version: 1

# Instruction files to manage
instruction_files:
  - AGENTS.md
  - CLAUDE.md
  - .github/copilot-instructions.md
  - .cursorrules

# Project metadata
project:
  languages:
    - Python
    - TypeScript
  frameworks:
    - FastAPI
    - React

# Enabled behaviors (coming soon)
behaviors:
  enabled:
    - test_before_commit
    - update_docs_after_changes

---

Development

# Clone the repository
git clone https://github.com/Nas4146/brief.git
cd brief

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Format code
black .

---

Roadmap

V0.1 (Current) - MVP ✅ Complete

• ✅ CLI with init, update, validate, list commands
• ✅ Auto-discovery of instruction files
• ✅ Context-aware updates (language, framework detection)
• ✅ Basic validation
• ✅ Diff preview before applying changes
• ✅ MCP server for AI assistant integration
• ✅ Duplicate prevention with fuzzy matching

V0.2 (Next)

• Template library with common behaviors
• sync command for applying templates
• Config file generation wizard
• Advanced consistency checking
• CI/CD integration examples

V0.3 (Future)

• Community template marketplace
• Web dashboard for team management
• Git hooks integration
• Multi-project synchronization

---

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

---

License

MIT © 2025

---

Why "Brief"?

Brief (verb): to give essential information to someone

Perfect for giving your AI assistants the essential context they need, once, and having it propagate everywhere.

---

Links

• GitHub: https://github.com/Nas4146/brief
• Issues: https://github.com/Nas4146/brief/issues

---