ai-agent-rules 0.40.1

Manage user-level AI agent configurations

AI Rules

Manage AI agent configurations through symlinks. Keep all your configs in one git-tracked location.

Overview

Consolidates config files for AI coding agents (Claude Code, Goose, Gemini CLI, Codex CLI, Amp) into a single source of truth via symlinks:

• Git-tracked configs synced across machines
• Edit once, apply everywhere
• Declarative plugin management (Claude Code)
• Exclude specific files (e.g., company-managed)
• Per-agent customizations

Supported: Claude Code, Goose, Gemini CLI, Codex CLI, Amp — plus Shared (AGENTS.md, skills)

Agent	Config dir	Skills dir
Amp	~/.config/amp/	~/.config/agents/skills/
Claude Code	~/.claude/	~/.claude/skills/
Codex CLI	~/.codex/	~/.agents/skills/
Gemini CLI	~/.gemini/	(via ~/.agents/skills/)
Goose	~/.config/goose/	~/.config/goose/skills/

Installation

Requirements: Python 3.10+, uv

From PyPI (Recommended)

One-command setup from PyPI:

uvx --from ai-agent-rules ai-agent-rules setup

This will:

1. Install AI agent configuration symlinks
2. Make ai-agent-rules (and the ai-rules alias) available system-wide
3. Auto-install optional tools (claude-code-statusline)

After setup, you can run ai-agent-rules (or ai-rules for short) from any directory.

From GitHub (Development)

Install from GitHub to get the latest development code:

uvx --from ai-agent-rules ai-agent-rules setup --github

This installs from the main branch and auto-detects the GitHub source for future updates.

Local Development

For contributing or local development:

git clone https://github.com/wpfleger96/ai-agent-rules.git
cd ai-agent-rules
uv run ai-agent-rules install

Use uv run ai-agent-rules <command> to test local changes. The global ai-agent-rules command continues to run your installed version (PyPI/GitHub).

Updating

Check for and install updates:

ai-agent-rules upgrade              # Check and install updates (shows changelogs)
ai-agent-rules upgrade --check      # Only check for updates
ai-agent-rules upgrade --force      # Force reinstall even if up to date
ai-agent-rules upgrade --skip-install  # Skip running install --rebuild-cache after upgrade
ai-agent-rules upgrade --only statusline  # Upgrade only a specific tool (ai-agent-rules | statusline)

Usage

Generate the full CLI reference with just docs.

Setup and Upgrade

ai-agent-rules setup                      # One-time setup: install symlinks + make available system-wide
ai-agent-rules setup --github             # Install from GitHub (pre-release)
ai-agent-rules setup --profile work       # Setup with a specific profile
ai-agent-rules setup --skip-symlinks      # Skip symlink installation
ai-agent-rules setup --skip-completions   # Skip shell completion installation
ai-agent-rules upgrade                    # Upgrade to latest version
ai-agent-rules upgrade --check            # Check for updates without installing

Install and Sync

ai-agent-rules install                    # Install all agent configs + optional tools
ai-agent-rules install --agents claude    # Install specific agent(s): amp, claude, codex, gemini, goose, shared
ai-agent-rules install --dry-run          # Preview changes
ai-agent-rules install -y                 # Auto-confirm without prompting
ai-agent-rules install --rebuild-cache    # Rebuild merged settings cache
ai-agent-rules install --profile work     # Install with a specific profile

Status and Inspection

ai-agent-rules status                     # Check symlink status + optional tools + active profile (✓✗⚠○), shows diffs
ai-agent-rules diff                       # Show config differences
ai-agent-rules validate                   # Verify source files exist
ai-agent-rules list-agents                # Show available agents
ai-agent-rules info                       # Show install source, versions, and update availability for all tools
ai-agent-rules uninstall                  # Remove all symlinks

Configuration

ai-agent-rules config init                # Interactive wizard for first-time setup
ai-agent-rules config show                # Show raw config files
ai-agent-rules config show --merged       # Show merged settings with overrides applied
ai-agent-rules config show --agent claude # Show config for a specific agent
ai-agent-rules config edit                # Edit user config in $EDITOR

Exclusions and Overrides

ai-agent-rules exclude add "~/.claude/*.json"      # Add exclusion pattern (supports globs)
ai-agent-rules exclude remove "~/.claude/*.json"   # Remove exclusion pattern
ai-agent-rules exclude list                        # List all exclusions

ai-agent-rules override set claude.model "claude-sonnet-4-6"        # Set override
ai-agent-rules override set claude.hooks.SubagentStop[0].hooks[0].command "script.py"  # Array notation
ai-agent-rules override unset claude.model                          # Remove override
ai-agent-rules override list                                        # List all overrides

Shell Completions

ai-agent-rules completions install [--shell bash|zsh]   # Install shell completions
ai-agent-rules completions uninstall [--shell bash|zsh] # Remove completions
ai-agent-rules completions update [--shell bash|zsh]    # Update completion script
ai-agent-rules completions status                       # Check if installed

Configuration

User-Level Config

Create ~/.ai-agent-rules-config.yaml for user-level settings:

version: 1

# Supports glob patterns: *.json, **/*.yaml, etc.
exclude_symlinks:
  - "~/.config/goose/config.yaml"
  - "~/.claude/*.log"
  - "~/.claude/agents/debug-*.md"

# Machine-specific settings overrides
settings_overrides:
  claude:
    model: "claude-sonnet-4-6"
  goose:
    provider: "anthropic"

Config file locations:

• ~/.ai-agent-rules-config.yaml — User-specific config (exclusions and overrides)
• ~/.ai-agent-rules/state.yaml — Active profile and last install timestamp (auto-managed)
• ~/.ai-agent-rules/cache/ — Merged settings cache (auto-generated)

Settings Overrides

Use settings_overrides to keep settings.json synced via git while allowing machine-specific values:

# ~/.ai-agent-rules-config.yaml on personal laptop
settings_overrides:
  claude:
    model: "claude-sonnet-4-6"

# ~/.ai-agent-rules-config.yaml on work laptop
settings_overrides:
  claude:
    model: "claude-opus-4-6"

Merge pipeline at install time:

1. Base settings from src/ai_rules/config/claude/settings.json (git-tracked)
2. Profile overrides applied (if a profile is active)
3. User overrides from ~/.ai-agent-rules-config.yaml (local only)
4. Preserved fields merged from cache (agent-managed fields)
5. Cached in ~/.ai-agent-rules/cache/claude/settings.json
6. Symlinked to ~/.claude/settings.json

After changing overrides, run ai-agent-rules install --rebuild-cache.

Preserved Fields

When agents manage their own config fields (e.g., MCP server lists, installed plugins), ai-agent-rules preserves them during installs by merging through a cache file:

Agent	Preserved fields	Cache path
Claude	enabledPlugins, hooks	~/.ai-agent-rules/cache/claude/settings.json
Goose	extensions	~/.ai-agent-rules/cache/goose/config.yaml
Codex	projects	~/.ai-agent-rules/cache/codex/config.toml
Gemini	ide	~/.ai-agent-rules/cache/gemini/settings.json

Array Notation for Nested Settings

Override commands support array index notation for complex nested structures:

ai-agent-rules override set claude.hooks.SubagentStop[0].hooks[0].command "uv run ~/my-hook.py"
ai-agent-rules override set claude.env.MY_VAR "value"

# Path validation catches typos with suggestions
ai-agent-rules override set claude.modle "sonnet"
# Error: Key 'modle' not found at 'modle'
# Available options: model, env, hooks, statusLine, ...

Codex Native Status Line

Codex stores footer configuration in ~/.codex/config.toml under [tui].status_line, so ai-agent-rules manages the native Codex footer directly instead of installing a separate status line tool.

Claude status line	Codex native item
model	model-with-reasoning
directory	current-dir
git-branch	git-branch
context-percentage	context-used
context-tokens	used-tokens
session-id	session-id
cost	No native Codex equivalent
lines-changed	No native Codex equivalent
session-clock	No native Codex equivalent

Override per machine with settings_overrides:

settings_overrides:
  codex:
    tui:
      status_line:
        - model-with-reasoning
        - current-dir
        - git-branch
        - context-used
        - used-tokens
        - session-id

codex.tui.status_line replaces the entire footer list, so setting a shorter array removes the bundled defaults instead of merging with them.

MCP Management

MCP servers are defined in src/ai_rules/config/mcps.json (shared across agents). Each agent's MCP manager translates the shared definitions into its native config format:

Agent	Format
Amp	JSON
Claude Code	JSON (mcpServers in settings.json)
Codex CLI	TOML
Gemini CLI	JSON
Goose	YAML extensions

Managed MCPs are tracked with a _managedBy: "ai-agent-rules" marker so the tool can distinguish its entries from user-added servers. Override MCPs per machine via mcp_overrides in your user config or profile:

# ~/.ai-agent-rules-config.yaml
mcp_overrides:
  my-server:
    env:
      API_KEY: "local-key"

Profiles

Profiles group configuration overrides into named presets for different machines or contexts.

ai-agent-rules profile list                    # List available profiles
ai-agent-rules profile show work               # View profile details
ai-agent-rules profile show work --resolved    # Show with inheritance applied
ai-agent-rules profile current                 # Check which profile is active
ai-agent-rules profile switch work             # Switch to a different profile
ai-agent-rules install --profile work          # Install with a specific profile

Three built-in profiles with inheritance: default -> personal -> work. Profiles support these keys:

# profiles/work.yaml
name: work
description: Work laptop with extended context model
extends: personal          # Inherit from personal, then override
settings_overrides:
  claude:
    env:
      ANTHROPIC_DEFAULT_SONNET_MODEL: "claude-sonnet-4-6[1m]"
    model: opus
plugins: []
marketplaces: []
exclude_symlinks: []
mcp_overrides: {}

User-defined profiles live at ~/.ai-agent-rules/profiles/<name>.yaml. Priority order (lowest to highest): profile overrides → local ~/.ai-agent-rules-config.yaml. Your local config always wins.

The active profile persists in ~/.ai-agent-rules/state.yaml across sessions.

Plugin Management

Specify Claude Code plugins declaratively in your profile or user config:

# profiles/work.yaml or ~/.ai-agent-rules-config.yaml
plugins:
  - name: feature-dev
    marketplace: claude-plugins-official
  - name: python-expert
    marketplace: cc-marketplace

marketplaces:
  - name: cc-marketplace
    source: ananddtyagi/cc-marketplace

When you run ai-agent-rules install:

1. Adds missing marketplaces via claude plugin marketplace add
2. Installs missing plugins via claude plugin install <name>@<marketplace>
3. Auto-uninstalls orphaned plugins that were previously managed by ai-agent-rules but removed from config
4. Warns about manually-installed plugins not in config (doesn't auto-uninstall them)

Plugin state is tracked in ~/.claude/plugins/ai-agent-rules-managed.json to avoid removing manually-installed plugins.

Structure

src/ai_rules/config/
├── AGENTS.md              # -> ~/AGENTS.md
├── chat_agent_hints.md    # Chat agent custom instructions
├── mcps.json              # Shared MCP server definitions
├── amp/                   # -> ~/.config/amp/
├── claude/                # -> ~/.claude/
├── codex/                 # -> ~/.codex/
├── gemini/                # -> ~/.gemini/
├── goose/                 # -> ~/.config/goose/
├── profiles/              # Built-in profiles (default, personal, work)
├── skills/                # 10 shared skills -> multiple agent skill dirs
│   └── */SKILL.md
└── sprout/                # Multi-agent coordinator prompts

Optional Tools

AI Rules automatically installs optional tools that enhance functionality:

• claude-code-statusline — Custom status line for Claude Code showing token usage, git info, time, and workspace details

These tools are installed automatically during setup and install. Check installation status:

ai-agent-rules status  # Shows Optional Tools section
ai-agent-rules info    # Shows install source, versions, update availability

If a tool fails to install, ai-agent-rules continues normally (fail-open behavior).

Extending

Add shared skill (Claude Code, Goose, Codex, Amp):

1. Create src/ai_rules/config/skills/my-skill/SKILL.md with frontmatter:

---
name: my-skill
description: "Brief description"
metadata:
  trigger-keywords: "keyword1, keyword2"
  trigger-patterns: "pattern1, pattern2"
---

2. Run ai-agent-rules install
3. Skill symlinked to ~/.claude/skills/, ~/.config/goose/skills/, ~/.config/agents/skills/ (Amp), and ~/.agents/skills/ (Codex). Gemini discovers skills from ~/.agents/skills/ via built-in alias — no dedicated dir needed.

Add Claude hook:

1. Create src/ai_rules/config/claude/hooks/my-hook.py
2. Run ai-agent-rules install
3. Configure in settings or overrides (e.g., UserPromptSubmit, SubagentStop)

Add new AI tool:

1. Add configs to src/ai_rules/config/<tool>/
2. Implement src/ai_rules/agents/<tool>.py
3. Register in src/ai_rules/cli.py::get_agents()

Safety

• First-run warnings
• Timestamped backups (*.ai-agent-rules-backup.YYYYMMDD-HHMMSS)
• Interactive prompts and dry-run mode
• Only manages symlinks (never deletes real files)
• Contextual error messages with tips

Troubleshooting

Wrong target: ai-agent-rules status then ai-agent-rules install -y

Restore backup:

ls -la ~/.CLAUDE.md.ai-agent-rules-backup.*
mv ~/.CLAUDE.md.ai-agent-rules-backup.20250104-143022 ~/.CLAUDE.md

Disable symlink: Use the exclude command or add to config manually:

ai-agent-rules exclude add "~/.claude/settings.json"
ai-agent-rules config edit

Override not applying: Rebuild the merged settings cache:

ai-agent-rules install --rebuild-cache

View merged settings: Check what's actually being applied:

ai-agent-rules config show --merged
ai-agent-rules config show --merged --agent claude

Upgrading from pre-v0.35? Config auto-migrates from ~/.ai-rules-config.yaml to ~/.ai-agent-rules-config.yaml and ~/.ai-rules/ to ~/.ai-agent-rules/.

License

MIT