{"id":45907242,"url":"https://github.com/lucenx9/agentinit","last_synced_at":"2026-03-12T20:59:46.396Z","repository":{"id":341034272,"uuid":"1168641654","full_name":"Lucenx9/agentinit","owner":"Lucenx9","description":"Tiny router-first context files for AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor)","archived":false,"fork":false,"pushed_at":"2026-03-03T14:46:53.000Z","size":2587,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-03T18:59:37.026Z","etag":null,"topics":["ai-agents","claude-code","cli","codex","codex-cli","coding-agents","context","cursor-ai","developer-tools","gemini-cli","github-copilot","markdown","project-setup","python","scaffolding"],"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/Lucenx9.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":"2026-02-27T16:19:25.000Z","updated_at":"2026-03-03T14:46:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Lucenx9/agentinit","commit_stats":null,"previous_names":["lucenx9/agentinit"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/Lucenx9/agentinit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lucenx9%2Fagentinit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lucenx9%2Fagentinit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lucenx9%2Fagentinit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lucenx9%2Fagentinit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Lucenx9","download_url":"https://codeload.github.com/Lucenx9/agentinit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lucenx9%2Fagentinit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30086511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T15:40:14.053Z","status":"ssl_error","status_checked_at":"2026-03-04T15:40:13.655Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-agents","claude-code","cli","codex","codex-cli","coding-agents","context","cursor-ai","developer-tools","gemini-cli","github-copilot","markdown","project-setup","python","scaffolding"],"created_at":"2026-02-28T03:57:16.615Z","updated_at":"2026-03-12T20:59:46.390Z","avatar_url":"https://github.com/Lucenx9.png","language":"Python","readme":"# agentinit\n\nScaffold and maintain context files for AI coding agents.\n\n![CI](https://github.com/Lucenx9/agentinit/actions/workflows/ci.yml/badge.svg)\n[![PyPI](https://img.shields.io/pypi/v/agentinit.svg)](https://pypi.org/project/agentinit/)\n[![Python 3.10+](https://img.shields.io/pypi/pyversions/agentinit.svg)](https://pypi.org/project/agentinit/)\n\n\u003cimg src=\"https://raw.githubusercontent.com/Lucenx9/agentinit/main/assets/preview.png\" width=\"900\" alt=\"agentinit preview\" /\u003e\n\n`agentinit` generates a structured set of context files that modern AI coding assistants (Claude Code, Cursor, GitHub Copilot, Gemini CLI) read automatically. It uses a **router-first architecture**: you write your project rules once in `AGENTS.md`, and agentinit keeps the vendor-specific files in sync.\n\nNo runtime dependencies. Pure Python standard library. Works on Linux, macOS, and Windows.\n\n## Why agentinit\n\nAI coding agents perform better when they have clear, structured context about your project. Without it, they guess at your stack, conventions, and constraints.\n\n**agentinit solves this by:**\n\n- **One source of truth** -- Write project rules in `AGENTS.md`. Vendor files (`CLAUDE.md`, `GEMINI.md`, `.cursor/rules/`, `.github/copilot-instructions.md`) are generated routers that import it.\n- **Low-drift workflow** -- `sync --check` and `status --check` detect when files fall out of date. Run them in CI to catch drift early.\n- **Lean context model** -- Keep always-loaded files short (under 300 lines). Push details into `docs/` where agents load them on demand.\n- **Deterministic output** -- No LLM calls, no network requests. Every command produces the same output from the same input.\n\n## Installation\n\nRequires Python 3.10 or later.\n\n```sh\n# With pipx (recommended, installs in an isolated environment)\npipx install agentinit\n\n# With pip\npip install agentinit\n\n# Verify\nagentinit --version\n```\n\n## Quick start\n\n### Add context files to an existing project\n\n```sh\ncd your-project\nagentinit init\n```\n\nThis creates the full set of context files:\n\n```text\nyour-project/\n├── AGENTS.md                          # Primary agent instructions (source of truth)\n├── CLAUDE.md                          # Claude Code router → imports AGENTS.md\n├── GEMINI.md                          # Gemini CLI router → imports AGENTS.md\n├── llms.txt                           # Project discovery index\n├── .claude/rules/                     # Claude Code modular rules\n│   ├── coding-style.md\n│   ├── testing.md\n│   └── repo-map.md\n├── .cursor/rules/project.mdc          # Cursor rule routing\n├── .github/copilot-instructions.md    # GitHub Copilot context\n├── .contextlintrc.json                # Lint configuration\n└── docs/\n    ├── PROJECT.md                     # Stack, commands, layout, constraints\n    ├── CONVENTIONS.md                 # Style, naming, testing, git workflow\n    ├── TODO.md                        # Task tracking for agents\n    ├── DECISIONS.md                   # Architecture decision records\n    └── STATE.md                       # Session handoff notes\n```\n\n### Minimal mode\n\nFor smaller projects, generate only the essential files:\n\n```sh\nagentinit init --minimal\n```\n\n```text\nyour-project/\n├── AGENTS.md\n├── CLAUDE.md\n├── llms.txt\n└── docs/\n    ├── PROJECT.md\n    └── CONVENTIONS.md\n```\n\n### After scaffolding\n\n1. Open `docs/PROJECT.md` and describe your project, stack, and commands.\n2. Fill in `docs/CONVENTIONS.md` with your team's standards.\n3. Run your coding agent -- it reads `AGENTS.md` (or its vendor-specific router) automatically.\n\nTrack the generated files in git so your agents can find them:\n\n```sh\ngit add AGENTS.md CLAUDE.md GEMINI.md llms.txt docs/\n```\n\n## How it works\n\nagentinit uses a **router-first** design. Each AI tool has its own context file format, but the content should be consistent. Instead of maintaining multiple files manually, agentinit generates thin router files that all point back to `AGENTS.md`:\n\n```text\nAGENTS.md            ← You edit this (source of truth)\n  ├── CLAUDE.md      ← @AGENTS.md  (auto-generated router)\n  ├── GEMINI.md      ← @AGENTS.md  (auto-generated router)\n  ├── .cursor/rules/ ← @AGENTS.md  (auto-generated router)\n  └── .github/copilot-instructions.md  (auto-generated router)\n```\n\nWhen you run `agentinit sync`, it regenerates the router files from templates. When you run `agentinit sync --check`, it exits with code 1 if any router has drifted from the template -- useful in CI to prevent silent staleness.\n\nThe `docs/` directory holds detailed project context that agents load on demand. This keeps the always-loaded router files short and focused.\n\n## Commands\n\n### Scaffolding\n\n| Command | Description |\n| --- | --- |\n| `agentinit init` | Add missing context files to the current directory |\n| `agentinit init --minimal` | Generate only the minimal file set |\n| `agentinit minimal` | Shortcut for `init --minimal` |\n| `agentinit new \u003cname\u003e` | Create a new project directory and scaffold context files |\n| `agentinit remove` | Delete agentinit-managed files (with confirmation) |\n\nCommon flags for `init`, `minimal`, and `new`:\n\n| Flag | Effect |\n| --- | --- |\n| `--detect` | Auto-detect stack and commands from `pyproject.toml`, `package.json`, `Cargo.toml`, or `go.mod` |\n| `--purpose \"...\"` | Set the project purpose non-interactively |\n| `--prompt` | Run the interactive setup wizard (default on TTY) |\n| `--translate-purpose` | Translate non-English purpose text to English for `docs/` files |\n| `--skeleton fastapi` | Copy a starter project boilerplate after scaffolding |\n| `--force` / `--yes` / `-y` | Overwrite existing files without confirmation |\n\n### Maintenance\n\n| Command | Description |\n| --- | --- |\n| `agentinit sync` | Regenerate vendor router files from templates |\n| `agentinit sync --check` | Exit 1 if routers have drifted (CI mode) |\n| `agentinit sync --diff` | Show unified diff for out-of-sync routers |\n| `agentinit refresh-llms` | Regenerate `llms.txt` from project files |\n| `agentinit add \u003ctype\u003e \u003cname\u003e` | Install a modular resource (see below) |\n| `agentinit remove --archive` | Move managed files to `.agentinit-archive/` instead of deleting |\n\n### Validation\n\n| Command | Description |\n| --- | --- |\n| `agentinit status` | Show missing files, incomplete content, and line budget warnings |\n| `agentinit status --check` | Exit 1 if any issues found (CI mode) |\n| `agentinit lint` | Run contextlint checks (broken refs, bloat, duplication) |\n| `agentinit doctor` | Run all checks and suggest fix commands |\n\n### Modular resources (`add`)\n\nAdd reusable agent instructions to your project:\n\n```sh\n# List available resources of a type\nagentinit add skill --list\n\n# Install a skill (copies to .agents/skills/ or .claude/skills/)\nagentinit add skill code-reviewer\nagentinit add skill testing\nagentinit add skill frontend-reviewer\n\n# Install MCP integration guides (copies to .agents/)\nagentinit add mcp github\nagentinit add mcp postgres\n\n# Install security guardrails\nagentinit add security\n\n# Install agent personality definition\nagentinit add soul\n```\n\nEach `add` command also appends a reference to the resource in `AGENTS.md`.\n\n## CI integration\n\nAdd these checks to your CI pipeline to catch documentation drift:\n\n```yaml\n# .github/workflows/ci.yml\n- name: Check agent context\n  run: |\n    pip install agentinit\n    agentinit sync --check    # Fail if router files drifted from templates\n    agentinit status --check  # Fail if files are missing or incomplete\n    agentinit lint            # Fail on broken refs, bloat, or duplication\n```\n\nFor minimal-profile projects, `sync --check` and `status --check` auto-detect the profile. You can also force it with `--minimal`.\n\n## Supported tools\n\n| Tool | Generated file | How it works |\n| --- | --- | --- |\n| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `CLAUDE.md` | Router that `@`-imports `AGENTS.md` and `docs/` files |\n| [Cursor](https://cursor.com) | `.cursor/rules/project.mdc` | Project-level rules pointing to `AGENTS.md` |\n| [GitHub Copilot](https://github.com/features/copilot) | `.github/copilot-instructions.md` | Repository-level instructions referencing `AGENTS.md` |\n| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `GEMINI.md` | Router that imports `AGENTS.md` and `docs/` files |\n| [llms.txt](https://llmstxt.org/) | `llms.txt` | Standard discovery index with project summary and key files |\n\n## Development\n\n```sh\npython3 -m venv .venv\n. .venv/bin/activate\npip install -e . --group dev\n\n# Run tests\npython3 -m pytest tests/ -v\n\n# Lint and format check\npython3 -m ruff check agentinit tests cli\npython3 -m ruff format --check agentinit tests cli\n```\n\nOn distro-managed Python installs that enforce PEP 668, use a virtual environment instead of the system interpreter.\n\n## Documentation\n\n- [Changelog](CHANGELOG.md)\n- [Wiki](https://github.com/Lucenx9/agentinit/wiki) -- detailed guides, workflows, architecture, and FAQ\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucenx9%2Fagentinit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucenx9%2Fagentinit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucenx9%2Fagentinit/lists"}