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:

Install AI agent configuration symlinks
Make ai-agent-rules (and the ai-rules alias) available system-wide
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

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

Skills

ai-agent-rules skill list                 # List all bundled skills
ai-agent-rules skill show research        # Render skill content in terminal
ai-agent-rules skill show research --url  # Print versioned GitHub URL for sharing
ai-agent-rules skill show research --raw  # Print raw markdown (for piping)

Tools

ai-agent-rules tool list                              # Show managed tools with version and update info
ai-agent-rules tool show statusline                   # Detailed info for a specific tool
ai-agent-rules tool source list                       # List install source preferences
ai-agent-rules tool source get statusline             # Show source preference for a tool
ai-agent-rules tool source set statusline github      # Set install source (pypi, github, local:<path>, reset)

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
ai-agent-rules completions bash                         # Print raw bash completion script
ai-agent-rules completions zsh                          # Print raw zsh completion script

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:

Base settings from src/ai_rules/config/claude/settings.json (git-tracked)
Profile overrides applied (if a profile is active)
User overrides from ~/.ai-agent-rules-config.yaml (local only)
Preserved fields merged from cache (agent-managed fields)
Cached in ~/.ai-agent-rules/cache/claude/settings.json
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 ship with the tool, with inheritance chain default -> personal -> work. default is generic and suitable for anyone. personal and work are the author's own presets (for example, personal enables bypassPermissions) and are not generic recommendations. 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: []
managed_tools:             # Optional tool install sources
  install_sources: {}
agents_md_file: fragments/work.md  # Path relative to profiles dir; content appended to base
                                   # AGENTS.md, accumulating through inheritance parent-first.
                                   # Mutually exclusive with inline agents_md in the same profile.
                                   # Inline agents_md: | remains supported for short snippets.
exclude_symlinks: []
mcp_overrides: {}

User-defined profile files (e.g. ~/.ai-agent-rules/profiles/<name>.yaml) are not currently supported. Per-machine customization goes in ~/.ai-agent-rules-config.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.

Using the default profile

If you are not the author of this repo, install with the default profile to get generic engineering defaults that work for anyone. You can personalize without forking by adding a ~/.ai-agent-rules-config.yaml file: use agents_md to append your own rules to ~/AGENTS.md, and settings_overrides to adjust agent settings for your machine. If you want a fully custom setup with multiple named profiles, fork the repo and add your own profile YAML files and fragment files under src/ai_rules/config/profiles/.

# ~/.ai-agent-rules-config.yaml
agents_md: |
  ## My Team Standards

  - Always write tests for new features
  - Use conventional commits
  - Prefer explicit error handling over silent fallbacks

settings_overrides:
  claude:
    model: "claude-sonnet-4-6"

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:

Adds missing marketplaces via claude plugin marketplace add
Installs missing plugins via claude plugin install <name>@<marketplace>
Auto-uninstalls orphaned plugins that were previously managed by ai-agent-rules but removed from config
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)
│   └── fragments/         # Profile AGENTS.md fragment files (referenced via agents_md_file)
├── skills/                # 10 shared skills -> multiple agent skill dirs
│   └── */SKILL.md
└── buzz/                  # 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 tool list  # 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):

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"
---

Run ai-agent-rules install
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:

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

Add new AI tool:

Add configs to src/ai_rules/config/<tool>/
Implement src/ai_rules/agents/<tool>.py
Register in src/ai_rules/targets/registry.py::TARGET_CLASSES

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

Name		Name	Last commit message	Last commit date
Latest commit History 669 Commits
.github/workflows		.github/workflows
.hooks		.hooks
src/ai_rules		src/ai_rules
tests		tests
.ai-agent-rules-config.yaml.example		.ai-agent-rules-config.yaml.example
.editorconfig		.editorconfig
.gitignore		.gitignore
.python-version		.python-version
.release-please-manifest.json		.release-please-manifest.json
.tokeignore		.tokeignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Justfile		Justfile
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
release-please-config.json		release-please-config.json
renovate.json		renovate.json
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

AI Rules

Overview

Installation

From PyPI (Recommended)

From GitHub (Development)

Local Development

Updating

Usage

Setup and Upgrade

Install and Sync

Status and Inspection

Configuration

Exclusions and Overrides

Skills

Tools

Shell Completions

Configuration

User-Level Config

Settings Overrides

Preserved Fields

Array Notation for Nested Settings

Codex Native Status Line

MCP Management

Profiles

Using the default profile

Plugin Management

Structure

Optional Tools

Extending

Safety

Troubleshooting

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 206

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages