forgecode.fish

A fish-native Forge shell plugin.
Colon-prefixed prompts, agent switching, conversation continuity, tagged files, and an opt-in right prompt without falling back to zsh.

Install · First 5 Minutes · Parity Matrix · Traceability · Verification Report

forgecode.fish ports the approved Forge zsh workflow to fish using fish-native bindings, commandline mutation, completions, history handling, prompt hooks, and shell-local actions. The product goal is parity with the existing :-driven Forge workflow, not a fish-specific redesign.

The active implementation lives at the repo root. Planning artifacts under .omx/plans/ remain in the repo as the contract and verification record for the port.

• Turns : <prompt> into a Forge prompt dispatch path with conversation continuity.
• Supports explicit agent prompts (:sage ..., :muse ...) and agent switching via the same colon grammar.
• Keeps session-scoped agent, model, provider, and reasoning overrides inside the current fish session.
• Adds fish-native : command picking, @ file tagging, provider/workspace helpers, editor helpers, and commit helpers.
• Exposes an opt-in right prompt plus fish-native :doctor and :help surfaces.
• Ships a deterministic stub-backed verification harness with Linux current-fish and fish 3.6.x coverage lanes.

You need:

• forge
• fish 3.6+
• fzf
• either fd or fdfind
• python3 for the local verification harness

Copy the plugin directories into your fish config:

mkdir -p ~/.config/fish/conf.d ~/.config/fish/functions ~/.config/fish/completions
cp conf.d/forgecode.fish ~/.config/fish/conf.d/
cp functions/*.fish ~/.config/fish/functions/
cp completions/forge.fish ~/.config/fish/completions/

Open a new fish session or source the plugin directly:

source ~/.config/fish/conf.d/forgecode.fish

If you are working from this checkout, source the plugin from the repo root:

source conf.d/forgecode.fish

AUR packaging lives under packaging/aur and follows the same source-of-truth pattern used in the OneNoted desktop repos.

Planned package names:

yay -S forgecode-fish
# or track HEAD:
yay -S forgecode-fish-git

The current package assumptions and publish checklist are documented in packaging/aur/README.md. The intended publish path is GitHub-driven: tracked metadata lives in this repo and .github/workflows/aur.yml pushes the matching package repo to AUR once the required secrets are configured.

Prompt integration is disabled by default.

Enable it for the current session:

set -gx FORGE_FISH_PROMPT 1
source conf.d/forgecode.fish

That keeps the default install path conservative and avoids taking over an existing fish prompt setup unless you explicitly opt in.

Source the plugin:

source conf.d/forgecode.fish

Try the core flow:

: hello from fish
:sage explain this repository
:agent
:new
:conversation

Try tagged files and session controls:

: review @[README.md]
:model
:reasoning-effort
:doctor
:help

Key workflow reminders:

• : <prompt> sends a prompt with the active agent.
• :<agent> <prompt> sends a prompt with an explicit agent.
• :<agent> with no prompt switches the active agent.
• @ + Tab inserts @[path].
• non-: commands fall through to normal fish execution.

Run the full local suite:

bash scripts/test-fish-plugin.sh

Run the named environment lanes:

bash scripts/run-fish-matrix.sh ENV-1
bash scripts/run-fish-matrix.sh ENV-3

Current verification state:

• ENV-1 — executed locally on Linux / fish 4.6.x
• ENV-3 — executed in Debian 12 / fish 3.6.0 with an accepted PTY-smoke exception
• ENV-2 — prepared as an external macOS verification lane and CI job, but not executed in this Linux-only session

• Parity matrix
• Traceability matrix
• Known differences
• Verification report

Alpha. The fish-native port is implemented and verified against the approved PRD/test-spec contract, with the remaining published exception being the external macOS verification lane.

Apache-2.0. See LICENSE.