Alloy CLI Frontend

Alloy CLI Frontend is a command-line tool that installs a GitHub Copilot agent (@alloy) and scans your project's type definitions to build a model registry. The Copilot agent generates frontend components following Atomic Design patterns directly from VS Code Copilot Chat using natural language.

Table of Contents

• Prerequisites
• Quick Start
• Commands
  • Init
  • Scan
• Version Differences (v1 vs v2)
• Copilot Agent & Skills
  • What You Get
  • Using @alloy in Copilot Chat
  • Included Skills
• Contributing
• License

Prerequisites

• Node.js ≥ 20
• VS Code with GitHub Copilot Chat enabled
• A TypeScript/React project using Atomic Design conventions

Quick Start

# 1. Install the Copilot agent and skills
npx alloy-cli-frontend init

# 2. Scan your type definitions to build the model registry
npx alloy-cli-frontend scan

# 3. Restart VS Code, open Copilot Chat, and start generating
#    @alloy Create an atom Button with label, onClick, and disabled. Prefix: acme

Commands

The tool is designed to be run via npx in your project root — no global install needed. This keeps the agent and skills in sync with your project.

Init

Installs the Copilot agent and skills into your project. This copies the .github/agents/, .github/skills/, and .github/instructions/ files that power the @alloy Copilot Chat agent.

npx alloy-cli-frontend init

You'll be guided through two interactive prompts:

1. Template version — choose v1 or v2 (see Version Differences)
2. Categories to install — select which file groups to copy:

| Category | Description | |----------|-------------| | Alloy Agent | The @alloy orchestrator agent | | Generation Skills | Atom, molecule, organism, and page generators | | Template Skills | Blueprints for component, style, state, type, data, page, and template files | | Utility Skills | Model property resolution |

Existing files are skipped by default. Use --force to overwrite:

npx alloy-cli-frontend init --force

Scan

Scans your project's type definition files (src/_types/*.d.ts) and generates a model registry (.alloy-models.json) at the project root. The @alloy agent reads this registry to resolve property types instantly — instead of grepping through .d.ts files on every invocation.

npx alloy-cli-frontend scan

Your type definitions must extend BasedAtomicModel for the scanner to detect them. Both syntaxes are supported:

// v1 — interface syntax
interface ButtonModel extends BasedAtomicModel { /* ... */ }

// v2 — type alias syntax
type ButtonModel = BasedAtomicModel & { /* ... */ }

The scanner looks for three files — atoms.d.ts, molecules.d.ts, and organisms.d.ts — inside the type definitions directory and produces a categorized registry:

{
  "atoms": ["ButtonModel", "ImageModel"],
  "molecules": ["SearchBarModel"],
  "organisms": ["HeaderModel", "ProductCardModel"]
}

Options

| Option | Description | Default | |--------|-------------|---------| | -td, --type-directory <dir> | Type definitions directory (relative to src/) | _types |

Version Differences (v1 vs v2)

When running init you choose between two template versions. The core Atomic Design structure is the same; the differences are in file naming and import style:

| Aspect | v1 | v2 | |--------|----|----| | Component files | ComponentName.tsx, ComponentName.scss | index.tsx, index.scss | | Data files | componentNameCamelCase.ts | component-name-kebab-case.ts | | Type definitions | interface … extends BasedAtomicModel | type … = BasedAtomicModel & { } | | Imports | Explicit (import { Model } from '@_types/types') | Implicit (auto-import / no explicit path) |

Choose v2 for new projects. Use v1 if your existing codebase already follows v1 conventions.

Copilot Agent & Skills

Alloy CLI Frontend includes a GitHub Copilot agent that brings component generation directly into VS Code Copilot Chat. Describe what you want in natural language and the agent generates all the files for you.

What You Get

After running init, the following files are added to your project's .github/ directory:

| Category | Files | Purpose | |----------|-------|---------| | Agent | alloy.agent.md | Orchestrator that parses your request and delegates to skills | | Generation Skills | 4 skills | Generate atoms, molecules, organisms, and pages | | Template Skills | 8 skills | Embedded template blueprints for every file type | | Utility Skills | 1 skill | Smart property type resolution | | Instructions | copilot-instructions.md | Project-wide Atomic Design conventions for Copilot |

Restart VS Code (or reload the window) after running init to activate the agent.

Using @alloy in Copilot Chat

Open Copilot Chat in VS Code and mention @alloy to invoke the agent:

@alloy Create an organism called ProductCard with title, description, image, and price.
       Include style, state, script, and a page view with data.
       Prefix: xx

The agent will:

1. Parse your request — extract component type, name, prefix, optional files, and properties
2. Resolve property types — infer TypeScript types from property names (e.g., title → string, items → unknown[], onClick → () => void)
3. Confirm the plan — show you a summary of all files to be generated
4. Generate files — create every file using the correct Atomic Design conventions
5. Populate models — fill in the TypeScript interface with resolved properties

More Examples

@alloy Create an atom Button with label, onClick, disabled, and variant. Prefix: acme

@alloy Generate a molecule SearchBar with placeholder, onSearch, and isLoading. Include style and state. Prefix: xx

@alloy Create a page for an existing organism called HeroBanner

@alloy What files would an organism with a page view generate?

Included Skills

| Skill | Description | |-------|-------------| | generate-atom | Scaffolds an atom component with all optional files | | generate-molecule | Scaffolds a molecule component with all optional files | | generate-organism | Scaffolds an organism component with page, template, data, and all optional files | | generate-page | Creates a standalone page and template component | | tpl-component | Component .tsx file template | | tpl-template | Template wrapper .tsx file (works for all component types) | | tpl-page | Standard page file template | | tpl-page-story | Story collection page template | | tpl-data | Data/props file template | | tpl-state | State JSON file template | | tpl-style | SCSS style file template | | tpl-type | TypeScript interface/type definition template | | resolve-model-properties | Resolves property names into typed TypeScript interface fields |

Contributing

Contributions are welcome! To get started:

1. Fork the repository
2. Clone your fork and install dependencies:

   bun install

3. Run the CLI locally:

   bun run cli -- <command>

4. Run tests:

   bun run test

5. Create a feature branch, commit your changes, and open a pull request

License

This project is licensed under the MIT License. See the LICENSE file for details.