ai-agent-rules

AI Rules is a command-line tool for keeping the configuration of several AI coding agents in a single, git-tracked location and linking it into each agent's expected config directory with symlinks. The stated goal is "edit once, apply everywhere" while still allowing per-agent and per-machine customization. Supported agents and their config directories: - Amp: ~/.config/amp/ (skills in ~/.config/agents/skills/) - Claude Code: ~/.claude/ (skills in ~/.claude/skills/) - Codex CLI: ~/.codex/ (skills in ~/.agents/skills/) - Gemini CLI: ~/.gemini/ (discovers skills via ~/.agents/skills/) - Goose: ~/.config/goose/ (skills in ~/.config/goose/skills/) - Shared material such as AGENTS.md and skills Installation requires Python 3.10+ and uv. The recommended path is a one-command setup from PyPI (uvx --from ai-agent-rules ai-agent-rules setup), which installs symlinks, makes the ai-agent-rules command (and the ai-rules alias) available system-wide, and optionally installs helper tools. A --github flag installs from the main branch instead, and local development uses uv run ai-agent-rules install. An upgrade command checks for and installs updates, with flags for check-only, force, skipping the post-upgrade install, or upgrading only a specific tool. Core commands cover setup, install/sync, status and inspection, configuration, exclusions and overrides, skills, tools, and shell completions. Notable behaviors: - install supports selecting specific agents, dry-run previews, auto-confirm, cache rebuilds, and profile selection. - status reports symlink state, optional tools, and the active profile with status symbols and diffs; validate checks that source files exist; uninstall removes symlinks. - config init/show/edit exposes raw or merged settings, optionally per agent. - exclude add/remove/list manages glob patterns for files that should not be symlinked (for example company-managed files). - override set/unset/list edits nested settings, including array-index notation for structures such as hook command arrays, with path validation that suggests valid keys on typos. - skill list/show renders bundled skills, can print a versioned GitHub URL for sharing, or emit raw markdown for piping. - tool list/show and tool source get/set manage optional tools and their install source (pypi, github, local path, reset). - completions install/uninstall/update/status and raw bash/zsh script output are provided. Configuration is layered. A user-level file at ~/.ai-agent-rules-config.yaml holds exclusions and machine-specific settings_overrides. State (active profile, last install timestamp) lives in ~/.ai-agent-rules/state.yaml, and merged settings are cached under ~/.ai-agent-rules/cache/. The documented merge pipeline is: base git-tracked settings, then profile overrides, then user overrides, then preserved agent-managed fields merged from cache, then caching, then symlinking into the agent's directory. Preserved fields include Claude's enabledPlugins and hooks, Goose's extensions, Codex's projects, and Gemini's ide. Changing overrides requires running install --rebuild-cache. Profiles group overrides into named presets and support inheritance; three built-in profiles ship with the tool with the chain default -> personal -> work, where default is described as generic and personal/work as the author's own presets rather than general recommendations. Profiles can define settings_overrides, plugins, marketplaces, managed tool install sources, AGENTS.md fragments (agents_md_file, appended parent-first through inheritance, mutually exclusive with inline agents_md), exclusions, and MCP overrides. Local user config takes priority over profile overrides. User-defined profile files are not currently supported; per-machine customization goes in the user config file. MCP servers are defined once in a shared mcps.json and translated by each agent's manager into native formats (JSON for Amp, Claude, Gemini; TOML for Codex; YAML extensions for Goose). Managed entries carry a _managedBy marker to distinguish them from user-added servers, and mcp_overrides allow per-machine values such as API keys. Claude Code plugins can be declared in profiles or user config; install adds missing marketplaces and plugins, auto-uninstalls orphaned previously managed plugins, and warns about manually installed ones without removing them. Plugin state is tracked in a managed JSON file. Safety features include first-run warnings, timestamped backups, interactive prompts, dry-run mode, a claim that only symlinks are managed and real files are never deleted, and contextual error messages. Troubleshooting guidance covers wrong targets, restoring backups, disabling a symlink via exclusion, rebuilding the cache when overrides do not apply, viewing merged settings, and automatic migration from pre-v0.35 config paths. The project is MIT licensed.