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/concepts/forge-ai.md

@@ -0,0 +1,144 @@
+---
+title: Forge AI
+created: 2026-04-28
+updated: 2026-04-28
+type: concept
+tags: [concept, ai, tools, cli]
+sources: [../raw/articles/forge/]
+confidence: high
+---
+
+# Forge AI
+
+Forge AI (ForgeCode) is a CLI-based AI coding harness — a competitor to Claude Code with first-class support for many AI providers. It works with cloud models, open-weight models, and local models.
+
+**Website:** https://forgecode.dev
+
+## Agents
+
+Forge provides three built-in agents:
+
+| Agent | Access | Purpose |
+|-------|--------|---------|
+| **muse** | read + write | Planning and analysis — reviews impact, plans changes |
+| **forge** | read + write | Implementation — makes changes, fixes bugs (default) |
+| **sage** | read | Research — used internally by muse/forge for codebase understanding |
+
+Typical workflow: use `muse` to plan, switch to `forge` to implement.
+
+Switch agents with `:agent`, `:muse`, `:forge`.
+
+## Custom Agents
+
+Create agents as markdown files with YAML frontmatter in `.forge/agents/` (project) or `~/forge/agents/` (global).
+
+```yaml
+---
+id: my-agent
+title: My Agent
+description: Brief description
+tools: [read, search, shell]
+model: claude-sonnet-4
+provider: anthropic
+temperature: 0.1
+---
+System prompt here.
+```
+
+Tools: read, write, patch, shell, search, fetch, remove, undo, or `"*"` for all.
+
+## Custom Commands
+
+Repeatable workflows as slash commands in `.forge/commands/`:
+
+```markdown
+---
+name: check
+description: Runs lint and tests before commit
+---
+Run `lint` and `test`, fix any issues found.
+<lint>cargo clippy --fix</lint>
+<test>cargo test</test>
+```
+
+Invoke with `:check` in the Forge chat.
+
+## MCP Integration
+
+Connect external tools via `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "browser": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+Manage with `forge mcp import`, `forge mcp list`, `forge mcp remove`, `forge mcp reload`.
+
+## Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `FORGE_TERM` | on | Terminal context capture — passes command history to the model |
+| `FORGE_TERM_MAX_COMMANDS` | 5 | History buffer size |
+| `FORGE_CONFIG` | `~/forge/` | Config directory (for dotfiles repos) |
+| `FORGE_BIN` | `forge` | Binary path (for local builds or version switching) |
+
+## $FORGE_TERM
+
+On by default. The Zsh plugin tracks what commands you run, whether they succeeded, and passes that to ForgeCode on every `:` invocation. Means `forge fix it` already knows what failed — no need to narrate.
+
+Disable per-session: `export FORGE_TERM=false`
+
+## Forge Services
+
+Optional backend for enhanced capabilities: context engine (semantic search), tool-call guardrails, and skill engine. Enable with `:login` → select ForgeServices.
+
+Index project with `:sync`, check status with `:sync-status`.
+
+## Setup
+
+```bash
+# 1. Install
+curl -fsSL https://forgecode.dev/cli | sh
+
+# 2. Zsh plugin
+forge zsh setup
+
+# 3. Login to provider
+:login
+
+# 4. Pick model
+:model
+
+# 5. First prompt
+: Hi!
+```
+
+Requires: Nerd Font, Zsh.
+
+## Skills
+
+ForgeCode skills are markdown files (`.forge/skills/`) that provide reusable workflows. Similar to custom commands but more powerful — skills can use templating and conditional logic.
+
+## Configuration Files
+
+| File | Purpose |
+|------|---------|
+| `.forge.toml` | Main config ( ForgeConfig dir) |
+| `.mcp.json` | MCP server definitions |
+| `.forge/agents/` | Custom agent definitions |
+| `.forge/commands/` | Custom slash commands |
+| `.forge/skills/` | Reusable skill workflows |
+| `AGENTS.md` | Project-wide rules for all agents |
+
+## Related
+
+- [[opencode-cluster]] — OpenCode cluster setup in this homelab
+- [[ai-applications]] — AI application stack on ubuntu
+- [[hermes-gateway]] — Hermes gateway used for model routing