agentsmd-formatter (agsmd)

A small CLI that merges rule profiles into AGENTS.md files (or agents.md) that AI coding agents read. Stop copy-pasting the same global rules into every new project: keep a set of profiles per project type, then apply or generate AGENTS.md in one command.

• Format an existing AGENTS.md — merge a profile into it. Matching section headings are replaced, project-specific sections are preserved. Uses AI (deepseek-v4-flash via the OpenCode Go gateway) to merge intelligently, with a deterministic, no-AI fallback.
• Generate a preset AGENTS.md — for new projects, from a profile alone or profile + standard skeleton.

Install

npm install -g agentsmd-formatter
agsmd setup

setup stores your API key and preferences in ~/.config/agentsmd-formatter/config.json, so the tool is ready on any machine after a single interactive setup.

Profiles

Profiles are plain markdown files in ~/agentsmd-profiles/ (one file per profile, e.g. web-app.md, python-lib.md). Sections are ## Headings:

# web-app

## Build
Run `npm install`. Start the dev server with `npm run dev`.

## Test
Run `npm test`. Add a test for every new behavior.

## Code Style
Prefer TypeScript. No comments unless asked.

Headings in the profile replace the same headings in the target AGENTS.md; everything else in the target file is left untouched.

Commands

| Command | Description | | --- | --- | | agsmd | Open the interactive TUI (when run in a terminal) | | agsmd tui | Force-open the interactive TUI | | agsmd setup | Configure API key, model, base URL, profiles dir | | agsmd list | List available profiles | | agsmd init | Create the profiles directory | | agsmd profile new <name> | Create a new profile from a template | | agsmd format <file> [--profile <p>] [--out <p>] [--no-ai] [--no-backup] | Merge a profile into an existing AGENTS.md | | agsmd preset <profile> [--skeleton] [--out <p>] | Generate an AGENTS.md for a new project | | agsmd config | Show current config (key masked) |

TUI

Run agsmd (or agsmd tui) in a real terminal to get a menu-driven interface for everything the CLI does:

• Format an existing AGENTS.md — pick a profile, the target file, AI vs deterministic merge, backup preference, and output path.
• Generate a preset — pick a profile, choose skeleton or rules-only, write to a file or print to stdout.
• Create a new profile — name it, get a template, open it in your $EDITOR (falls back to notepad on Windows, vi elsewhere) to fill in the rules.
• Manage profiles — view, edit, or delete existing profiles.
• Settings — inspect the config or re-run the setup prompts.

The CLI and TUI share the same profile store and merge logic.

Format examples

# AI merge, overwrite in place (writes file.bak first)
agsmd format AGENTS.md --profile web-app

# Deterministic merge, no backup
agsmd format AGENTS.md --profile web-app --no-ai --no-backup

# Write result to a new path
agsmd format AGENTS.md --profile web-app --out formatted.md

# Interactive profile picker (omit --profile)
agsmd format AGENTS.md

Preset examples

# Rules only, print to stdout
agsmd preset web-app

# Standard skeleton + profile rules, write to AGENTS.md
agsmd preset web-app --skeleton --out AGENTS.md

Configuration

agsmd setup writes to ~/.config/agentsmd-formatter/config.json. Everything can also be overridden via environment variables:

• AGENTSMD_API_KEY
• AGENTSMD_MODEL (default deepseek-v4-flash)
• AGENTSMD_BASE_URL (default https://opencode.ai/zen/go/v1)
• AGENTSMD_PROFILES_DIR (default ~/agentsmd-profiles)
• AGENTSMD_CONFIG_DIR (default ~/.config/agentsmd-formatter)

Sharing

The package is meant to be shared. Peers install it, run agsmd setup with their own key, and point AGENTSMD_PROFILES_DIR (or the profile config) at a shared, git-versioned profiles folder — e.g. clone [email protected]:you/agentsmd-profiles.git and export the env var.

Development

npm install
npm run build
node dist/cli.js --help