Documentation
¶
Overview ¶
Package commands implements OpenClaw-style slash commands for the harness.
Two kinds exist:
Workspace commands: user-authored markdown files discovered from the workspace (mirroring the skills-folder model). A command file is "<dir>/<name>.md", optionally namespaced one level as "<dir>/<ns>/<name>.md" -> "<ns>:<name>". Its YAML-ish frontmatter carries description / argument-hint / model / allowed-tools and the body is a prompt template. Invoking "/<name> <args>" expands the body (substituting $ARGUMENTS and $1..$9) and feeds the result to the model as the turn's user prompt.
Reserved built-ins (help, commands, clear): handled by the runner without calling the model. Reserved names cannot be shadowed by workspace files.
Parsing follows OpenClaw: a leading "/", an optional ":" after the name ("/think: high" == "/think high"), and hyphen/underscore-insensitive names.
NOTE: literal OpenClaw registers commands as code handlers; a Go sandbox runtime cannot load handler code from a workspace, so workspace commands are markdown prompt-expansion (the Claude-Code convention) while parsing/dispatch semantics stay faithful to OpenClaw.
Index ¶
- Variables
- func CanonicalBuiltin(name string) (canonical string, ok bool)
- func CanonicalKey(name string) string
- func Expand(body, args string) string
- func IsReserved(name string) bool
- func Parse(line string) (name, args string, ok bool)
- type Command
- type CommandDef
- type Owner
- type Registry
- type Surface
Constants ¶
This section is empty.
Variables ¶
var ReservedNames = func() map[string]string { definitions := Definitions(SurfaceRunner) out := make(map[string]string, len(definitions)) for _, definition := range definitions { out[CanonicalKey(definition.Name)] = definition.Description } return out }()
ReservedNames are built-in command names handled by the runner; workspace files using these names are ignored so built-ins cannot be shadowed. The value is the help-line description.
Functions ¶
func CanonicalBuiltin ¶ added in v0.0.2
CanonicalBuiltin resolves a known built-in or alias. Unknown names are returned in canonical-key form with ok=false.
func CanonicalKey ¶
CanonicalKey normalizes a command name for lookup: lower-case with underscores folded to hyphens so "/dock-discord" and "/dock_discord" resolve identically. Namespace separators (":") are preserved.
func Expand ¶
Expand substitutes argument tokens in a command body:
$ARGUMENTS -> the full raw argument string
$1 .. $9 -> whitespace-split positional arguments ("" when absent)
Tokens with no corresponding argument expand to the empty string. $ARGUMENTS is listed first so it is never partially matched by a positional token.
func IsReserved ¶
IsReserved reports whether name collides with a reserved built-in command.
func Parse ¶
Parse splits a chat line into a command name and raw argument string. It returns ok=false when the line is not a slash command. The name is lower-cased and stripped of a trailing ":" ("/think:" -> "think"); args is everything after the first run of whitespace, trimmed. A bare "/", a leading "//", or a "/ foo" (slash then space) is not treated as a command.
Types ¶
type Command ¶
type Command struct {
Name string // canonical, lower-case (e.g. "commit" or "git:commit")
Description string // from frontmatter description (or fallback)
ArgumentHint string // from frontmatter argument-hint (display only)
Model string // optional per-turn model override (frontmatter model)
AllowedTools []string // from frontmatter allowed-tools (display only for now)
Body string // prompt template (frontmatter stripped)
Path string // workspace-relative or absolute operator source path
}
Command is a single workspace command discovered from the filesystem.
func Discover ¶
Discover scans each workspace-relative or absolute dir for "<name>.md" command files plus one level of namespace dirs ("<ns>/<name>.md" -> "<ns>:<name>"). Missing dirs are skipped. Commands are de-duplicated by canonical name (first occurrence wins; dirs are scanned in order). Reserved names are skipped.
type CommandDef ¶ added in v0.0.2
type CommandDef struct {
Name string
Aliases []string
Description string
ArgumentHint string
Owner Owner
Surfaces []Surface
AliasFor string
}
CommandDef is the declarative metadata shared by reserved-name checks, help, completion, and command catalogs. Aliases are expanded by Definitions.
func Definitions ¶ added in v0.0.2
func Definitions(surface Surface) []CommandDef
Definitions returns detached definitions for a surface, with aliases expanded into independently displayable entries pointing at their canonical command.
type Owner ¶ added in v0.0.2
type Owner string
Owner identifies the component that handles a command after metadata-driven discovery. Handlers remain in their owning packages.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds discovered workspace commands, keyed for hyphen/underscore- and case-insensitive lookup. A nil *Registry is usable (empty). First occurrence of a key wins, so callers should pass commands in precedence order.
func New ¶
New builds a Registry from the given commands (deduplicated by canonical key; first occurrence wins).
Source Files