agentinit 0.3.1

Scaffold agent context files into a project.

agentinit

Scaffold tiny, router-first context files so your AI coding agents stop guessing your project setup, style rules, and test commands.

Pure Python standard library. No runtime dependencies. Does not touch your source code. Generates router files for Claude Code, Codex, Cursor, Copilot, and Gemini CLI.

🚀 Start in 60 seconds

# 1. Install via pipx (recommended)
pipx install agentinit

# 2. Add minimal agent context to your project
cd your-project
agentinit init --minimal

What it does

Instead of giant, token-heavy instruction files for every tool, agentinit creates a router-first structure. Top-level files stay tiny and only point to AGENTS.md, which links to docs/*.

your-project/
├── AGENTS.md              # The central hub for all agents
├── CLAUDE.md              # Claude Code router
└── docs/
    ├── PROJECT.md         # What this project is (you fill this)
    └── CONVENTIONS.md     # How to work in it (you fill this)

Next steps: Open docs/PROJECT.md and docs/CONVENTIONS.md and fill them in.

Next session: Tell your agent: "follow the router for your tool (CLAUDE.md / GEMINI.md / etc) → AGENTS.md"

---

🛠️ Add extras (Skills, MCP, Personality)

Agents can do more than just read conventions. You can inject modular resources directly into your project. Resources are written under .agents/ and linked from AGENTS.md automatically.

# View available resources
agentinit add --list

# Add specific capabilities
agentinit add skill code-reviewer
agentinit add mcp github
agentinit add security
agentinit add soul "YourAgentName"

(Replace "YourAgentName" with any name you want for your agent persona.)

This creates modular files and automatically links them in your AGENTS.md:

your-project/
├── .agents/
│   ├── security.md
│   ├── soul.md
│   ├── mcp-github.md
│   └── skills/
│       └── code-reviewer/
│           └── SKILL.md
└── AGENTS.md              # Automatically updated!

(Adding resources is safe: it skips existing files to avoid duplicates. Use --force to overwrite.)

---

🚦 Keep your context clean (Status & CI)

Token limits matter. agentinit includes a status checker and linter to prevent context bloat, broken links, and missing information.

# View line budgets, broken references, and missing details
agentinit status

Example output:
! docs/CONVENTIONS.md (201 lines >= 200)
x Broken reference: docs/missing-file.md

# Perfect for CI (exits non-zero on hard violations)
agentinit status --check

---

🤖 AI Prompt: Fill the docs fast

Don't want to write PROJECT.md and CONVENTIONS.md yourself? After running agentinit init, paste this prompt to your favorite AI agent:

Read the entire repository. Fill in docs/PROJECT.md and docs/CONVENTIONS.md using only facts found in the repo (package files, configs, source code, CI). Do not invent commands. If information is missing, write TODO: <what's needed>. Do not modify any other files.

Review the result, fix the TODOs, and commit!

---

📚 Advanced Usage & Commands

Core Commands

• agentinit new <project> — Create a new directory and scaffold files.
• agentinit init — Add missing files to an existing directory.
• agentinit minimal — Shortcut for init --minimal.
• agentinit add <type> <name> — Add modular resources (skills, mcp, security, soul).
• agentinit status — Check health, line budgets, and broken links.
• agentinit lint — Run contextlint to find duplicate text across files.
• agentinit remove — Safely remove or archive agent files.

Common Flags (init / new / minimal)

• --yes or -y — Runs non-interactively / skips the wizard (use --force to overwrite agentinit-managed files).
• --minimal — Create only the 4 core files (AGENTS.md, CLAUDE.md, and docs).
• --detect — Auto-detect stack and commands from package files (e.g., package.json, pyproject.toml).
• --purpose "<text>" — Prefill the project purpose non-interactively.

Linting Options

# Human-readable output
agentinit lint

# Machine-readable JSON for CI
agentinit lint --format json

Removing Files

agentinit remove --dry-run    # Preview what will happen
agentinit remove              # Remove with confirmation
agentinit remove --archive    # Move to .agentinit-archive/ instead of deleting

💡 Why Router-First?

• Saves Tokens: Re-typing 400 tokens per session across 20 sessions/month wastes 8k+ tokens.
• Single Source of Truth: Update a convention once in docs/, and Cursor, Copilot, and Claude all see it.
• Prevents Hallucinations: Agents stop guessing your test command or trying to use the wrong linting tool.
• Faster Onboarding: Human developers benefit from reading PROJECT.md just as much as the AI does.

⚙️ Installation & Development

Requires Python 3.10+.

# Install (pipx is recommended for CLI apps)
pipx install agentinit

# Update
pipx upgrade agentinit

# Install without pipx
pip install agentinit

Color Output

Colored output is enabled on terminals. It disables automatically in CI or when piping. Force disable it with:

NO_COLOR=1 agentinit init

Development

pip install -e . --group dev
python3 -m pytest tests/ -v

License

MIT