agntmd

Prepare your repositories for AI coding assistants

agntmd is a CLI tool that generates AI coding assistant instruction files (AGENTS.md) for repositories. It analyzes your codebase, detects the tech stack, and creates comprehensive instructions. AGENTS.md is natively supported by GitHub Copilot, Cursor, and OpenCode. For tools without native support, agntmd generates lightweight configuration files that reference AGENTS.md.

How It Works

agntmd uses a template layering system to build instructions:

┌─────────────────────────────────────────────┐
│  Base Template (AGENTS.base.md)            │  ← Generic guidelines
│  - Role & communication style              │
│  - Development process                     │
│  - Code quality standards                  │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  Org Template (e.g., org/example.md)       │  ← Organization-specific
│  - Internal tooling configuration          │
│  - Org conventions & policies              │
│  - Shared infrastructure context           │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  Platform Template (e.g., typescript.md)   │  ← Tech stack specifics
│  - Language best practices                 │
│  - Framework patterns                      │
│  - Testing requirements                    │
│  - Build commands                          │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  Repository Analysis (Copilot SDK)         │  ← Repo-specific details
│  - Project overview                        │
│  - Actual tech stack                       │
│  - Project structure                       │
│  - Quick commands                          │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  Custom Instructions (optional)            │  ← Team customizations
│  - .agntmd/custom-instructions.md          │
└─────────────────────────────────────────────┘
                    ↓
    ┌───────────────────────────┐
    │      AGENTS.md            │  ← Final output
    └───────────────────────────┘

Installation

From npm (recommended):

npm install -g agntmd
# or
npx agntmd run .

From source:

git clone https://github.com/bhaskarmelkani/agntmd.git
cd agntmd
pnpm install
pnpm build
pnpm link

Then from any repository:

agntmd run .

Quick Start

Zero-Setup (no GitHub token needed)

# Generate base configuration only — no AI analysis, no token required
agntmd run . --base-only

Full Analysis

# Run in current directory (requires GITHUB_TOKEN for Copilot SDK analysis)
agntmd run .

# With organization template
agntmd run . --org mycompany

# Run on remote GitHub repo
agntmd run owner/my-repo

# Force regeneration (skip change detection)
agntmd run . --force

# Preview without writing files
agntmd run . --dry-run

Check Readiness

# Assess AI readiness maturity
agntmd check .

# JSON output
agntmd check . --json

Commands Reference

agntmd run [repo]

Generate AI instruction files for a repository.

Arguments:

• [repo] - Repository to process (default: current directory .)
  • Local path: ./my-repo, /absolute/path, ~/projects/repo
  • Remote GitHub: owner/repo (requires GITHUB_TOKEN)

Options:

• --base-only - Skip repository analysis, output standard base config only (no token required)
• --org <name> - Organization template to use. Templates are in templates/org/
• --create-pr - Create draft PR with generated files (remote repos only)
• --dry-run - Preview changes without writing files
• --verbose - Show detailed log
• --force - Force regeneration even if no changes detected
• --model <name> - LLM model to use for analysis (default: claude-sonnet-4.5)

Environment Variables:

• GITHUB_TOKEN - Required for Copilot SDK analysis and remote repos. Not required with --base-only.
• AGNTMD_MODEL - LLM model to use for Copilot SDK analysis (default: claude-sonnet-4.5). Overridden by --model flag.
• DEFAULT_ORG - Default org template name (e.g. mycompany). Overridden by --org flag.

agntmd check [repo]

Assess the AI readiness maturity of a repository.

Arguments:

• [repo] - Repository to check (default: current directory .)

Options:

• --json - Output as JSON

Maturity Levels:

• Not Ready (0-29): Missing or broken AGENTS.md
• Basic (30-69): Base template only
• Enhanced (70-100): Full repo-specific analysis

Generated Files

agntmd creates the following files in your repository:

| File | Purpose | AI Tool | |------|---------|---------| | AGENTS.md | Main instruction file | GitHub Copilot, Cursor, OpenCode (native support) | | .gemini/settings.json | Configuration pointing to AGENTS.md | Gemini Code Assist | | .claude/CLAUDE.md | Symlink to AGENTS.md | Claude Code |

Note: Most AI tools now natively support AGENTS.md at the repository root. agntmd only generates additional configuration files for tools that need explicit setup (Gemini, Claude Code).

Customization

Add repository-specific instructions by creating:

.agntmd/custom-instructions.md

These will be merged into the generated AGENTS.md file. Perfect for:

• Project-specific pain points
• Team conventions not in base templates
• Module-specific guidelines
• Known issues and workarounds

Example:

## Custom Project Guidelines

### Database
- Always use transactions for multi-table updates
- Run migrations in this order: schema → data → permissions

### API
- All endpoints must have rate limiting configured
- Document breaking changes in CHANGELOG.md

Supported Platforms

agntmd automatically detects your platform and applies the appropriate template:

| Platform | Detection | Template | |----------|-----------|----------| | Android (Kotlin) | build.gradle, settings.gradle.kts | android.md | | iOS (Swift) | Package.swift, .xcodeproj | ios.md | | Backend JVM | build.gradle.kts, Java/Kotlin | backend-jvm.md | | TypeScript/Node.js | package.json + TypeScript | typescript.md | | Web (React/Next.js) | package.json + React/Next | web.md | | Python FastAPI | pyproject.toml + FastAPI | python-fastapi.md | | Python Flask | pyproject.toml + Flask | python-flask.md |

Template Structure

agntmd includes four layers of templates:

1. Base Template (templates/base/AGENTS.base.md)

Generic guidelines for all repositories:

• Role & communication style (plan first, then implement)
• Development process
• Code quality standards
• PR/commit conventions

2. Org Templates (templates/org/*.md)

Organization-specific guidelines (selected via --org):

• Internal tooling configuration
• Org-wide conventions and policies
• Shared infrastructure context

See templates/org/example.md for the template format.

3. Platform Templates (templates/platforms/*.md)

Tech stack-specific guidelines:

• Language best practices
• Framework patterns
• Architecture requirements
• Testing strategies
• Build/run commands

Change Detection

agntmd tracks state in .agntmd/state.json and automatically regenerates when:

1. Repository changes - New commits detected
2. Custom instructions change - .agntmd/custom-instructions.md modified
3. Templates change - Base, org, or platform templates updated
4. agntmd version change - Package upgraded

Use --force to regenerate regardless of changes.

Development

Building

pnpm install
pnpm build

Testing

# Run on test fixtures
pnpm dev run ./test-fixtures/backend-jvm --force

# Run type checking
pnpm type-check

# Run tests
pnpm test

Project Structure

agntmd/
├── src/
│   ├── cli/              # Command definitions
│   ├── templates/        # Template loading & merging
│   ├── generators/       # File generation logic
│   ├── copilot/          # Copilot SDK integration
│   ├── tools/            # Platform detection, file ops
│   ├── state/            # State management & change detection
│   ├── maturity/         # AI readiness scoring
│   ├── custom/           # Custom instructions support
│   └── utils/            # Config, logging, GitHub API
├── templates/
│   ├── base/             # Base template (all repos)
│   ├── org/              # Organization templates (--org)
│   └── platforms/        # Platform-specific templates
├── test-fixtures/        # Sample repositories for testing
└── dist/                 # Compiled output (gitignored)

Adding New Platform Templates

1. Create templates/platforms/{platform}.md with platform-specific guidelines
2. Add detection logic to src/tools/detect-platform.ts
3. Test with a sample repository
4. Update this README's "Supported Platforms" table

Contributing

See CONTRIBUTING.md for guidelines on contributing templates and features.

License

MIT — See LICENSE for details.

Links

• GitHub
• Issues
• npm
• Changelog