hermes-ice/homelab/raw/articles/forge/reference/docs-commands.md

type, agent, source, scraped, content_hash

type	agent	source	scraped	content_hash
agent-doc	ForgeCode	https://forgecode.dev/docs/commands/	2026-04-28T21:02:35.706451+00:00	8ef9d024

Custom Commands

You repeat the same workflow constantly — lint, test, fix, commit. Every time, you type it out or paste it from a notes file. Custom commands let you turn any repeatable workflow into a named slash command that ForgeCode executes on demand.

How It Works​

A custom command is a Markdown file in the .forge/commands/ directory. The filename becomes the command name. The file body is the instruction ForgeCode follows when you invoke it.

.forge/└── commands/    ├── check.md     →  :check    └── fixme.md     →  :fixme

Type :check in the chat, and ForgeCode runs whatever check.md describes. That's it.

File Format​

Every command file has two parts: a frontmatter block and an instruction body.

---name: checkdescription: Checks if the code is ready to be committed---- Run the `lint` and `test` commands and verify if everything is fine.  <lint>cargo +nightly fmt --all; cargo +nightly clippy --fix --allow-staged --allow-dirty --workspace</lint>  <test>cargo insta test --accept --unreferenced=delete</test>- Fix every issue found in the process

Frontmatter​

Field	Required	Description
name	Yes	The slash command name (e.g. check → /check)
description	Yes	One-line summary shown in the command picker

Body​

The body is plain Markdown. Write it the same way you'd explain the workflow to a teammate. You can use:

• Prose for context or decision logic
• Bullet lists for sequential steps
• XML-style tags to attach literal shell commands to a step (e.g. ..., ...)
• Code blocks for multi-line scripts

ForgeCode reads the body as instructions and executes them. If a step fails, it attempts to fix the problem before continuing — just like it would for any other task.

A Minimal Example​

The simplest possible command:

---name: fixmedescription: Looks for all the fixme comments in the code and attempts to fix them---Find all the FIXME comments in source-code files and attempt to fix them.

Invoke it with :fixme and ForgeCode searches every source file for FIXME comments and tries to resolve each one.

A More Complex Example​

Commands can embed exact shell commands so ForgeCode runs the right tools every time:

---name: checkdescription: Checks if the code is ready to be committed---- Run the `lint` and `test` commands and verify if everything is fine.  <lint>cargo +nightly fmt --all; cargo +nightly clippy --fix --allow-staged --allow-dirty --workspace</lint>  <test>cargo insta test --accept --unreferenced=delete</test>- Fix every issue found in the process

The and tags tell ForgeCode the exact commands to run for those steps. If clippy reports an error, ForgeCode fixes it. If a test fails, ForgeCode investigates. You don't have to tell it how — the command already knows.

Where to Put Commands​

Commands can live in three places, loaded in precedence order:

.forge/commands/          ← project commands (highest precedence)~/.agents/commands/       ← shared across agent tools~/forge/commands/         ← global, across all projects

Project commands are the most common. Check them into version control and your team shares the same /check, /fixme, and any other workflows you define.

Invoking Commands​

Type the command name with a leading slash in the ForgeCode chat:

:check:fixme

ForgeCode picks it up immediately. No restart needed — new command files are available as soon as they exist on disk.

Verifying Your Commands​

To see all available commands, run :help in the chat. You'll get a list with names and descriptions.

:help

---

The hardest part of getting value from custom commands is identifying which workflows deserve one. A good rule: if you've typed the same instruction three times, write a command for it.