How the Forge Zsh Plugin Intercepts and Routes ':' Prefix Commands to the CLI

The Forge Zsh plugin registers a custom ZLE widget named forge-accept-line that intercepts Enter key presses, parses lines beginning with ':' using regex patterns, and routes them to specific action handlers or the Forge CLI binary while preserving normal shell command execution.

The Forge Zsh plugin transforms the standard Zsh line editor into an intelligent command router that captures colon-prefixed instructions and delegates them to the Rust-based Forge CLI. Implemented in the antinomyhq/forgecode repository, this plugin enables expressive AI-powered workflows directly from your terminal without conflicting with native shell behavior.

Registering the Custom ZLE Widget

The interception mechanism starts in shell-plugin/lib/bindings.zsh, where the plugin registers the Zsh Line Editor (ZLE) widget forge-accept-line and binds it to the Enter key. The configuration targets both carriage return (^M) and line feed (^J) to ensure consistent behavior across different terminal emulators.

# In bindings.zsh

bindkey '^M' forge-accept-line
bindkey '^J' forge-accept-line

When a user presses Enter, ZLE executes forge-accept-line defined in shell-plugin/lib/dispatcher.zsh instead of the default accept-line behavior.

Parsing the ':' Prefix Syntax

Inside dispatcher.zsh, the widget examines the current command line stored in the $BUFFER variable. It validates input against two specific regular expression patterns to identify valid Forge commands.

# Pattern 1: :command or :command arguments

^:([a-zA-Z][a-zA-Z0-9_-]*)( (.*))?

# Pattern 2: : space-separated text

^: (.*)$

If the line matches the first pattern, the widget extracts the command name into user_action and the arguments into input_text. Before any transformation occurs, the plugin preserves the original input in Zsh history using print -s, ensuring users can recall raw commands via standard history navigation even after the plugin processes them.

Dispatching to Action Handlers

The widget implements a case statement that maps user_action to specific handler functions. Hard-coded aliases normalize common shortcuts—ask routes to sage, and plan routes to muse—before the dispatch logic evaluates the command.

The dispatcher recognizes several built-in patterns:

• new|n → _forge_action_new
• agent|a → _forge_action_agent
• doctor → _forge_action_doctor

If no specific match exists, the widget delegates to _forge_action_default implemented in shell-plugin/lib/actions/core.zsh.

Executing Against the Forge CLI

The _forge_action_default function validates commands against the registry returned by _forge_get_commands and determines the command type (CUSTOM or AGENT) from the second column of the show-commands table.

For CUSTOM commands, the plugin generates a conversation ID (stored in _FORGE_CONVERSATION_ID) if needed and executes the binary:

_forge_exec cmd execute --cid "$_FORGE_CONVERSATION_ID" "$user_action" "$input_text"

For AGENT commands without arguments, the plugin switches the active agent by setting _FORGE_ACTIVE_AGENT. When input_text contains content, it launches the interactive CLI session:

_forge_exec_interactive -p "$input_text" --cid "$_FORGE_CONVERSATION_ID"

After execution completes, _forge_reset restores the prompt state and syntax highlighting. Certain actions like editor or commit-preview return early to manage their own buffer cleanup.

Summary

• The Forge Zsh plugin overrides standard Enter key behavior via the forge-accept-line widget defined in dispatcher.zsh and registered in bindings.zsh.
• Colon-prefixed commands are parsed using regex patterns that extract user_action and input_text variables for downstream processing.
• A case statement routes specific aliases to dedicated handlers like _forge_action_new or _forge_action_doctor, falling back to _forge_action_default for unknown commands.
• The default handler validates commands against _forge_get_commands and dispatches to either _forge_exec for direct execution or _forge_exec_interactive for conversational sessions.
• The plugin maintains shell history integrity by calling print -s before transforming the buffer, ensuring raw commands remain accessible via history recall.

Frequently Asked Questions

How does the Forge Zsh plugin capture the Enter key without breaking normal shell commands?

The plugin registers the forge-accept-line widget in bindings.zsh and binds it to ^M and ^J. When executed, the widget checks if $BUFFER starts with a colon. If the line does not match the colon-prefixed pattern, the widget immediately falls back to standard accept-line behavior, ensuring regular shell commands execute normally without interference.

What happens if I type a ':' command that doesn't exist in the Forge CLI?

The widget passes unknown commands to _forge_action_default, which validates the user_action against the output of _forge_get_commands. If the command does not appear in the Forge CLI's show-commands table, the handler manages the error state appropriately without terminating the shell session or corrupting the prompt.

Can I use the Forge Zsh plugin alongside other ZLE customizations such as syntax highlighting?

Yes, the plugin is designed to coexist with other ZLE modifications including syntax highlighting frameworks. It preserves the original $BUFFER in history via print -s before manipulation, and calls _forge_reset after execution to restore prompt state and highlighting. However, conflicting key bindings to ^M or ^J in your .zshrc may require explicit ordering of initialization scripts to ensure bindings.zsh loads after other ZLE configurations.

Where are the command aliases like 'ask' and 'plan' defined within the source code?

Short aliases are normalized within the forge-accept-line widget logic in dispatcher.zsh before the case statement evaluates the action. Specifically, ask maps to the sage agent and plan maps to muse, allowing users to type :ask or :plan as intuitive shorthand for specific agent invocations without requiring separate configuration files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}