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

> Discover how the Forge Zsh plugin intercepts and routes ':' prefix commands to the Forge CLI. Learn about its custom ZLE widget and regex parsing for seamless command execution.

- Repository: [Forge Code/forgecode](https://github.com/antinomyhq/forgecode)
- Tags: internals
- Published: 2026-04-08

---

**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`](https://github.com/antinomyhq/forgecode/blob/main/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.

```zsh

# 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`](https://github.com/antinomyhq/forgecode/blob/main/shell-plugin/lib/dispatcher.zsh) instead of the default `accept-line` behavior.

## Parsing the ':' Prefix Syntax

Inside [`dispatcher.zsh`](https://github.com/antinomyhq/forgecode/blob/main/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.

```zsh

# 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`](https://github.com/antinomyhq/forgecode/blob/main/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:

```zsh
_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:

```zsh
_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`](https://github.com/antinomyhq/forgecode/blob/main/dispatcher.zsh) and registered in [`bindings.zsh`](https://github.com/antinomyhq/forgecode/blob/main/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`](https://github.com/antinomyhq/forgecode/blob/main/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`](https://github.com/antinomyhq/forgecode/blob/main/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`](https://github.com/antinomyhq/forgecode/blob/main/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.