@aion0/forge 0.6.1 → 0.6.3

package/.forge/worktrees/pipeline-44a94121/lib/forge-skills/forge-inbox.md

@@ -1,38 +0,0 @@
----
-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-44a94121/lib/forge-skills/forge-send.md

@@ -1,47 +0,0 @@
----
-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-44a94121/lib/forge-skills/forge-status.md

@@ -1,32 +0,0 @@
----
-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-44a94121/lib/forge-skills/forge-workspace-sync.md

@@ -1,37 +0,0 @@
----
-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-44a94121/lib/help-docs/00-overview.md

@@ -1,40 +0,0 @@
-# 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-44a94121/lib/help-docs/01-settings.md

@@ -1,194 +0,0 @@
-# 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-44a94121/lib/help-docs/02-telegram.md

@@ -1,41 +0,0 @@
-# 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-44a94121/lib/help-docs/03-tunnel.md

@@ -1,31 +0,0 @@
-# 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-44a94121/lib/help-docs/04-tasks.md

@@ -1,52 +0,0 @@
-# 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