{"id":49239748,"url":"https://github.com/wpfleger96/ai-agent-rules","last_synced_at":"2026-05-28T05:01:06.192Z","repository":{"id":310115411,"uuid":"1038696039","full_name":"wpfleger96/ai-agent-rules","owner":"wpfleger96","description":"Manage configs for Claude Code, Codex, Gemini CLI, Goose, and Amp from one repo — symlinks, merge pipeline, profile inheritance, cross-machine sync","archived":false,"fork":false,"pushed_at":"2026-05-23T20:24:36.000Z","size":1401,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-23T21:20:19.315Z","etag":null,"topics":["ai","claude-code","coding-agents","llm","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wpfleger96.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-08-15T17:01:00.000Z","updated_at":"2026-05-23T20:24:40.000Z","dependencies_parsed_at":"2026-02-05T20:04:37.324Z","dependency_job_id":null,"html_url":"https://github.com/wpfleger96/ai-agent-rules","commit_stats":null,"previous_names":["wpfleger96/ai-tools","wpfleger96/ai-rules"],"tags_count":155,"template":false,"template_full_name":null,"purl":"pkg:github/wpfleger96/ai-agent-rules","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpfleger96%2Fai-agent-rules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpfleger96%2Fai-agent-rules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpfleger96%2Fai-agent-rules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpfleger96%2Fai-agent-rules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wpfleger96","download_url":"https://codeload.github.com/wpfleger96/ai-agent-rules/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpfleger96%2Fai-agent-rules/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33594851,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude-code","coding-agents","llm","python"],"created_at":"2026-04-24T19:02:30.473Z","updated_at":"2026-05-28T05:01:06.186Z","avatar_url":"https://github.com/wpfleger96.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Rules\n\nManage AI agent configurations through symlinks. Keep all your configs in one git-tracked location.\n\n[![PyPI Downloads](https://img.shields.io/pypi/dm/ai-agent-rules.svg)](https://pypi.org/project/ai-agent-rules/)\n[![PyPI version](https://img.shields.io/pypi/v/ai-agent-rules.svg)](https://pypi.org/project/ai-agent-rules/)\n[![Python Versions](https://img.shields.io/pypi/pyversions/ai-agent-rules.svg)](https://pypi.org/project/ai-agent-rules/)\n[![CI](https://github.com/wpfleger96/ai-agent-rules/actions/workflows/ci.yml/badge.svg)](https://github.com/wpfleger96/ai-agent-rules/actions/workflows/ci.yml)\n[![GitHub Contributors](https://img.shields.io/github/contributors/wpfleger96/ai-agent-rules.svg)](https://github.com/wpfleger96/ai-agent-rules/graphs/contributors)\n[![Lines of Code](https://aschey.tech/tokei/github/wpfleger96/ai-agent-rules?category=code)](https://github.com/wpfleger96/ai-agent-rules)\n[![License](https://img.shields.io/github/license/wpfleger96/ai-agent-rules.svg)](https://github.com/wpfleger96/ai-agent-rules/blob/main/LICENSE)\n\n## Overview\n\nConsolidates config files for AI coding agents (Claude Code, Goose, Gemini CLI, Codex CLI, Amp) into a single source of truth via symlinks:\n\n- Git-tracked configs synced across machines\n- Edit once, apply everywhere\n- Declarative plugin management (Claude Code)\n- Exclude specific files (e.g., company-managed)\n- Per-agent customizations\n\n**Supported:** Claude Code, Goose, Gemini CLI, Codex CLI, Amp — plus Shared (AGENTS.md, skills)\n\n| Agent | Config dir | Skills dir |\n|-------|-----------|------------|\n| Amp | `~/.config/amp/` | `~/.config/agents/skills/` |\n| Claude Code | `~/.claude/` | `~/.claude/skills/` |\n| Codex CLI | `~/.codex/` | `~/.agents/skills/` |\n| Gemini CLI | `~/.gemini/` | (via `~/.agents/skills/`) |\n| Goose | `~/.config/goose/` | `~/.config/goose/skills/` |\n\n## Installation\n\n**Requirements:** Python 3.10+, [uv](https://github.com/astral-sh/uv)\n\n### From PyPI (Recommended)\n\nOne-command setup from PyPI:\n\n```bash\nuvx --from ai-agent-rules ai-agent-rules setup\n```\n\nThis will:\n1. Install AI agent configuration symlinks\n2. Make `ai-agent-rules` (and the `ai-rules` alias) available system-wide\n3. Auto-install optional tools (claude-code-statusline)\n\nAfter setup, you can run `ai-agent-rules` (or `ai-rules` for short) from any directory.\n\n### From GitHub (Development)\n\nInstall from GitHub to get the latest development code:\n\n```bash\nuvx --from ai-agent-rules ai-agent-rules setup --github\n```\n\nThis installs from the main branch and auto-detects the GitHub source for future updates.\n\n### Local Development\n\nFor contributing or local development:\n\n```bash\ngit clone https://github.com/wpfleger96/ai-agent-rules.git\ncd ai-agent-rules\nuv run ai-agent-rules install\n```\n\nUse `uv run ai-agent-rules \u003ccommand\u003e` to test local changes. The global `ai-agent-rules` command continues to run your installed version (PyPI/GitHub).\n\n### Updating\n\nCheck for and install updates:\n\n```bash\nai-agent-rules upgrade              # Check and install updates (shows changelogs)\nai-agent-rules upgrade --check      # Only check for updates\nai-agent-rules upgrade --force      # Force reinstall even if up to date\nai-agent-rules upgrade --skip-install  # Skip running install --rebuild-cache after upgrade\nai-agent-rules upgrade --only statusline  # Upgrade only a specific tool (ai-agent-rules | statusline)\n```\n\n## Usage\n\n### Setup and Upgrade\n\n```bash\nai-agent-rules setup                      # One-time setup: install symlinks + make available system-wide\nai-agent-rules setup --github             # Install from GitHub (pre-release)\nai-agent-rules setup --profile work       # Setup with a specific profile\nai-agent-rules setup --skip-symlinks      # Skip symlink installation\nai-agent-rules setup --skip-completions   # Skip shell completion installation\nai-agent-rules upgrade                    # Upgrade to latest version\nai-agent-rules upgrade --check            # Check for updates without installing\n```\n\n### Install and Sync\n\n```bash\nai-agent-rules install                    # Install all agent configs + optional tools\nai-agent-rules install --agents claude    # Install specific agent(s): amp, claude, codex, gemini, goose, shared\nai-agent-rules install --dry-run          # Preview changes\nai-agent-rules install -y                 # Auto-confirm without prompting\nai-agent-rules install --rebuild-cache    # Rebuild merged settings cache\nai-agent-rules install --profile work     # Install with a specific profile\n```\n\n### Status and Inspection\n\n```bash\nai-agent-rules status                     # Check symlink status + optional tools + active profile (✓✗⚠○), shows diffs\nai-agent-rules diff                       # Show config differences\nai-agent-rules validate                   # Verify source files exist\nai-agent-rules list-agents                # Show available agents\nai-agent-rules uninstall                  # Remove all symlinks\n```\n\n### Configuration\n\n```bash\nai-agent-rules config init                # Interactive wizard for first-time setup\nai-agent-rules config show                # Show raw config files\nai-agent-rules config show --merged       # Show merged settings with overrides applied\nai-agent-rules config show --agent claude # Show config for a specific agent\nai-agent-rules config edit                # Edit user config in $EDITOR\n```\n\n### Exclusions and Overrides\n\n```bash\nai-agent-rules exclude add \"~/.claude/*.json\"      # Add exclusion pattern (supports globs)\nai-agent-rules exclude remove \"~/.claude/*.json\"   # Remove exclusion pattern\nai-agent-rules exclude list                        # List all exclusions\n\nai-agent-rules override set claude.model \"claude-sonnet-4-6\"        # Set override\nai-agent-rules override set claude.hooks.SubagentStop[0].hooks[0].command \"script.py\"  # Array notation\nai-agent-rules override unset claude.model                          # Remove override\nai-agent-rules override list                                        # List all overrides\n```\n\n### Skills\n\n```bash\nai-agent-rules skill list                 # List all bundled skills\nai-agent-rules skill show research        # Render skill content in terminal\nai-agent-rules skill show research --url  # Print versioned GitHub URL for sharing\nai-agent-rules skill show research --raw  # Print raw markdown (for piping)\n```\n\n### Tools\n\n```bash\nai-agent-rules tool list                              # Show managed tools with version and update info\nai-agent-rules tool show statusline                   # Detailed info for a specific tool\nai-agent-rules tool source list                       # List install source preferences\nai-agent-rules tool source get statusline             # Show source preference for a tool\nai-agent-rules tool source set statusline github      # Set install source (pypi, github, local:\u003cpath\u003e, reset)\n```\n\n### Shell Completions\n\n```bash\nai-agent-rules completions install [--shell bash|zsh]   # Install shell completions\nai-agent-rules completions uninstall [--shell bash|zsh] # Remove completions\nai-agent-rules completions update [--shell bash|zsh]    # Update completion script\nai-agent-rules completions status                       # Check if installed\nai-agent-rules completions bash                         # Print raw bash completion script\nai-agent-rules completions zsh                          # Print raw zsh completion script\n```\n\n## Configuration\n\n### User-Level Config\n\nCreate `~/.ai-agent-rules-config.yaml` for user-level settings:\n\n```yaml\nversion: 1\n\n# Supports glob patterns: *.json, **/*.yaml, etc.\nexclude_symlinks:\n  - \"~/.config/goose/config.yaml\"\n  - \"~/.claude/*.log\"\n  - \"~/.claude/agents/debug-*.md\"\n\n# Machine-specific settings overrides\nsettings_overrides:\n  claude:\n    model: \"claude-sonnet-4-6\"\n  goose:\n    provider: \"anthropic\"\n```\n\n**Config file locations:**\n- `~/.ai-agent-rules-config.yaml` — User-specific config (exclusions and overrides)\n- `~/.ai-agent-rules/state.yaml` — Active profile and last install timestamp (auto-managed)\n- `~/.ai-agent-rules/cache/` — Merged settings cache (auto-generated)\n\n### Settings Overrides\n\nUse `settings_overrides` to keep `settings.json` synced via git while allowing machine-specific values:\n\n```yaml\n# ~/.ai-agent-rules-config.yaml on personal laptop\nsettings_overrides:\n  claude:\n    model: \"claude-sonnet-4-6\"\n\n# ~/.ai-agent-rules-config.yaml on work laptop\nsettings_overrides:\n  claude:\n    model: \"claude-opus-4-6\"\n```\n\nMerge pipeline at install time:\n1. **Base settings** from `src/ai_rules/config/claude/settings.json` (git-tracked)\n2. **Profile overrides** applied (if a profile is active)\n3. **User overrides** from `~/.ai-agent-rules-config.yaml` (local only)\n4. **Preserved fields** merged from cache (agent-managed fields)\n5. **Cached** in `~/.ai-agent-rules/cache/claude/settings.json`\n6. **Symlinked** to `~/.claude/settings.json`\n\nAfter changing overrides, run `ai-agent-rules install --rebuild-cache`.\n\n#### Preserved Fields\n\nWhen 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:\n\n| Agent | Preserved fields | Cache path |\n|-------|-----------------|------------|\n| Claude | `enabledPlugins`, `hooks` | `~/.ai-agent-rules/cache/claude/settings.json` |\n| Goose | `extensions` | `~/.ai-agent-rules/cache/goose/config.yaml` |\n| Codex | `projects` | `~/.ai-agent-rules/cache/codex/config.toml` |\n| Gemini | `ide` | `~/.ai-agent-rules/cache/gemini/settings.json` |\n\n#### Array Notation for Nested Settings\n\nOverride commands support array index notation for complex nested structures:\n\n```bash\nai-agent-rules override set claude.hooks.SubagentStop[0].hooks[0].command \"uv run ~/my-hook.py\"\nai-agent-rules override set claude.env.MY_VAR \"value\"\n\n# Path validation catches typos with suggestions\nai-agent-rules override set claude.modle \"sonnet\"\n# Error: Key 'modle' not found at 'modle'\n# Available options: model, env, hooks, statusLine, ...\n```\n\n#### Codex Native Status Line\n\nCodex 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.\n\n| Claude status line | Codex native item |\n|--------------------|-------------------|\n| `model` | `model-with-reasoning` |\n| `directory` | `current-dir` |\n| `git-branch` | `git-branch` |\n| `context-percentage` | `context-used` |\n| `context-tokens` | `used-tokens` |\n| `session-id` | `session-id` |\n| `cost` | No native Codex equivalent |\n| `lines-changed` | No native Codex equivalent |\n| `session-clock` | No native Codex equivalent |\n\nOverride per machine with `settings_overrides`:\n\n```yaml\nsettings_overrides:\n  codex:\n    tui:\n      status_line:\n        - model-with-reasoning\n        - current-dir\n        - git-branch\n        - context-used\n        - used-tokens\n        - session-id\n```\n\n`codex.tui.status_line` replaces the entire footer list, so setting a shorter array removes the bundled defaults instead of merging with them.\n\n### MCP Management\n\nMCP 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:\n\n| Agent | Format |\n|-------|--------|\n| Amp | JSON |\n| Claude Code | JSON (`mcpServers` in `settings.json`) |\n| Codex CLI | TOML |\n| Gemini CLI | JSON |\n| Goose | YAML extensions |\n\nManaged 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:\n\n```yaml\n# ~/.ai-agent-rules-config.yaml\nmcp_overrides:\n  my-server:\n    env:\n      API_KEY: \"local-key\"\n```\n\n### Profiles\n\nProfiles group configuration overrides into named presets for different machines or contexts.\n\n```bash\nai-agent-rules profile list                    # List available profiles\nai-agent-rules profile show work               # View profile details\nai-agent-rules profile show work --resolved    # Show with inheritance applied\nai-agent-rules profile current                 # Check which profile is active\nai-agent-rules profile switch work             # Switch to a different profile\nai-agent-rules install --profile work          # Install with a specific profile\n```\n\nThree built-in profiles with inheritance: `default -\u003e personal -\u003e work`. Profiles support these keys:\n\n```yaml\n# profiles/work.yaml\nname: work\ndescription: Work laptop with extended context model\nextends: personal          # Inherit from personal, then override\nsettings_overrides:\n  claude:\n    env:\n      ANTHROPIC_DEFAULT_SONNET_MODEL: \"claude-sonnet-4-6[1m]\"\n    model: opus\nplugins: []\nmarketplaces: []\nexclude_symlinks: []\nmcp_overrides: {}\n```\n\nUser-defined profiles live at `~/.ai-agent-rules/profiles/\u003cname\u003e.yaml`. Priority order (lowest to highest): profile overrides → local `~/.ai-agent-rules-config.yaml`. Your local config always wins.\n\nThe active profile persists in `~/.ai-agent-rules/state.yaml` across sessions.\n\n### Plugin Management\n\nSpecify Claude Code plugins declaratively in your profile or user config:\n\n```yaml\n# profiles/work.yaml or ~/.ai-agent-rules-config.yaml\nplugins:\n  - name: feature-dev\n    marketplace: claude-plugins-official\n  - name: python-expert\n    marketplace: cc-marketplace\n\nmarketplaces:\n  - name: cc-marketplace\n    source: ananddtyagi/cc-marketplace\n```\n\nWhen you run `ai-agent-rules install`:\n1. Adds missing marketplaces via `claude plugin marketplace add`\n2. Installs missing plugins via `claude plugin install \u003cname\u003e@\u003cmarketplace\u003e`\n3. Auto-uninstalls orphaned plugins that were previously managed by ai-agent-rules but removed from config\n4. Warns about manually-installed plugins not in config (doesn't auto-uninstall them)\n\nPlugin state is tracked in `~/.claude/plugins/ai-agent-rules-managed.json` to avoid removing manually-installed plugins.\n\n## Structure\n\n```\nsrc/ai_rules/config/\n├── AGENTS.md              # -\u003e ~/AGENTS.md\n├── chat_agent_hints.md    # Chat agent custom instructions\n├── mcps.json              # Shared MCP server definitions\n├── amp/                   # -\u003e ~/.config/amp/\n├── claude/                # -\u003e ~/.claude/\n├── codex/                 # -\u003e ~/.codex/\n├── gemini/                # -\u003e ~/.gemini/\n├── goose/                 # -\u003e ~/.config/goose/\n├── profiles/              # Built-in profiles (default, personal, work)\n├── skills/                # 10 shared skills -\u003e multiple agent skill dirs\n│   └── */SKILL.md\n└── sprout/                # Multi-agent coordinator prompts\n```\n\n## Optional Tools\n\nAI Rules automatically installs optional tools that enhance functionality:\n\n- **claude-code-statusline** — Custom status line for Claude Code showing token usage, git info, time, and workspace details\n\nThese tools are installed automatically during `setup` and `install`. Check installation status:\n\n```bash\nai-agent-rules status  # Shows Optional Tools section\nai-agent-rules tool list  # Shows install source, versions, update availability\n```\n\nIf a tool fails to install, ai-agent-rules continues normally (fail-open behavior).\n\n## Extending\n\n**Add shared skill (Claude Code, Goose, Codex, Amp):**\n1. Create `src/ai_rules/config/skills/my-skill/SKILL.md` with frontmatter:\n```yaml\n---\nname: my-skill\ndescription: \"Brief description\"\nmetadata:\n  trigger-keywords: \"keyword1, keyword2\"\n  trigger-patterns: \"pattern1, pattern2\"\n---\n```\n2. Run `ai-agent-rules install`\n3. 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.\n\n**Add Claude hook:**\n1. Create `src/ai_rules/config/claude/hooks/my-hook.py`\n2. Run `ai-agent-rules install`\n3. Configure in settings or overrides (e.g., UserPromptSubmit, SubagentStop)\n\n**Add new AI tool:**\n1. Add configs to `src/ai_rules/config/\u003ctool\u003e/`\n2. Implement `src/ai_rules/agents/\u003ctool\u003e.py`\n3. Register in `src/ai_rules/targets/registry.py::TARGET_CLASSES`\n\n## Safety\n\n- First-run warnings\n- Timestamped backups (`*.ai-agent-rules-backup.YYYYMMDD-HHMMSS`)\n- Interactive prompts and dry-run mode\n- Only manages symlinks (never deletes real files)\n- Contextual error messages with tips\n\n## Troubleshooting\n\n**Wrong target:** `ai-agent-rules status` then `ai-agent-rules install -y`\n\n**Restore backup:**\n```bash\nls -la ~/.CLAUDE.md.ai-agent-rules-backup.*\nmv ~/.CLAUDE.md.ai-agent-rules-backup.20250104-143022 ~/.CLAUDE.md\n```\n\n**Disable symlink:** Use the exclude command or add to config manually:\n```bash\nai-agent-rules exclude add \"~/.claude/settings.json\"\nai-agent-rules config edit\n```\n\n**Override not applying:** Rebuild the merged settings cache:\n```bash\nai-agent-rules install --rebuild-cache\n```\n\n**View merged settings:** Check what's actually being applied:\n```bash\nai-agent-rules config show --merged\nai-agent-rules config show --merged --agent claude\n```\n\n**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/`.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwpfleger96%2Fai-agent-rules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwpfleger96%2Fai-agent-rules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwpfleger96%2Fai-agent-rules/lists"}