✨ MagicAgentHelix CLI ✨

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

🚀 Quick Start

``bash


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

$3

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

$3

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

Then add to your package.json scripts:
`json
{
"scripts": {
"align": "magic-helix run"
}
}
`

🎯 Commands

$3

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

`bash
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 - Custom output directory (default: .github/instructions)
- --config - Path to custom config file
- --verbose - Show detailed output
- --quiet - Show minimal output
- --project - Target a specific project only

Examples:
`bash


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
`

$3

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

`bash
magic-helix refresh [options]
`

Options:
- --config - Path to custom config file
- --verbose - Show detailed output
- --quiet - Show minimal output
- --project - Target a specific project only

Examples:
`bash


Refresh all instruction files

magic-helix refresh

Refresh specific project

magic-helix refresh --project my-app
`

$3

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

`bash
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, ...
`

$3

Validates instruction files for common issues and integrity.

`bash
magic-helix validate
`

Checks performed:
- Frontmatter presence and structure
- Required applyTo field
- Content after frontmatter
- Glob pattern validity

$3

Removes all generated instruction files with confirmation.

`bash
magic-helix clean
`

$3

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

`bash
magic-helix init
`

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

⚙️ Configuration

$3

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

$3

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

`json
{
"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:
`markdown


My Custom Rule

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

🔧 VS Code + GitHub Copilot Integration

Add to your .vscode/settings.json:

`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:

`markdown
---


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