{"id":50561815,"url":"https://github.com/simtabi/ai-config-kit","last_synced_at":"2026-06-04T12:01:09.384Z","repository":{"id":358197096,"uuid":"1240232781","full_name":"simtabi/ai-config-kit","owner":"simtabi","description":"Manage ~/.claude and cross-vendor AI agent rules: 7-vendor adapters, decision packs, AGENTS.md composition.","archived":false,"fork":false,"pushed_at":"2026-05-16T07:52:58.000Z","size":586,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T08:46:21.671Z","etag":null,"topics":["agents-md","ai-coding-agents","claude","claude-code","config-manager","dotfiles","oss","python","symlink"],"latest_commit_sha":null,"homepage":"https://opensource.simtabi.com/products/ai-configurator","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/simtabi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T22:52:13.000Z","updated_at":"2026-05-16T07:53:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/simtabi/ai-config-kit","commit_stats":null,"previous_names":["simtabi/ai-config-kit"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/simtabi/ai-config-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simtabi%2Fai-config-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simtabi%2Fai-config-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simtabi%2Fai-config-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simtabi%2Fai-config-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simtabi","download_url":"https://codeload.github.com/simtabi/ai-config-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simtabi%2Fai-config-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33903134,"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-06-04T02:00:06.755Z","response_time":64,"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":["agents-md","ai-coding-agents","claude","claude-code","config-manager","dotfiles","oss","python","symlink"],"created_at":"2026-06-04T12:01:08.252Z","updated_at":"2026-06-04T12:01:09.373Z","avatar_url":"https://github.com/simtabi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ai-config-kit\n\n[![CI](https://github.com/simtabi/ai-config-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/simtabi/ai-config-kit/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/ai-config-kit.svg)](https://pypi.org/project/ai-config-kit/)\n[![Python](https://img.shields.io/pypi/pyversions/ai-config-kit.svg)](https://pypi.org/project/ai-config-kit/)\n[![License](https://img.shields.io/github/license/simtabi/ai-config-kit.svg)](LICENSE)\n\nVersion your `~/.claude/` directory without versioning your caches.\nAuthor rules once, ship them to every AI coding agent you use.\n\n`ai-config-kit` symlinks a content directory you control into\n`~/.claude/` at the paths [Claude Code](https://docs.claude.com/en/docs/claude-code/overview)\nexpects, ships opinionated \"decision packs\" that bake in\ncontent-filter-safe practices, and gives you one verb each for\nsetting up a fresh machine and dropping cross-vendor rules into any\nproject repo. Wired adapters: claude-code, aider, cursor, windsurf,\ncopilot, codex, cline.\n\n```bash\npip install ai-config-kit\nai-config-kit bootstrap        # validate + init + install + doctor, one shot\n```\n\n---\n\n## Table of contents\n\n- [Why it exists](#why-it-exists)\n- [Install](#install)\n- [Quick start](#quick-start)\n- [Commands at a glance](#commands-at-a-glance)\n- [Decisions: bundled global rules](#decisions-bundled-global-rules)\n- [The fetch command + canonical-file pattern](#the-fetch-command--canonical-file-pattern)\n- [Multi-machine setup](#multi-machine-setup)\n- [Documentation](#documentation)\n- [Project layout](#project-layout)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Why it exists\n\n`~/.claude/` is a mixed bag:\n\n| Kind | Examples | Worth versioning? |\n|---|---|---|\n| **Config** | `CLAUDE.md`, `settings.json`, `commands/`, `agents/`, `skills/`, `hooks/`, `prompts/`, `projects/*/memory/`, `plugins/blocklist.json` | yes |\n| **Opt-in** | `sessions/`, `history.jsonl` | maybe (grow fast) |\n| **Runtime** | `paste-cache/`, `file-history/`, `tasks/`, `todos/`, `cache/`, `plans/`, `statsig/`, `telemetry/` | no |\n| **Secret** | `.credentials.json`, SSH keys, `.npmrc`, `.netrc`, `.env*` | never |\n\nPutting the whole directory under git means versioning hundreds of MB\nof caches and fighting `.gitignore` every time Claude Code adds a new\nruntime path. `ai-config-kit` solves this by keeping your\ncanonical config in a content directory (default\n`~/.config/claude-config/content/`), symlinked into `~/.claude/` at\nthe right paths. Edit a file in `~/.claude/` and you're editing the\ncontent dir; commit and push to share across machines.\n\nThe classification above is enforced by the install command. See\n[`docs/architecture.md`](docs/architecture.md) for the full table.\n\n---\n\n## Install\n\n```bash\npip install ai-config-kit\n# or:  pipx install ai-config-kit\n# or:  uv tool install ai-config-kit\n```\n\nRequirements: Python 3.10+, `git` on `PATH` (only for `init` and\n`sync`). Works on macOS, Linux, and Windows (Windows symlinks need\neither Administrator or Developer Mode). Full install notes in\n[`docs/installation.md`](docs/installation.md).\n\n---\n\n## One-liner install (any platform)\n\nIf you have neither `pip` nor `ai-config-kit` yet, use the\n[`get-installer`](https://github.com/simtabi/get-installer) bootstrap\n(a sibling Simtabi project):\n\n```bash\n# POSIX (macOS / Linux / WSL / Git-Bash)\nsh -c \"$(curl -fsSL https://get.simtabi.com/install.sh)\" -- \\\n  --product ai-config-kit\n\n# PowerShell (Windows)\nirm https://get.simtabi.com/install.ps1 | iex\n```\n\n`get-installer` is registry-driven, version-aware, journals every\naction for clean rollback on failure, and refuses to run as root. It\npreviously shipped inside this repo at `installer/`; it now lives as\nits own project so other Simtabi tools (and third parties) can vendor\nit. Full design + threat model: \u003chttps://github.com/simtabi/get-installer\u003e.\n\n## Quick start (after pip install)\n\n```bash\nai-config-kit bootstrap\n```\n\nRuns validate → init → install → doctor with prompts. Idempotent:\nsafe to re-run on a machine that's already set up. Pass `--push` to\nalso commit + push the content dir to its remote, `--remote URL` to\nconfigure `origin` on a fresh machine, `--dry-run` to see what would\nhappen.\n\nOnce installed:\n\n```bash\nai-config-kit status              # what's tracked, what's not, git state\nai-config-kit list                # grouped view of everything in content\nai-config-kit view CLAUDE.md      # print a tracked file\nai-config-kit sync -m \"tighten X\" # commit changes in the content dir\n```\n\n---\n\n## Multi-vendor: one rules source, every AI agent\n\n`ai-config-kit` ships adapters for seven CLI-based AI coding agents.\nAuthored rules live once in your content dir; each vendor's expected\nfile format gets generated on demand.\n\n```bash\n# Compose the cross-vendor canonical from CLAUDE.md + decision packs\nai-config-kit compose-agents-md\n\n# Drop AGENTS.md, .cursorrules, .windsurfrules, .clinerules, and\n# .github/copilot-instructions.md into a project repo in one shot\nai-config-kit project-install ~/code/my-app \\\n    --vendor=aider --vendor=cursor --vendor=windsurf \\\n    --vendor=copilot --vendor=codex --vendor=cline\n```\n\nThe supported vendors and their conventions:\n\n| Vendor | Project file | Global target |\n|---|---|---|\n| claude-code | (none) | `~/.claude/` |\n| aider | `AGENTS.md` | (none) |\n| codex | `AGENTS.md` (native) | `~/.codex/instructions/` |\n| cursor | `.cursorrules` | `~/.cursor/rules/` |\n| cline | `.clinerules` | (none) |\n| windsurf | `.windsurfrules` | (none) |\n| copilot | `.github/copilot-instructions.md` | (none) |\n\n`install` also writes the canonical `AGENTS.md` into each configured\nvendor's global target (currently only cursor benefits). Existing\nper-project files are never overwritten without `--force`.\n\n---\n\n## Commands at a glance\n\n| Verb | What it does |\n|---|---|\n| [`bootstrap`](docs/tools/ai-config-kit.md#bootstrap--one-shot-first-time-setup) | One-shot setup (validate + init + install + optional push + doctor). |\n| [`init`](docs/tools/ai-config-kit.md#init--create-the-content-dir) | Create the content dir + git repo + apply default decision packs. |\n| [`install`](docs/tools/ai-config-kit.md#install--symlink-into-target) | Symlink `content/claude/*` into `~/.claude/`; also drops `AGENTS.md` into each non-claude-code vendor's global target (e.g., `~/.cursor/rules/`). |\n| [`compose-agents-md`](docs/tools/ai-config-kit.md#compose-agents-md-synthesize-the-canonical-cross-vendor-file) | Synthesize a single `AGENTS.md` from `CLAUDE.md` + decision-pack fragments. |\n| [`project-install`](docs/tools/ai-config-kit.md#project-install-per-vendor-files-for-a-project-repo) | Write per-vendor files (`AGENTS.md`, `.cursorrules`, `.windsurfrules`, ...) into a project repo. |\n| [`uninstall`](docs/tools/ai-config-kit.md#uninstall--remove-symlinks) | Remove symlinks; restore pre-install backups. |\n| [`sync`](docs/tools/ai-config-kit.md#sync--commit--optionally-push) | `git add` + commit + optionally push, scoped to the content dir. |\n| [`track`](docs/tools/ai-config-kit.md#track--move-a-real-path-into-the-content-dir) | Move a real `~/.claude/` path into content + symlink back. |\n| [`status`](docs/tools/ai-config-kit.md#status--whats-tracked--git-state) | Tracked + untracked candidates + git state. |\n| [`doctor`](docs/tools/ai-config-kit.md#doctor--verify-symlink-health) | Verify every symlink resolves to a tracked source. `--heal` also runs the permission audit. |\n| [`heal`](docs/tools/ai-config-kit.md#heal-audit--fix-permissions-on-the-content-dir) | Audit + (with `--yes`) fix mode bits on the content dir. Never escalates privilege; orphan-owner findings are flagged but never fixed. |\n| [`capacity`](docs/tools/ai-config-kit.md#capacity-per-provider-overload-verdict-for-now-in-the-users-timezone) | Per-provider overload verdict (Anthropic, OpenAI, Codex, Google, Cohere, Mistral, local) computed against the user's local timezone using the bundled off-peak data. |\n| [`validate`](docs/tools/ai-config-kit.md#validate--pre-flight-check) | Pre-flight environment check (Python, git, writability). |\n| [`list`](docs/tools/ai-config-kit.md#list--grouped-view-of-content) | Grouped tree of content with size + count per group. |\n| [`view`](docs/tools/ai-config-kit.md#view--print-a-tracked-file) | Print a tracked file's contents (path-traversal-safe). |\n| [`cleanup`](docs/tools/ai-config-kit.md#cleanup--remove-noise) | Remove `.DS_Store`, broken symlinks, orphan backups. |\n| [`repair`](docs/tools/ai-config-kit.md#repair--heal-a-broken-install) | Cleanup + rebuild symlinks + restore protected backups. |\n| [`decisions`](docs/decisions.md) | List / show / apply bundled global-decision packs. |\n| [`fetch`](docs/tools/ai-config-kit.md#fetch--disk-to-disk-download) | Disk-to-disk download of a canonical / upstream text file. |\n\nEvery subcommand has `--help`. The full reference lives in\n[`docs/tools/ai-config-kit.md`](docs/tools/ai-config-kit.md).\n\n---\n\n## Decisions: bundled global rules\n\n`ai-config-kit` ships **decision packs**: opinionated bundles\nof `CLAUDE.md` fragments and slash commands that bake in proven\npatterns. Two are auto-applied on `init` (skip with `--no-decisions`):\n\n| Pack | What it ships |\n|---|---|\n| `script-generation-pattern` | Slash command + `CLAUDE.md` fragment that tells the model to use a generator script for many-file / content-filter-risky tasks. |\n| `fetch-canonical-pattern` | `/fetch-canonical` slash command + `CLAUDE.md` fragment for canonical-file downloads (license, code of conduct, etc.) that route URL → disk and never through the response stream. |\n\n```bash\nai-config-kit decisions list                # show all bundled packs\nai-config-kit decisions show \u003cname\u003e         # print pack details\nai-config-kit decisions apply \u003cname\u003e        # copy into content dir (non-clobbering)\n```\n\nFull guide and pack-authoring schema:\n[`docs/decisions.md`](docs/decisions.md).\n\n---\n\n## The `fetch` command + canonical-file pattern\n\nAsking Claude Code to add a `LICENSE`, `CODE_OF_CONDUCT.md`, or any\nother well-known upstream text often trips a content-filter policy\nblock. The model's file-write tool streams the body through the\nresponse, and the filter watches that stream.\n\n`ai-config-kit fetch` routes the bytes URL → disk via Python's\nstdlib (`urllib.request`). The response only contains the metadata:\n\n```bash\nai-config-kit fetch https://example.com/license.txt ./LICENSE\n# path=…  bytes=11357  lines=202  sha256=…  status=created  first_line=Apache License\n```\n\nAtomic write, idempotent, HTTPS-only by default, size cap (1 MiB),\nUTF-8 validation, optional `--expect-sha256`. The bundled\n`fetch-canonical-pattern` decision pack teaches the model to use this\nverb (or `curl -o` as a fallback) automatically.\n\n---\n\n## Multi-machine setup\n\nPush the content dir to a private git repo from machine A, then on\nmachine B:\n\n```bash\npip install ai-config-kit\ngit clone git@github.com:you/my-claude-content.git ~/.config/claude-config/content\nai-config-kit bootstrap\n```\n\nThe on-disk path stays `~/.config/claude-config/` (not\n`ai-config-kit/`) so existing installs keep working. The\npackage name is what changed.\n\n---\n\n## Documentation\n\n| Doc | Covers |\n|---|---|\n| [`docs/installation.md`](docs/installation.md) | Install, requirements, CI setup, Windows note |\n| [`docs/configuration.md`](docs/configuration.md) | JSON config schema, env vars, secret patterns, host overlays |\n| [`docs/architecture.md`](docs/architecture.md) | Symlink design, content-dir layout, classification table |\n| [`docs/tools/ai-config-kit.md`](docs/tools/ai-config-kit.md) | Per-subcommand reference with all flags |\n| [`docs/decisions.md`](docs/decisions.md) | Decision-pack catalogue + schema for authors |\n| [`docs/release.md`](docs/release.md) | Tag-driven release flow, OIDC trusted publishing |\n| [`docs/shipping-checklist.md`](docs/shipping-checklist.md) | One-time + ongoing release prep |\n| Installer (sibling repo) | `https://github.com/simtabi/get-installer`. Reusable cross-platform one-liner installer; was here at `installer/` through v0.2.0 |\n\n---\n\n## Project layout\n\n```\nai-config-kit/\n├── README.md                       you are here (the single authoritative readme)\n├── docs/                           subdocs (lowercase-kebab, linked from README)\n├── src/ai_config_kit/        the package\n│   ├── manager.py                  ClaudeConfig class + all report types\n│   ├── cli.py                      thin argparse wrapper\n│   ├── __init__.py                 public API\n│   └── resources/decisions/        bundled decision packs (ships in wheel)\n│       ├── core/\n│       ├── script-generation-pattern/\n│       └── fetch-canonical-pattern/\n├── tests/                          pytest suite (manager + CLI)\n├── pyproject.toml\n├── CHANGELOG.md\n├── CONTRIBUTING.md\n├── SECURITY.md\n├── CODE_OF_CONDUCT.md\n└── LICENSE\n```\n\nPer-pack details live next to each pack as `details.md` (shown by\n`ai-config-kit decisions show \u003cname\u003e`). No per-pack README.md\nfiles to disambiguate from this one.\n\n---\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md). Quality gates: `pytest`,\n`ruff check`, `mypy --strict`. All four pass on PR; CI runs them on\nmacOS + Ubuntu × Python 3.10–3.13.\n\n---\n\n## License\n\nMIT. See [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimtabi%2Fai-config-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimtabi%2Fai-config-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimtabi%2Fai-config-kit/lists"}