✨ MagicAgentHelix CLI ✨

A powerful CLI tool that inspects your project and generates granular, path-specific AI instructions for agents like GitHub Copilot.

🚀 Quick Start

# Install globally
npm install -g @el-j/magic-agent-helix

# Or use with npx (no installation required)
npx @el-j/magic-agent-helix run

📦 Installation

Global Installation

npm install -g @el-j/magic-agent-helix

Project-Specific Installation

npm install --save-dev @el-j/magic-agent-helix

Then add to your package.json scripts:

{
  "scripts": {
    "align": "magic-helix run"
  }
}

🎯 Commands

run - Generate Instruction Files

Scans your project and generates AI instruction files based on detected technologies.

magic-helix run [options]

Options:

• --dry-run - Preview what would be generated without writing files
• --force - Overwrite files and prune without prompting
• --skip-pruning - Don't ask to remove old files
• --output-dir <path> - Custom output directory (default: .github/instructions)
• --config <path> - Path to custom config file
• --verbose - Show detailed output
• --quiet - Show minimal output
• --project <name> - Target a specific project only

Examples:

# Basic usage
magic-helix run

# Dry run to see what would be generated
magic-helix run --dry-run

# Generate for specific project only
magic-helix run --project my-app

# Use custom output directory
magic-helix run --output-dir .ai/instructions

# Quiet mode with force overwrite
magic-helix run --quiet --force

refresh (alias: resync) - Update Instruction Files

Rescans your project and updates existing instruction files with new information.

magic-helix refresh [options]

Options:

• --config <path> - Path to custom config file
• --verbose - Show detailed output
• --quiet - Show minimal output
• --project <name> - Target a specific project only

Examples:

# Refresh all instruction files
magic-helix refresh

# Refresh specific project
magic-helix refresh --project my-app

list - Show Project Information

Lists detected projects, tags, and templates without generating files.

magic-helix list

Example Output:

📦 my-app
   Path: packages/my-app
   Tags: framework-vue, style-tailwind, test-vitest, lang-typescript
   Would generate: my-app.vue-core.md, my-app.style-tailwind.md, ...

validate - Check Instruction Files

Validates instruction files for common issues and integrity.

magic-helix validate

Checks performed:

• Frontmatter presence and structure
• Required applyTo field
• Content after frontmatter
• Glob pattern validity

clean - Remove Generated Files

Removes all generated instruction files with confirmation.

magic-helix clean

init - Initialize Custom Configuration

Creates a minimal configuration file for extending built-in rules.

magic-helix init

Creates:

• magic-helix.config.json - Configuration file (legacy: ai-aligner.config.json still supported)
• ai_templates/ - Directory for custom templates

⚙️ Configuration

Built-in Detection

MagicAgentHelix automatically detects:

Frameworks:

• Vue.js, React, Angular, NestJS

Styling:

• Tailwind CSS, PrimeVue, Material-UI, Quasar

Testing:

• Vitest, Jest, Cypress, Playwright

State Management:

• RxJS, Pinia, Redux, Zustand

Languages:

• TypeScript, JavaScript, Go, Python

Custom Configuration

Create magic-helix.config.json to extend or override:

{
  "target": "github-copilot",
  "templateDirectory": "ai_templates",
  "outputDirectory": ".github/instructions",
  "dependencyTagMap": {
    "my-internal-package": "domain-my-rules"
  },
  "configFileTagMap": {
    "my-custom-config.json": "domain-my-rules"
  },
  "fileGlobTagMap": {
    "src/specific-folder/**/*.ts": "domain-my-rules"
  },
  "tagTemplateMap": {
    "domain-my-rules": [
      { "template": "my-custom-rule.md", "suffix": "my-rule.md" }
    ]
  }
}

🎨 Custom Templates

1. Run magic-helix init to create the template directory
2. Add your custom .md files in ai_templates/
3. Reference them in your config's tagTemplateMap

Template format:

# My Custom Rule

- Follow this pattern
- Use this convention
- Avoid that anti-pattern

🔧 VS Code + GitHub Copilot Integration

Add to your .vscode/settings.json:

{
  "github.copilot.advanced": {
    "instructions": ".github/instructions"
  }
}

This ensures Copilot always reads your instruction files. Restart VS Code after adding.

📊 Generated File Format

Generated instruction files include frontmatter with precise file targeting:

---
# Auto-generated by ai-aligner for: my-app
# Source Template: vue/vue-core.md
# Generated: 2025-10-27T10:30:00.000Z
applyTo: "packages/my-app/src/**/*.{vue}"
---

# Vue 3 Composition API Guidelines

- Use `<script setup>` syntax
- Prefer Composition API over Options API
...

🚀 CI/CD Integration

GitHub Actions

name: Update AI Instructions

on:
  push:
    branches: [main]

jobs:
  update-instructions:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npx @el-j/magic-agent-helix run --force
      - uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: "chore: update AI instructions"
          file_pattern: ".github/instructions/*.md"

📚 Examples

Monorepo with Multiple Frameworks

# List all detected projects
magic-helix list

# Generate instructions for all projects
magic-helix run

# Update just the frontend project
magic-helix refresh --project my-frontend

Single Project

# Generate instructions
magic-helix run

# Validate they're correct
magic-helix validate

# Clean up if needed
magic-helix clean

🛠️ Troubleshooting

No files generated?

Run magic-helix list to see if your project is detected and what tags are found.

Wrong file extensions in applyTo?

The CLI now automatically detects the right extensions based on your project's technologies.

Need to regenerate everything?

magic-helix clean
magic-helix run

📖 More Information

See the monorepo root README.md for full development and testing instructions.

📄 License

MIT