@aion0/forge 0.5.33 → 0.5.34

package/CLAUDE.md

@@ -60,6 +60,8 @@ When adding or changing a feature, check if `lib/help-docs/` needs updating. Eac
 - `08-rules.md` — CLAUDE.md templates
 - `09-issue-autofix.md` — GitHub issue scanner
 - `10-troubleshooting.md` — common issues
+- `11-workspace.md` — multi-agent workspace (smiths, daemon, request docs)
+- `12-usage.md` — token usage analytics and cost tracking
 If a feature change affects user-facing behavior, update the corresponding help doc in the same commit.
 
 ### Architecture

package/RELEASE_NOTES.md

@@ -1,8 +1,8 @@
-# Forge v0.5.33
+# Forge v0.5.34
 
 Released: 2026-04-10
 
-## Changes since v0.5.32
+## Changes since v0.5.33
 
 
-**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.5.32...v0.5.33
+**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.5.33...v0.5.34

package/lib/help-docs/00-overview.md

@@ -2,6 +2,22 @@
 
 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.
 
+## Main Features
+
+| Feature | Description |
+|---|---|
+| **Browser Terminal** | xterm.js + tmux persistence, split panes, mouse on/off toggle, auto-reconnect on disconnect |
+| **Projects** | File tree, Git operations, code search, per-project tabs, favorites |
+| **Workspace (Smiths)** | Multi-agent orchestration with DAG dependencies, message bus, request documents |
+| **Tasks** | Background AI task queue with hook-based completion notifications |
+| **Pipelines** | YAML-driven DAG workflows with scheduling and routing |
+| **Skills Marketplace** | Install/update Claude Code skills and slash commands per project |
+| **Usage Analytics** | Token/cost tracking by project, model, source with charts and heatmaps |
+| **Telegram Bot** | Mobile control — submit tasks, receive notifications |
+| **Remote Access** | One-click Cloudflare tunnel for remote browsing |
+| **GitHub Issue Auto-fix** | Scan issues, auto-fix, create PRs |
+| **Memory (optional)** | Code graph + knowledge via `@aion0/temper` MCP server |
+
 ## Quick Start
 
 ```bash

package/lib/help-docs/07-projects.md

@@ -40,6 +40,26 @@ Add project directories in Settings → **Project Roots** (e.g. `~/Projects`). F
 
 Click ★ next to a project to favorite it. Favorites appear at the top of the sidebar.
 
+## Sidebar & Navigation
+
+- **Collapse sidebar** (▶/◀ button): Narrow strip shows opened tabs at top (marked with green dot) and all other projects as initials below. Hover to show close (×) button on open tabs.
+- **Sidebar state is persisted** across browser refreshes via `localStorage`.
+- **Open projects** are marked with a green dot in the expanded sidebar; hover to reveal a close button.
+- **Close confirmation** prompts before closing a project tab to prevent accidental closes.
+- Up to **20 project tabs** stay mounted simultaneously (LRU eviction beyond that) — switching between recent projects is instant, terminal state is preserved.
+
+## Tree Views — Collapse All
+
+All hierarchical tree views have a `⇱` "Collapse all" button to quickly fold every folder:
+
+| Location | Button position |
+|---|---|
+| Project **Code** tab file tree | Right of "Files" label |
+| **Docs viewer** tree | Right of search box |
+| **Skills** panel file tree | Top of file tree |
+| **Workspace** sidebar | Header next to `+` |
+| **Session** list | Next to Batch button |
+
 ## Terminal
 
 ### Opening a Terminal

package/lib/help-docs/10-troubleshooting.md

@@ -39,6 +39,18 @@ rm ~/.forge/data/terminal-state.json
 # Restart server — tabs will be empty but tmux sessions survive
 ```
 
+### Terminal input is laggy
+Usually caused by high system load. Check:
+- System memory — if heavily swapping, kill some processes
+- Clean up old tmux sessions: `tmux list-sessions` then `tmux kill-session -t <name>`
+- Reduce polling: open tabs are limited to 20 by LRU eviction
+- Workspace terminals auto-reconnect on disconnect; no need to manually reopen
+
+### "Connection error" in workspace terminal
+The WebSocket dropped (system suspend, network blip). Forge auto-reconnects after 2s and re-attaches to the same tmux session. If it keeps happening:
+- Check `~/.forge/data/forge.log` for terminal-standalone errors
+- Restart: `forge server restart`
+
 ### gh CLI not authenticated (Issue Scanner)
 ```bash
 gh auth login

package/lib/help-docs/11-workspace.md

@@ -207,6 +207,24 @@ Agents use these MCP tools (via forge-mcp-server):
 | `mark_message_done` | Mark a processed message as done |
 | `check_outbox` | Check delivery status of sent messages |
 
+### Request vs Inbox — When to use which
+
+Every preset smith's role prompt includes a decision rule for this:
+
+**Use `create_request`** when:
+- Delegating substantive work (implement feature, write tests, do review)
+- Work has concrete deliverables and acceptance criteria
+- Work should flow through a pipeline (engineer → qa → reviewer)
+- The task needs to be tracked, claimed, and its status visible
+
+**Use `send_message`** when:
+- Asking a clarifying question
+- Quick status update or coordination
+- Reporting a bug back after review fails
+- No concrete deliverable
+
+**When unsure, prefer `create_request`** — a tracked artifact beats losing context in chat.
+
 ### Other
 
 | Tool | Description |
@@ -317,6 +335,31 @@ Click **⌨️** on any smith to open a terminal session:
 - Forge Skills available: `/forge-send`, `/forge-inbox`, `/forge-status`, `/forge-workspace-sync`
 - Session Picker: choose new session, continue existing, or browse all Claude sessions
 - Close terminal → smith returns to auto mode, pending messages resume
+- **Auto-reconnect**: If the WebSocket drops (e.g. system suspend, network blip), the terminal automatically reconnects after 2s and re-attaches to the same tmux session — conversation context preserved
+- **Mouse ON/OFF toggle** (🖱️ button in header): Toggle tmux mouse mode globally for all sessions
+  - **ON**: trackpad scroll, `Shift+drag` to select text
+  - **OFF**: drag to select text directly, `Ctrl+B [` to enter scroll mode
+  - Click to apply instantly (no restart needed)
+
+### Terminal Layout: Float vs Dock
+
+The workspace toolbar has a layout switcher: `⧉ Float` or `▤ Dock`.
+
+| Layout | Behavior |
+|---|---|
+| **Float** (default) | Each terminal is a draggable/resizable floating window positioned near its smith node |
+| **Dock** | All open terminals arranged in a fixed grid at the bottom of the workspace |
+
+Dock mode features:
+- Grid columns selector (1/2/3/4) — auto-expands based on open terminal count
+- 1 terminal with 4 columns → fills full width
+- 2 → half-half, 3 → thirds, 4 → quarters, 5+ → wraps to second row
+- Drag the top border to resize dock height
+- Layout preference persisted to localStorage
+
+### Smith Node Positions
+
+Drag smith nodes to reorganize the graph. Positions are **persisted to workspace state** and restored on reload. Auto-save debounces writes (500ms after drag stops).
 
 ## Watch (Autonomous Monitoring)
 
@@ -356,7 +399,7 @@ Agents can monitor file/git/command changes without message-driven triggers.
 
 Each smith can display an animated companion character next to its node.
 
-**Themes**: Stick figure, Cat, Dog, Pig, Emoji, Off (default)
+**Themes**: Stick figure, Cat, Pixel (8-bit RPG hero), Emoji, Off (default)
 
 - Theme picker in workspace header
 - Animates based on smith state (idle/running/done/failed/sleeping)
@@ -368,7 +411,7 @@ Each smith can display an animated companion character next to its node.
 | Action | Description |
 |--------|-------------|
 | **Start Daemon** | Launch all smiths, begin consuming messages |
-| **Stop Daemon** | Stop all smiths, kill workers |
+| **Stop Daemon** | Stop all smiths, kill workers. Preserves user's terminal conversation context (no `/clear` is sent). Tmux sessions attached to by a user are kept alive. |
 | **Run All** | Trigger all runnable agents once |
 | **Run** | Trigger specific agent |
 | **Pause/Resume** | Pause/resume message consumption for one agent |

package/lib/help-docs/12-usage.md

@@ -0,0 +1,103 @@
+# Usage Analytics
+
+Forge tracks Claude API token usage and estimated costs across all your projects.
+
+## Access
+
+Click **Usage** in the Dashboard top navigation.
+
+## Data Source
+
+Forge scans these sources on-demand (via **Scan Now** button) or automatically on startup:
+
+| Source | Location | What it tracks |
+|---|---|---|
+| `claude-code` | `~/.claude/projects/*/` | Interactive Claude Code sessions |
+| `forge-task` | `~/.forge/data/tasks.db` | Background tasks submitted through Forge |
+| `api-direct` | SDK/API calls logged by Forge | Direct API calls (rare) |
+
+Stored in `~/.forge/data/usage.db` (SQLite). Each row records: session_id, source, project, model, day, input/output/cache tokens, cost_usd, message_count.
+
+## Time Range Filter
+
+Buttons in the header: **7d / 30d / 90d / All** — filter all charts and tables.
+
+## Summary Cards
+
+| Card | Shows |
+|---|---|
+| **Total Cost** | Sum of `cost_usd` in the selected range + trend (↑/↓ vs previous half) |
+| **Daily Avg** | Total cost divided by days with activity |
+| **Tokens** | Total tokens (input + output + cache read), broken down below |
+| **Cache Hit** | `cacheRead / (input + cacheRead) × 100%` + cached tokens count |
+
+## Visualizations
+
+### Token Mix (stacked bar)
+A single horizontal bar showing the proportion of:
+- 🔵 Input tokens
+- 🟢 Output tokens
+- 🟣 Cache read tokens
+- 🟠 Cache create tokens
+
+Hover for tooltip.
+
+### Cost Trend (line chart)
+Line chart of daily cost over the selected range. Y-axis auto-scales to max cost. X-axis labels shown for ~7 date points.
+
+### Activity Heatmap
+GitHub-style 90-day grid: rows are weekdays (S/M/T/W/T/F/S), columns are weeks. Darker blue = higher cost. Hover a cell for exact date and cost.
+
+### Avg by Weekday
+Bar chart showing the average daily cost per weekday. Weekends highlighted in orange, weekdays in blue.
+
+### By Model / By Source (donut charts)
+Two side-by-side donut charts splitting total cost by model (Opus, Sonnet, Haiku) and by source (claude-code, forge-task, api-direct). Shows percentage + absolute cost per slice.
+
+### By Project (bar list)
+Top 20 projects ranked by cost. Each row shows project name, relative bar, cost, and session count.
+
+### Model Details (table)
+Per-model breakdown:
+- Input / Output tokens
+- Cost
+- Message count
+- Avg cost per message
+
+### Summary Stats (bottom 3 cards)
+- **Avg per session** — total cost / session count
+- **Avg per message** — total cost / message count
+- **Sessions per day** — session count / days with activity
+
+## Cost Calculation
+
+Estimates based on public Anthropic API pricing:
+
+| Model | Input | Output |
+|---|---|---|
+| Claude Opus 4 | $15/M | $75/M |
+| Claude Sonnet 4 | $3/M | $15/M |
+| Claude Haiku 4 | ~$0.80/M | ~$4/M |
+
+Cache reads are ~90% cheaper than regular inputs (~$0.30/M for Opus).
+
+> Actual cost may differ if you're on Claude Max/Pro subscription (fixed monthly), or using Bedrock/Vertex with different pricing.
+
+## Actions
+
+- **Scan Now** — Re-scans all JSONL session files and tasks.db, updates the database
+- **Time range** — 7/30/90/All days
+
+## Troubleshooting
+
+### Usage shows $0
+- No data yet — click **Scan Now**
+- Check `~/.claude/projects/` has JSONL session files
+- Check `~/.forge/data/tasks.db` exists and has rows
+- Check `~/.forge/data/usage.db` has data: `sqlite3 ~/.forge/data/usage.db 'SELECT COUNT(*) FROM token_usage'`
+
+### Wrong project name
+Usage scanner derives project name from directory path. Rename via scan refresh after moving projects.
+
+### Missing recent sessions
+Sessions in progress aren't tracked until the file is flushed. Click **Scan Now** to force a refresh.

package/lib/help-docs/CLAUDE.md

@@ -42,6 +42,7 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 | `09-issue-autofix.md` | GitHub issue auto-fix pipeline |
 | `10-troubleshooting.md` | Common issues and solutions |
 | `11-workspace.md` | Workspace (Forge Smiths) — multi-agent orchestration, daemon, message bus, profiles |
+| `12-usage.md` | Token usage analytics — charts, heatmap, cost estimation, by model/project/source |
 
 ## Matching questions to docs
 
@@ -60,3 +61,6 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 - Watch/monitor/detect/file changes/autonomous → `11-workspace.md`
 - Agent profile/env/model/cliType → `01-settings.md` + `11-workspace.md`
 - Agent log/logs/history/clear logs → `11-workspace.md`
+- Usage/cost/tokens/spending/billing/analytics → `12-usage.md`
+- Terminal dock/float/mouse toggle/reconnect → `07-projects.md` + `11-workspace.md`
+- Sidebar collapse/project tabs/favorites → `07-projects.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.5.33",
+  "version": "0.5.34",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {