Examples
EN

agents-md

Generate or update the AGENTS.md file for AI agent instructions. Useful for updating existing projects to the latest AGENTS.md or switching between content modes.

# Print local (full embedded) version to stdout
hwaro tool agents-md

# Print remote (lightweight) version to stdout
hwaro tool agents-md --remote

# Write to AGENTS.md file
hwaro tool agents-md --write

# Write remote version to file
hwaro tool agents-md --remote --write

# Overwrite without confirmation
hwaro tool agents-md --write --force

Content Modes

Mode Description
--local (default) Full embedded reference (~260 lines). Includes content format, template variables, configuration reference, and AI agent notes. Best for offline or local LLM environments.
--remote Lightweight version (~70 lines). Includes project structure, essential commands, and AI agent notes with links to online documentation and LLM reference.

Both modes include a Site-Specific Instructions section where you can add your own project rules and conventions. Regenerating with --write preserves that section from the existing file. The generated parts are refreshed (or switched between modes) while whatever you wrote under ## Site-Specific Instructions is carried over unchanged. Preservation keys on that exact heading: an existing file without a ## Site-Specific Instructions heading is replaced entirely (the prompt, or a warning under --force, says so before it happens).

Options

Flag Description
--remote Generate lightweight version with links to online docs
--local Generate full embedded reference (default)
--write Write to AGENTS.md file instead of stdout
-f, --force Regenerate an existing file without confirmation (Site-Specific Instructions still preserved)
-h, --help Show help

By default, the command prints to stdout so you can inspect the content before saving. Use --write to save to file. If AGENTS.md already exists, you'll be prompted for confirmation unless --force is used. Without a terminal to answer the prompt (piped or redirected stdin, CI), the command refuses with a usage error (exit 2) instead of writing. Either way, your Site-Specific Instructions section is preserved across the rewrite.

When AGENTS.md is a symlink, --write updates the file it points at as long as that file resolves inside the project (for example AGENTS.md -> CLAUDE.md); a link resolving outside the project is refused.

Relation to hwaro init

When creating a new project, hwaro init also generates an AGENTS.md file. You can control the content mode with the --agents flag:

hwaro init my-site                  # default: remote (lightweight)
hwaro init my-site --agents local   # full embedded reference
hwaro init my-site --skip-agents-md # skip AGENTS.md entirely

See Also