ai-agent-init

A small Node.js CLI to scaffold a clean AI agent context architecture in any project. It creates the files that AI coding agents (Claude Code, OpenAI Codex, Aider, Cursor, ...) need to collaborate safely with humans on your codebase.

Zero runtime dependencies. Works on Windows, macOS and Linux.

Why this project exists

AI coding agents work best when the project tells them:

• what the project is,
• which stack and commands to use,
• which rules to follow,
• which areas require human approval (auth, payments, deployment),
• which files they must never read or modify (.env, secrets, keys).

Most teams end up rebuilding the same AGENTS.md, CLAUDE.md, rules and permissions in every repository. ai-agent-init does it for you in a predictable, conservative way.

Install

Use without installing:

npx ai-agent-init

Install globally:

npm install -g ai-agent-init
ai-init

Usage

Run inside the project you want to bootstrap:

ai-init                 # generate context files (skip existing)
ai-init --dry-run       # show what would be written, do not touch the FS
ai-init --force         # overwrite existing managed files
ai-init --global        # also create ~/.codex/AGENTS.md and ~/.claude/CLAUDE.md
ai-init --launch        # try to launch VS Code, Codex CLI, Claude CLI
ai-init --global --launch
ai-init --help

Files generated

In the current project (existing files are skipped unless --force):

AGENTS.md
CLAUDE.md
.claude/settings.json
.claude/rules/coding.md
.claude/rules/testing.md
.claude/rules/security.md
.claude/skills/project-bootstrap-audit/SKILL.md
.claude/commands/init-ai-context.md
docs/ai-workflow.md
docs/architecture.md
docs/decisions.md
.gitignore                    # only missing lines are appended

With --global:

~/.codex/AGENTS.md
~/.claude/CLAUDE.md

Role of each file

• AGENTS.md — tool-agnostic source of truth. Read first by any agent.
• CLAUDE.md — Claude Code entry point. Imports AGENTS.md via @AGENTS.md and adds Claude-specific rules.
• .claude/settings.json — denies reads/edits of .env, secrets, .pem and .key files.
• .claude/rules/*.md — coding, testing and security rules.
• .claude/skills/project-bootstrap-audit/SKILL.md — reusable Claude skill to audit and improve the agent setup of a project.
• .claude/commands/init-ai-context.md — slash command with an audit checklist.
• docs/ai-workflow.md — human ↔ agent workflow, approval boundaries.
• docs/architecture.md — architecture skeleton.
• docs/decisions.md — lightweight ADR log.

CLI options

| Flag | Purpose | | -------------- | --------------------------------------------------------------------- | | --dry-run | Print what would change. Does not touch the filesystem. | | --force | Overwrite existing files managed by this CLI. | | --global | Also create ~/.codex/AGENTS.md and ~/.claude/CLAUDE.md. | | --launch | Try to launch VS Code, Codex CLI, Claude CLI. Failures are non-fatal. | | -h, --help | Show usage and exit. |

Windows behavior

• Works in cmd.exe, PowerShell 5.1, PowerShell 7+, Windows Terminal and Git Bash.
• npm install -g automatically generates ai-init.cmd (cmd) and ai-init.ps1 (PowerShell).
• --launch uses child_process.spawn with shell: true, which resolves .cmd shims on Windows. If a tool is missing, the CLI prints a clear message and continues — it never crashes.

See docs/windows.md for details.

Safety

• Existing files are never overwritten without --force.
• .gitignore is updated, not rewritten — only missing lines are appended.
• The CLI never reads or prints secrets, never commits, never publishes, never installs dependencies.

See docs/safety.md.

Example workflow

cd my-project
npx ai-agent-init           # scaffold the AI context
git add AGENTS.md CLAUDE.md .claude docs .gitignore
git commit -m "Add AI agent context"
# Open the project in your agent of choice
claude    # or: codex, code .

Then, inside Claude Code, run the slash command:

/init-ai-context

to get an audit of the agent setup.

Local development

git clone <this-repo>
cd ai-agent-init
npm test                  # smoke test in a temp directory
npm run test:dry          # dry-run the CLI in the current directory
npm install -g .          # install globally from local source
ai-init --dry-run         # try the global command

Documentation

• docs/how-it-works.md — internals.
• docs/generated-files.md — full reference of generated files.
• docs/windows.md — Windows specifics.
• docs/safety.md — safety model.

Contributing

Issues and pull requests are welcome. Please:

• Keep changes small and focused.
• Avoid adding runtime dependencies.
• Update or add tests when behavior changes.
• Update the docs when new files are generated.

License

MIT — see LICENSE.