Initial commit: homelab infrastructure wiki

- Full Obsidian vault content
- Host configs (ice, grizzley, ubuntu, proxmox, truenas, panda, hyte)
- Media stack documentation
- Traefik HA setup
- Automation scripts
- Bachelor party planning

homelab/raw/articles/forge/reference/docs-zsh-support.md

@@ -0,0 +1,171 @@
+---
+type: agent-doc
+agent: ForgeCode
+source: https://forgecode.dev/docs/zsh-support/
+scraped: 2026-04-28T21:02:44.582641+00:00
+content_hash: b4527bec
+---
+# ZSH Support
+
+ForgeCode's interactive mode runs in its own environment. That means your ZSH aliases, custom functions, and shell tooling don't work inside it. You're stuck choosing between AI help and your own productivity setup.
+
+The : sentinel character solves this. It lets you send prompts to ForgeCode from your native ZSH session — no environment switch, no lost context, no broken aliases.
+
+```
+# Your aliases work as usual (gst = git status, gcam = git commit -am)gstgcam "fix: resolve memory leak"# Ask ForgeCode without leaving your shell: analyze the memory usage patterns in src/server.rs# Run your tools as part of the investigationps aux | grep serverhtop -p $(pgrep server)# Continue with full context: now optimize the memory allocations you identified in the server struct
+```
+
+Shell commands and AI prompts live in the same workflow. Context carries across both.
+
+`TAB`
+`:`
+Type : then immediately press TAB to open the command completion list — switch agents, start a new conversation, open the editor, and more.
+
+```
+:<TAB>   # opens the full command list
+```
+
+## Examples​
+
+### Basic Prompts​
+
+```
+: explain this error message: refactor this function to be more readable: add error handling to the database connection
+```
+
+Prompts go to your last-used agent. If this is your first interaction, it defaults to ForgeCode. The conversation continues across prompts until you run :new.
+
+### Agent Selection​
+
+Switch agents by prefixing the agent name after ::
+
+```
+:sage
+```
+
+ForgeCode prints a confirmation and updates your terminal's right-hand prompt (RPROMPT):
+
+```
+⏺ [16:14:54] SAGE is now the active agent
+```
+
+All subsequent bare : prompts now go to sage:
+
+```
+: explain the algorithm complexity and performance characteristics: what are the potential edge cases?
+```
+
+You can also pass a prompt inline as a shortcut — this switches the agent and sends the prompt in one step:
+
+```
+:forge refactor this function to be more maintainable
+```
+
+Run :agent to pick from a list of all configured agents.
+
+### Starting a New Conversation​
+
+ForgeCode carries conversation context forward indefinitely within a session, until a terminal window is closed. When you move to a different task and don't want the previous context bleeding in, run :new:
+
+```
+:new
+```
+
+This clears the conversation history and starts fresh. The active agent stays the same.
+
+You can also pass a prompt directly — :new starts the fresh conversation and sends it in one step:
+
+```
+:new hi what's the time
+```
+
+### Switching Conversations​
+
+To switch to a different existing conversation, run :conversation:
+
+```
+:conversation
+```
+
+This opens a list of your saved conversations. Select one to switch to it.
+
+To jump back to the last conversation you were in, use the - shorthand:
+
+```
+:conversation -
+```
+
+### File Tagging​
+
+Tag files in your prompts with @ followed by a partial name, then press TAB:
+
+```
+: review the changes in @package<TAB>: explain the logic in @src/utils/helper<TAB>: optimize the queries in @database/queries<TAB>
+```
+
+`TAB`
+`@`
+After typing @ and a few characters, press TAB to open a fuzzy file picker. Type to filter, arrow keys to navigate, Enter to select. The full file path is inserted into your prompt automatically. .gitignore is respected.
+
+If fd and fzf aren't installed, use the full path directly:
+
+```
+: review the changes in @[src/components/Header.tsx]
+```
+
+### Multiline Text​
+
+When your prompt needs structure (lists, steps, logs), insert line breaks directly in the prompt composer:
+
+- Windows/Linux: Shift+Enter
+- macOS: Option+Enter
+
+This lets you write multiline prompts without sending early.
+
+See Keyboard Shortcuts for all shortcuts available in your ZSH session.
+
+### :edit as an Alternative​
+
+For longer prompts, use :edit instead of typing everything inline:
+
+```
+:edit
+```
+
+This opens your configured editor from $FORGE_EDITOR or $EDITOR. Write your prompt, save, and close the editor to send it.
+
+Example (VS Code):
+
+```
+export FORGE_EDITOR="code --wait"# or: export EDITOR="code --wait"
+```
+
+### Retrying a Request​
+
+If you cancel a prompt mid-flight with Ctrl+C and want to run it again, use :retry:
+
+```
+:retry
+```
+
+This resends the last request without you having to retype it. Most useful after an accidental interrupt or a timeout.
+
+### Editing Configuration​
+
+To open the ForgeCode configuration file (~/.forge/.forge.toml) in your default editor, run :config:
+
+```
+:config-edit
+```
+
+See the configuration reference for a full list of available settings.
+
+## Troubleshooting​
+
+Start with these two commands — they cover most issues:
+
+```
+forge zsh doctor # checks your environment and reports problemsforge zsh setup  # re-runs the ZSH integration setup
+```
+
+If both run cleanly and things still aren't working, join us on Discord and we'll help you sort it out.