Skip to main content

Getting Started

This guide walks you through installing Agloom and running your first transpilation. By the end, you will have a working .agloom/ directory and generated config files for your AI coding tool.

Prerequisites​

  • Node.js 20+ (check with node -v)
  • npm or pnpm package manager

Installation​

Install Agloom globally:

npm install -g agloom

Verify the installation:

agloom --version

Step 1: Initialize​

Create a .agloom/config.yml file in your project root. You can do this manually or use the init command.

Using init:

agloom init --adapter claude

This creates a config.yml and copies any existing Claude Code files (CLAUDE.md, .claude/, .mcp.json) into .agloom/overlays/claude/ so they are preserved as overlays.

Or create it manually:

# .agloom/config.yml
adapters:
  - claude

The adapters field tells Agloom which target tools to generate files for. You can list multiple adapters to generate files for several tools at once.

Step 2: Write Instructions​

Create an AGLOOM.md file in your project root with your project instructions:

# My Project

## Stack

TypeScript, Node.js, React.

## Conventions

- Use functional components.
- Write tests for all new features.
- Keep functions pure when possible.

Agloom discovers AGLOOM.md files in the project root and any subdirectories (excluding node_modules, hidden directories, and .gitignore entries). Each file is transpiled into the corresponding instruction file for every adapter listed in your config.

Step 3: Transpile​

Run the transpile command:

agloom transpile

Agloom reads your .agloom/ directory and generates config files for each adapter:

Produces a CLAUDE.md in your project root.

Add --verbose to see all steps:

agloom transpile --verbose
✓ Transpiling for claude...
  ✓ Instructions         1 file
  ✓ Skills               0 files
  ✓ Agents               0 files
  ✓ Docs                 0 files
  ✓ Schemas              0 files
  ✓ MCP                  0 files
  ✓ Permissions          0 files
  ✓ Overlay              0 files
Done. 1 file written.

Step 4: Verify​

Open the generated CLAUDE.md and confirm it contains your instructions.

Formatting​

Agloom includes a format command to format canonical files (Markdown, JSON, YAML, TOML). By default, it targets .agloom/**/* and **/AGLOOM.md:

agloom format

You can pass specific paths or globs, or use --all to format all supported files in the project:

agloom format "docs/**/*.md"
agloom format --all

Use --check to verify formatting without modifying files. See reference/cli for full details.

What's Next​