@aion0/forge 0.5.26 → 0.5.28

package/.forge/worktrees/pipeline-4dd8dc2d/lib/forge-skills/forge-inbox.md

@@ -0,0 +1,38 @@
+---
+description: "[FALLBACK — only use if MCP get_inbox tool is NOT available] Check messages from other Forge Workspace agents via HTTP API"
+---
+
+# Forge Inbox
+
+Check for messages from other agents and manage their status.
+
+## When to trigger
+- At the start of a new conversation/session
+- When the user asks about other agents' status or messages
+
+## How to use
+
+### Option 1: MCP Tools (preferred)
+If MCP tools are available, use them directly:
+- `get_inbox()` — check messages
+- `mark_message_done(message_id: "ID")` — mark as done
+- `check_outbox()` — check messages you sent
+
+### Option 2: HTTP API (fallback)
+
+Step 1 — Get workspace ID (env var first, then API fallback):
+```bash
+WS_ID="${FORGE_WORKSPACE_ID:-$(curl -s "http://localhost:8405/resolve?projectPath=$(pwd)" | python3 -c "import sys,json; print(json.load(sys.stdin).get('workspaceId',''))" 2>/dev/null)}"
+```
+
+Step 2 — Check inbox:
+```bash
+curl -s -X POST "http://localhost:8403/api/workspace/$WS_ID/smith" -H "Content-Type: application/json" -d '{"action":"inbox","agentId":"'"$FORGE_AGENT_ID"'"}'
+```
+
+## Mark message as done
+```bash
+curl -s -X POST "http://localhost:8403/api/workspace/$WS_ID/smith" -H "Content-Type: application/json" -d '{"action":"message_done","agentId":"'"$FORGE_AGENT_ID"'","messageId":"MESSAGE_ID"}'
+```
+
+After handling a message, always mark it as done or failed.

package/.forge/worktrees/pipeline-4dd8dc2d/lib/forge-skills/forge-send.md

@@ -0,0 +1,47 @@
+---
+description: "[FALLBACK — only use if MCP send_message tool is NOT available] Send a message to another Forge Workspace agent via HTTP API"
+---
+
+# Forge Send
+
+Send a message to another agent in the Forge Workspace.
+
+## When to trigger
+- You fixed a bug that QA reported → notify QA immediately
+- You have a question about requirements → ask PM
+- You found an issue that another agent should know about
+- User explicitly asks to send a message to another agent
+
+## When NOT to trigger
+- Do NOT send a reply to the agent whose message you are currently processing. The system automatically marks your result as done and notifies them. Only use forge-send for NEW issues or questions to OTHER agents.
+
+## How to send
+
+### Option 1: MCP Tool (preferred)
+If the `send_message` tool is available, use it directly:
+```
+send_message(to: "TARGET_LABEL", content: "YOUR MESSAGE", action: "ACTION")
+```
+
+### Option 2: HTTP API (fallback if MCP not available)
+
+Step 1 — Get workspace ID (env var first, then API fallback):
+```bash
+WS_ID="${FORGE_WORKSPACE_ID:-$(curl -s "http://localhost:8405/resolve?projectPath=$(pwd)" | python3 -c "import sys,json; print(json.load(sys.stdin).get('workspaceId',''))" 2>/dev/null)}"
+echo "$WS_ID"
+```
+
+Step 2 — Send message:
+```bash
+curl -s -X POST "http://localhost:8403/api/workspace/$WS_ID/smith" -H "Content-Type: application/json" -d '{"action":"send","agentId":"'"$FORGE_AGENT_ID"'","to":"TARGET_LABEL","msgAction":"ACTION","content":"YOUR MESSAGE"}'
+```
+
+Replace:
+- `WORKSPACE_ID` = the ID from step 1
+- `TARGET_LABEL` = target agent label (e.g., "QA", "PM", "Engineer", "Reviewer")
+- `ACTION` = one of: `fix_request`, `update_notify`, `question`, `info_request`, `review`
+- `YOUR MESSAGE` = your actual message
+
+Note: `$FORGE_AGENT_ID` is automatically set by Forge when launching the terminal. Do NOT replace it manually.
+
+Tell the user the result.

package/.forge/worktrees/pipeline-4dd8dc2d/lib/forge-skills/forge-status.md

@@ -0,0 +1,32 @@
+---
+description: "[FALLBACK — only use if MCP get_status tool is NOT available] Check agent statuses via HTTP API"
+---
+
+# Forge Status
+
+Check the current status of all agents in the Forge Workspace.
+
+## When to trigger
+- User asks "what's the status?" or "how are other agents doing?"
+- At the start of a session to understand the current workspace state
+
+## How to check
+
+### Option 1: MCP Tools (preferred)
+If MCP tools are available:
+- `get_status()` — all agent statuses
+- `get_agents()` — agent details (roles, dependencies)
+
+### Option 2: HTTP API (fallback)
+
+Step 1 — Get workspace ID (env var first, then API fallback):
+```bash
+WS_ID="${FORGE_WORKSPACE_ID:-$(curl -s "http://localhost:8405/resolve?projectPath=$(pwd)" | python3 -c "import sys,json; print(json.load(sys.stdin).get('workspaceId',''))" 2>/dev/null)}"
+```
+
+Step 2 — Check status:
+```bash
+curl -s -X POST "http://localhost:8403/api/workspace/$WS_ID/smith" -H "Content-Type: application/json" -d '{"action":"status","agentId":"'"$FORGE_AGENT_ID"'"}'
+```
+
+Present the results as a clear status overview.

package/.forge/worktrees/pipeline-4dd8dc2d/lib/forge-skills/forge-workspace-sync.md

@@ -0,0 +1,37 @@
+---
+description: Automatically sync your work progress with Forge Workspace when you've completed a task or made significant changes
+---
+
+# Forge Workspace Sync
+
+When you detect that the user has completed a meaningful unit of work, automatically sync with Forge Workspace.
+
+## When to trigger
+- User says they're done ("done", "完成了", "finished", "that should work")
+- You've made multiple file changes and the conversation reaches a natural stopping point
+- User asks to move on to the next task or agent
+
+## How to sync
+
+IMPORTANT: Do NOT check environment variables. Just run the commands.
+
+Step 1 — Get workspace ID:
+```bash
+curl -s "http://localhost:8403/api/workspace?projectPath=$(pwd)" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))"
+```
+
+Step 2 — Sync (replace WORKSPACE_ID):
+```bash
+curl -s -X POST "http://localhost:8403/api/workspace/WORKSPACE_ID/smith" -H "Content-Type: application/json" -d '{"action":"done","agentId":"'"$FORGE_AGENT_ID"'","output":"PASTE_YOUR_RECENT_OUTPUT_HERE"}'
+```
+
+Include any `[SEND:AgentLabel:action] message` markers in the `output` field.
+
+This will:
+1. Detect git changes since last sync
+2. Record what you did in agent memory
+3. Parse [SEND:...] markers and deliver messages
+4. Mark this agent as "done"
+5. Notify downstream agents
+
+Tell the user what files changed, messages sent, and that downstream agents were notified.

package/.forge/worktrees/pipeline-4dd8dc2d/lib/help-docs/00-overview.md

@@ -0,0 +1,40 @@
+# Forge Overview
+
+Forge is a self-hosted Vibe Coding platform for Claude Code. It provides a browser-based terminal, multi-agent workspace orchestration, AI task management, remote access, and mobile control via Telegram.
+
+## Quick Start
+
+```bash
+npm install -g @aion0/forge
+forge server start
+```
+
+Open `http://localhost:8403`. First launch prompts you to set an admin password.
+
+## Requirements
+- Node.js >= 20
+- tmux (`brew install tmux` on macOS)
+- Claude Code CLI (`npm install -g @anthropic-ai/claude-code`)
+
+## Data Location
+- Config: `~/.forge/` (binaries)
+- Data: `~/.forge/data/` (settings, database, state)
+- Workspaces: `~/.forge/workspaces/<id>/` (workspace state files)
+- Claude: `~/.claude/` (skills, commands, sessions)
+
+## Architecture
+- `forge-server.mjs` starts: Next.js (port 8403) + Terminal server + Telegram bot + Workspace daemon (port 8405)
+- `pnpm dev` / `start.sh dev`: Next.js dev mode (init.ts spawns terminal + telegram + workspace)
+- `FORGE_EXTERNAL_SERVICES=1`: Next.js skips spawning (forge-server manages external services)
+
+## Server Commands
+```bash
+forge server start              # background (default)
+forge server start --foreground # foreground
+forge server start --dev        # dev mode with hot-reload
+forge server stop               # stop
+forge server restart            # restart
+forge server start --port 4000  # custom port
+forge server start --dir ~/.forge-test  # custom data dir
+forge --reset-password          # reset admin password
+```

package/.forge/worktrees/pipeline-4dd8dc2d/lib/help-docs/01-settings.md

@@ -0,0 +1,194 @@
+# Settings Configuration
+
+Settings are stored in `~/.forge/data/settings.yaml`. Configure via the web UI (Settings button in top-right menu) or edit YAML directly.
+
+## All Settings Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `projectRoots` | string[] | `[]` | Directories containing your projects (e.g. `~/Projects`) |
+| `docRoots` | string[] | `[]` | Markdown/Obsidian vault directories |
+| `claudePath` | string | `""` | Path to claude binary (auto-detected if empty) |
+| `claudeHome` | string | `""` | Claude Code home directory (default: `~/.claude`) |
+| `telegramBotToken` | string | `""` | Telegram Bot API token (encrypted) |
+| `telegramChatId` | string | `""` | Telegram chat ID (comma-separated for multiple users) |
+| `notifyOnComplete` | boolean | `true` | Telegram notification on task completion |
+| `notifyOnFailure` | boolean | `true` | Telegram notification on task failure |
+| `tunnelAutoStart` | boolean | `false` | Auto-start Cloudflare Tunnel on server startup |
+| `telegramTunnelPassword` | string | `""` | Admin password for login + tunnel + secrets (encrypted) |
+| `taskModel` | string | `"default"` | Model for background tasks |
+| `pipelineModel` | string | `"default"` | Model for pipeline workflows |
+| `telegramModel` | string | `"sonnet"` | Model for Telegram AI features |
+| `defaultAgent` | string | `"claude"` | Default agent for tasks and terminal |
+| `telegramAgent` | string | `""` | Agent for Telegram task execution |
+| `docsAgent` | string | `""` | Agent for documentation queries |
+| `skipPermissions` | boolean | `false` | Add `--dangerously-skip-permissions` to claude invocations |
+| `notificationRetentionDays` | number | `30` | Auto-cleanup notifications older than N days |
+| `skillsRepoUrl` | string | forge-skills URL | GitHub raw URL for skills registry |
+| `displayName` | string | `"Forge"` | Display name shown in header |
+| `displayEmail` | string | `""` | User email |
+| `favoriteProjects` | string[] | `[]` | Starred project paths |
+| `obsidianVault` | string | `""` | Path to Obsidian vault |
+
+## Agents
+
+Forge auto-detects installed CLI agents (Claude Code, Codex, Aider). You can also add custom agents manually.
+
+### Agent Fields
+
+Each agent entry in `settings.agents` supports:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Display name |
+| `path` | string | Path to CLI binary |
+| `enabled` | boolean | Whether this agent is available |
+| `cliType` | string | CLI tool type: `claude-code`, `codex`, `aider`, `generic` |
+| `taskFlags` | string | Flags for headless task execution (e.g. `-p --verbose`) |
+| `interactiveCmd` | string | Command for interactive terminal sessions |
+| `resumeFlag` | string | Flag to resume sessions (e.g. `-c` for claude) |
+| `outputFormat` | string | Output format: `stream-json`, `text` |
+| `skipPermissionsFlag` | string | Flag to skip permissions (e.g. `--dangerously-skip-permissions`) |
+| `requiresTTY` | boolean | Whether agent needs a PTY (true for codex) |
+| `models` | object | Model overrides per context: `terminal`, `task`, `telegram`, `help`, `mobile` |
+| `profile` | string | Linked profile ID — applies that profile's env/model when launching |
+
+### CLI Type
+
+The `cliType` field determines how Forge interacts with the agent:
+
+| CLI Type | Session Support | Resume | Skip Permissions |
+|----------|----------------|--------|------------------|
+| `claude-code` | Yes (session files) | `-c` / `--resume <id>` | `--dangerously-skip-permissions` |
+| `codex` | No | — | `--full-auto` |
+| `aider` | No | — | `--yes` |
+| `generic` | No | — | — |
+
+### Example YAML
+
+```yaml
+agents:
+  claude:
+    name: Claude Code
+    path: /usr/local/bin/claude
+    enabled: true
+    cliType: claude-code
+    skipPermissionsFlag: --dangerously-skip-permissions
+  codex:
+    name: OpenAI Codex
+    path: codex
+    enabled: true
+    cliType: codex
+    requiresTTY: true
+    skipPermissionsFlag: --full-auto
+```
+
+## Agent Profiles
+
+Profiles are reusable configurations that extend a base agent with custom environment variables, model overrides, and CLI settings. Any smith or terminal session can use a profile.
+
+### Profile Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `base` | string | Base agent ID (e.g. `claude`, `codex`) — makes this entry a profile |
+| `name` | string | Display name |
+| `model` | string | Model override (passed via `--model` flag) |
+| `env` | object | Environment variables injected when launching |
+| `cliType` | string | Override CLI type (inherits from base if not set) |
+| `enabled` | boolean | Whether this profile is available |
+
+### Example: Custom API Endpoint Profile
+
+```yaml
+agents:
+  forti-k2:
+    base: claude
+    name: Forti K2
+    model: forti-k2
+    env:
+      ANTHROPIC_AUTH_TOKEN: sk-xxx
+      ANTHROPIC_BASE_URL: http://my-server:7001/
+      ANTHROPIC_SMALL_FAST_MODEL: forti-k2
+      CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "true"
+      DISABLE_TELEMETRY: "true"
+```
+
+### Example: Model Override Profile
+
+```yaml
+agents:
+  claude-opus:
+    base: claude
+    name: Claude Opus
+    model: claude-opus-4-6
+  claude-sonnet:
+    base: claude
+    name: Claude Sonnet
+    model: claude-sonnet-4-6
+```
+
+### How Profiles Work
+
+1. A profile inherits all capabilities from its base agent (binary path, session support, resume flags)
+2. Environment variables from `env` are exported before launching the CLI
+3. The `model` field is passed as `--model <value>` flag (claude-code) or via env
+4. Profiles appear in agent selection dropdowns alongside base agents
+
+### Linking a Profile to an Agent
+
+In the agent configuration, set the `profile` field to link a profile:
+
+```yaml
+agents:
+  claude:
+    profile: forti-k2    # Claude will use forti-k2's env/model when launched
+```
+
+This applies the profile's environment variables and model override whenever that agent is launched in a terminal.
+
+## API Providers
+
+Configure API keys for direct API access (used by API-backend smiths):
+
+```yaml
+providers:
+  anthropic:
+    apiKey: sk-ant-...    # encrypted on save
+    defaultModel: claude-sonnet-4-6
+    enabled: true
+  google:
+    apiKey: AIza...
+    defaultModel: gemini-2.0-flash
+    enabled: true
+  openai:
+    apiKey: sk-...
+    enabled: false
+```
+
+Provider API keys are encrypted with AES-256-GCM. The UI shows masked values (••••••••).
+
+## Admin Password
+
+- Set on first launch (CLI prompt)
+- Required for: login, tunnel start, secret changes, Telegram commands
+- Reset: `forge --reset-password`
+
+## Encrypted Fields
+
+`telegramBotToken` and `telegramTunnelPassword` are encrypted with AES-256-GCM. Agent/provider `apiKey` fields are also encrypted. The encryption key is stored at `~/.forge/data/.encrypt-key`.
+
+## Settings UI
+
+The Settings modal has these sections:
+
+| Section | What it configures |
+|---------|-------------------|
+| **Project Roots** | Directories to scan for projects |
+| **Document Roots** | Markdown/Obsidian vault paths |
+| **Agents** | Detected CLI agents + configuration |
+| **Profiles** | Agent profiles with env/model overrides |
+| **Providers** | API provider keys and defaults |
+| **Telegram** | Bot token, chat ID, notification toggles |
+| **Display** | Name, email |
+| **Other** | Skip permissions, skills repo URL, notification retention |

package/.forge/worktrees/pipeline-4dd8dc2d/lib/help-docs/02-telegram.md

@@ -0,0 +1,41 @@
+# Telegram Bot Setup
+
+## Setup Steps
+
+1. Open Telegram, search for [@BotFather](https://t.me/botfather)
+2. Send `/newbot`, follow prompts to create a bot
+3. Copy the bot token (looks like `6234567890:ABCDefGHIJKLMNOPQRSTUVWXYZ`)
+4. In Forge Settings, paste the token into **Telegram Bot Token**
+5. To get your Chat ID: send any message to your bot, then visit `https://api.telegram.org/bot<TOKEN>/getUpdates` — find `chat.id` in the response
+6. Paste the Chat ID into **Telegram Chat ID** in Settings
+7. The bot starts automatically after saving
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/task <project> <prompt>` | Create a background task |
+| `/tasks [status]` | List tasks (running/queued/done/failed) |
+| `/sessions [project]` | AI summary of Claude Code sessions |
+| `/watch <id>` | Live stream task output |
+| `/unwatch <id>` | Stop streaming |
+| `/docs <query>` | Search Obsidian vault |
+| `/note <text>` | Quick note to vault |
+| `/peek <project>` | Preview running session |
+| `/cancel <id>` | Cancel a task |
+| `/retry <id>` | Retry a failed task |
+| `/tunnel_start <password>` | Start Cloudflare Tunnel (returns URL + code) |
+| `/tunnel_stop` | Stop tunnel |
+| `/tunnel_code <password>` | Get session code for remote login |
+| `/projects` | List configured projects |
+
+## Shortcuts
+- Reply to a task message to interact with it
+- Send `"project: instructions"` to quick-create a task
+- Numbered lists — reply with a number to select
+
+## Troubleshooting
+
+- **Bot not responding**: Check token is correct, restart server
+- **"Unauthorized"**: Chat ID doesn't match configured value
+- **Multiple users**: Set comma-separated Chat IDs (e.g. `123456,789012`)

package/.forge/worktrees/pipeline-4dd8dc2d/lib/help-docs/03-tunnel.md

@@ -0,0 +1,31 @@
+# Remote Access (Cloudflare Tunnel)
+
+## How It Works
+
+Forge creates a temporary Cloudflare Tunnel — a secure public URL that routes to your local Forge server. No Cloudflare account needed.
+
+## Start Tunnel
+
+**From UI**: Click the "Tunnel" button in the top-right header.
+
+**From Telegram**: `/tunnel_start <admin_password>`
+
+**Auto-start**: Set `tunnelAutoStart: true` in Settings.
+
+## Login Flow
+
+- **Local access** (localhost, LAN): Admin password only
+- **Remote access** (via tunnel, `.trycloudflare.com`): Admin password + Session Code (2FA)
+
+Session code is generated when tunnel starts. Get it via:
+- Telegram: `/tunnel_code <password>`
+- CLI: `forge tcode`
+
+## Troubleshooting
+
+- **Tunnel stuck at "starting"**: Kill old cloudflared processes: `pkill -f cloudflared`
+- **URL not reachable**: Tunnel may have timed out, restart it
+- **Session cookie invalid after restart**: Set `AUTH_SECRET` in `~/.forge/data/.env.local`:
+  ```bash
+  echo "AUTH_SECRET=$(openssl rand -hex 32)" >> ~/.forge/data/.env.local
+  ```

package/.forge/worktrees/pipeline-4dd8dc2d/lib/help-docs/04-tasks.md

@@ -0,0 +1,52 @@
+# Background Tasks
+
+## What Are Tasks?
+
+Tasks run Claude Code prompts in the background. They use `claude -p` (print mode) — execute and exit, no persistent session. Your code runs on your machine using your Claude subscription.
+
+## Create a Task
+
+**From UI**: Click "+ New Task" in the Tasks tab.
+
+**From CLI**:
+```bash
+forge task my-project "fix the login bug"
+forge task my-project "add unit tests for utils.ts" --new  # fresh session
+```
+
+**From Telegram**: `/task my-project fix the login bug`
+
+## Task Modes
+
+| Mode | Description |
+|------|-------------|
+| `prompt` | Run Claude Code with a prompt (default) |
+| `shell` | Execute raw shell command |
+| `monitor` | Watch a session and trigger actions |
+
+## Watch Task Output
+
+```bash
+forge watch <task-id>    # live stream in terminal
+```
+
+Or from Telegram: `/watch <task-id>`
+
+## CLI Commands
+
+```bash
+forge tasks              # list all tasks
+forge tasks running      # filter by status
+forge status <id>        # task details
+forge cancel <id>        # cancel
+forge retry <id>         # retry failed task
+forge log <id>           # execution log
+```
+
+## Features
+
+- **Per-project concurrency**: One prompt task per project at a time, others queue
+- **Session continuity**: All tasks in the same project share one Claude conversation
+- **Cost tracking**: Token usage and USD cost per task
+- **Git tracking**: Captures branch name and git diff after execution
+- **Scheduled execution**: Set `scheduledAt` for deferred tasks