Getting Started¶

Requirements¶

agents-md-wizard is a Bun script. Install Bun first if you don't have it:

curl -fsSL https://bun.sh/install | bash

Install¶

Global installWithout installingFrom source

bun install -g agents-md-wizard

Then run it anywhere:

agents-md-wizard > AGENTS.md

bunx agents-md-wizard > AGENTS.md

git clone https://github.com/benhuckvale/agents-md-wizard
cd agents-md-wizard
bun install
bun src/cli.tsx > AGENTS.md

Running the TUI¶

agents-md-wizard > AGENTS.md

The TUI draws on stderr so the terminal stays interactive while stdout is redirected to your file. You'll see the interface in your terminal as normal; only the final markdown goes to the file.

If you just want to preview the output without writing a file, run without redirection:

agents-md-wizard

The interface¶

Selection screen¶

Agents Markdown Wizard — compose your AGENTS.md / CLAUDE.md

▸Code Style (3)   Version Control (0)   Testing (0)   Architecture (0) …

Code Style   3/10
  ›  ●  No magic numbers
     ○  Early returns over nesting              │ No magic numbers
     ●  Consistent naming          [stack]      │ ─────────────────
     ●  No commented-out code                   │ - Do not use unexplained numeric
     ○  Minimal focused changes                 │   or string literals inline.
     ○  Explicit over implicit                  │   Extract them as named constants
     …                                          │   with clear names that express
                                                │   intent.

Key	Action
`↑` `↓`	Move cursor
`←` `→`	Switch section tab
`Space`	Toggle selected / deselected
`A`	Select / deselect all in current section
`P`	Toggle the preview panel
`Enter`	Generate output
`Q`	Quit without output

The preview panel on the right shows the exact markdown text that will be written for the highlighted item, including stack-specific variants if they exist.

Stack selection¶

If any of your selected guidelines have stack-specific wording, you'll be asked to choose a target stack:

Target stack (optional)
Some guidelines have stack-specific wording. Choose one, or skip.

› (none — use generic wording)
  typescript
  python

Choosing a stack (e.g. typescript) causes guidelines that have TypeScript-specific wording to use that instead of the generic text.

Variable prompts¶

Some guidelines have configurable values — for example, "Small focused functions" has a max_lines_per_function variable defaulting to 40. You'll be shown each variable with its default:

Configure variables (1/1)

max_lines_per_function   default: 40
› 60▊

Enter to confirm · blank keeps default

Press Enter to accept the default, or type a new value first.

Output format¶

The generated markdown groups your selected guidelines under ## section headings, with each guideline as a bullet:

## Code Style

- Do not use unexplained numeric or string literals inline. Extract them as named constants with clear names that express intent.
- Use consistent naming conventions throughout the codebase.
- Do not leave commented-out code in the codebase. If code is unused, delete it. Version control preserves history.

## Version Control

- Make atomic commits. If changing a function, include the relevant tests and documentation changes in the same commit.
- Each commit should produce a working build.

Using a specific config file or directory¶

By default agents-md-wizard loads its own bundled guidelines. You can point it at your own file or directory instead:

agents-md-wizard --config my-guidelines.yaml > AGENTS.md
agents-md-wizard --dir path/to/guidelines/    > AGENTS.md

See Custom Guidelines for how to write your own.