@aion0/forge 0.3.4 → 0.3.6

package/components/TabBar.tsx

@@ -0,0 +1,46 @@
+'use client';
+
+import React from 'react';
+
+export interface Tab {
+  id: number;
+  label: string;
+}
+
+export interface TabBarProps {
+  tabs: Tab[];
+  activeId: number;
+  onActivate: (id: number) => void;
+  onClose: (id: number) => void;
+}
+
+export default function TabBar({ tabs, activeId, onActivate, onClose }: TabBarProps) {
+  if (tabs.length === 0) return null;
+
+  return (
+    <div className="flex items-center border-b border-[var(--border)] bg-[var(--bg-tertiary)] overflow-x-auto shrink-0">
+      {tabs.map(tab => (
+        <div
+          key={tab.id}
+          className={`flex items-center gap-1 px-3 py-1.5 text-[11px] cursor-pointer border-r border-[var(--border)]/30 shrink-0 group ${
+            tab.id === activeId
+              ? 'bg-[var(--bg-primary)] text-[var(--text-primary)] border-b-2 border-b-[var(--accent)]'
+              : 'text-[var(--text-secondary)] hover:bg-[var(--bg-secondary)] hover:text-[var(--text-primary)]'
+          }`}
+          onClick={() => onActivate(tab.id)}
+        >
+          <span className="truncate max-w-[120px]">{tab.label}</span>
+          <button
+            onClick={(e) => {
+              e.stopPropagation();
+              onClose(tab.id);
+            }}
+            className="text-[9px] w-4 h-4 flex items-center justify-center rounded hover:bg-[var(--bg-tertiary)] text-[var(--text-secondary)] hover:text-[var(--text-primary)] opacity-0 group-hover:opacity-100 shrink-0"
+          >
+            x
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,34 @@
+# Forge Overview
+
+Forge is a self-hosted Vibe Coding platform for Claude Code. It provides a browser-based terminal, AI task orchestration, remote access, and mobile control via Telegram.
+
+## Quick Start
+
+```bash
+npm install -g @aion0/forge
+forge server start
+```
+
+Open `http://localhost:3000`. 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)
+- Claude: `~/.claude/` (skills, commands, sessions)
+
+## 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/lib/help-docs/01-settings.md

@@ -0,0 +1,37 @@
+# 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 |
+| `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 |
+
+## Admin Password
+
+- Set on first launch (CLI prompt)
+- Required for: login, tunnel start, secret changes, Telegram commands
+- Reset: `forge --reset-password`
+- Forgot? Run `forge --reset-password` in terminal
+
+## Encrypted Fields
+
+`telegramBotToken` and `telegramTunnelPassword` are encrypted with AES-256-GCM. The encryption key is stored at `~/.forge/data/.encrypt-key`.

package/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/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/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

package/lib/help-docs/05-pipelines.md

@@ -0,0 +1,73 @@
+# Pipelines (Workflows)
+
+## What Are Pipelines?
+
+Pipelines chain multiple tasks into a DAG (directed acyclic graph). Each step can depend on previous steps, pass outputs forward, and run in parallel.
+
+## YAML Workflow Format
+
+```yaml
+name: my-workflow
+description: "What this workflow does"
+input:
+  feature: "Feature description"
+vars:
+  project: my-app
+nodes:
+  design:
+    project: "{{vars.project}}"
+    prompt: "Design: {{input.feature}}"
+    outputs:
+      - name: spec
+        extract: result
+  implement:
+    project: "{{vars.project}}"
+    depends_on: [design]
+    prompt: "Implement: {{nodes.design.outputs.spec}}"
+  review:
+    project: "{{vars.project}}"
+    depends_on: [implement]
+    prompt: "Review the changes"
+```
+
+## Node Options
+
+| Field | Description |
+|-------|-------------|
+| `project` | Project name (supports `{{vars.xxx}}` templates) |
+| `prompt` | Claude Code prompt or shell command |
+| `mode` | `claude` (default) or `shell` |
+| `branch` | Auto-checkout branch before running |
+| `depends_on` | List of node IDs that must complete first |
+| `outputs` | Extract results: `result`, `git_diff`, or `stdout` |
+| `routes` | Conditional routing to next nodes |
+
+## Template Variables
+
+- `{{input.xxx}}` — pipeline input values
+- `{{vars.xxx}}` — workflow variables
+- `{{nodes.xxx.outputs.yyy}}` — outputs from previous nodes
+
+## Built-in Workflows
+
+### issue-auto-fix
+Fetches a GitHub issue → fixes code on new branch → creates PR.
+
+Input: `issue_id`, `project`, `base_branch` (optional)
+
+### pr-review
+Fetches PR diff → AI code review → posts result.
+
+Input: `pr_number`, `project`
+
+## CLI
+
+```bash
+forge flows              # list available workflows
+forge run my-workflow    # execute a workflow
+```
+
+## Storage
+
+- Workflow YAML: `~/.forge/data/flows/`
+- Execution state: `~/.forge/data/pipelines/`

package/lib/help-docs/06-skills.md

@@ -0,0 +1,43 @@
+# Skills Marketplace
+
+## Overview
+
+Browse, install, and manage Claude Code skills and commands from the Forge Skills registry.
+
+## Types
+
+| | Skills | Commands |
+|---|---|---|
+| Location | `~/.claude/skills/<name>/` | `~/.claude/commands/<name>.md` |
+| Entry file | `SKILL.md` | Single `.md` file |
+| Complexity | Multi-file with templates | Simple slash command |
+
+Both register as `/slash-command` in Claude Code.
+
+## Install
+
+1. Go to **Skills** tab in Forge
+2. Click **Sync** to fetch latest registry
+3. Click **Install** on any skill → choose Global or specific project
+4. Use in Claude Code with `/<skill-name>`
+
+## Update
+
+Skills with newer versions show a yellow "update" indicator. Click to update (checks for local modifications first).
+
+## Local Skills
+
+The **Local** tab shows skills/commands installed on your machine (both from marketplace and manually created). You can:
+- **Install to...** — Copy a local skill to another project or global
+- **Delete** — Remove from project or global
+- **Edit** — View and modify installed files
+
+## Registry
+
+Default: `https://raw.githubusercontent.com/aiwatching/forge-skills/main`
+
+Change in Settings → Skills Repo URL.
+
+## Custom Skills
+
+Create your own: put a `.md` file in `<project>/.claude/commands/` or a directory in `<project>/.claude/skills/<name>/`.

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

@@ -0,0 +1,39 @@
+# Projects
+
+## Setup
+
+Add project directories in Settings → **Project Roots** (e.g. `~/Projects`). Forge scans subdirectories automatically.
+
+## Features
+
+### Code Tab
+- File tree browser
+- Syntax-highlighted code viewer
+- Git diff view (click changed files)
+- Git operations: commit, push, pull
+- Commit history
+
+### Skills & Commands Tab
+- View installed skills/commands for this project
+- Scope indicator: G (global), P (project), G+P (both)
+- Edit files, update from marketplace, uninstall
+
+### CLAUDE.md Tab
+- View and edit project's CLAUDE.md
+- Apply rule templates (built-in or custom)
+- Templates auto-injected with dedup markers
+
+### Issues Tab
+- Enable GitHub Issue Auto-fix per project
+- Configure scan interval and label filters
+- Manual trigger: enter issue # and click Fix Issue
+- Processed issues history with retry/delete
+- Auto-chains: fix → create PR → review
+
+## Favorites
+
+Click ★ next to a project to favorite it. Favorites appear at the top of the sidebar.
+
+## Terminal
+
+Click "Terminal" button in project header to open a Vibe Coding terminal for that project. Uses `claude -c` to continue last session.

package/lib/help-docs/08-rules.md

@@ -0,0 +1,53 @@
+# Rules (CLAUDE.md Templates)
+
+## What Are Rules?
+
+Reusable markdown snippets that get appended to project CLAUDE.md files. They define coding conventions, security rules, workflow guidelines, etc.
+
+## Built-in Templates
+
+| Template | Description |
+|----------|-------------|
+| TypeScript Rules | Coding conventions (const, types, early returns) |
+| Git Workflow | Commit messages, branch naming |
+| Obsidian Vault | Vault integration instructions |
+| Security Rules | OWASP guidelines, no hardcoded secrets |
+
+## Manage Rules
+
+**Skills tab → Rules sub-tab**:
+- View all templates (built-in + custom)
+- Create new: click "+ New"
+- Edit any template (including built-in)
+- Delete custom templates
+- Set as "default" — auto-applied to new projects
+- Batch apply: select template → check projects → click "Apply"
+
+## Apply to Project
+
+**Project → CLAUDE.md tab**:
+- Left sidebar shows CLAUDE.md content + template list
+- Click "+ add" to inject a template
+- Click "added" to remove
+- Templates wrapped in `<!-- forge:template:id -->` markers (prevents duplicate injection)
+
+## Default Templates
+
+Templates marked as "default" are automatically injected into new projects when they first appear in the project list.
+
+## Custom Templates
+
+Stored in `~/.forge/data/claude-templates/`. Each is a `.md` file with YAML frontmatter:
+
+```markdown
+---
+name: My Rule
+description: What this rule does
+tags: [category]
+builtin: false
+isDefault: false
+---
+
+## My Custom Rule
+Your content here...
+```

package/lib/help-docs/09-issue-autofix.md

@@ -0,0 +1,51 @@
+# Issue Auto-fix
+
+## Overview
+
+Automatically scan GitHub Issues, fix code, create PRs, and review — all hands-free.
+
+## Prerequisites
+
+- `gh` CLI installed and authenticated: `gh auth login`
+- Project has a GitHub remote
+
+## Setup
+
+1. Go to **Projects → select project → Issues tab**
+2. Enable **Issue Auto-fix**
+3. Configure:
+   - **Scan Interval**: minutes between scans (0 = manual only)
+   - **Base Branch**: leave empty for auto-detect (main/master)
+   - **Labels Filter**: comma-separated labels (empty = all issues)
+4. Click **Scan Now** to test
+
+## Flow
+
+```
+Scan → Fetch Issue → Fix Code (new branch) → Push → Create PR → Auto Review → Notify
+```
+
+1. **Scan**: `gh issue list` finds open issues matching labels
+2. **Fix**: Claude Code analyzes issue and fixes code on `fix/<id>-<description>` branch
+3. **PR**: Pushes branch and creates Pull Request
+4. **Review**: Automatically triggers `pr-review` pipeline
+5. **Notify**: Results sent via Telegram (if configured)
+
+## Manual Trigger
+
+Enter an issue number in "Manual Trigger" section and click "Fix Issue".
+
+## Retry
+
+Failed fixes show a "Retry" button. Click to provide additional context (e.g. "rebase from main first") and re-run.
+
+## Safety
+
+- Checks for uncommitted changes before starting (aborts if dirty)
+- Always works on new branches (never modifies main)
+- Switches back to original branch after completion
+- Existing PRs are updated, not duplicated
+
+## Processed Issues
+
+History shows all processed issues with status (processing/done/failed), PR number, and pipeline ID. Click pipeline ID to view details.

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

@@ -0,0 +1,82 @@
+# Troubleshooting
+
+## Common Issues
+
+### "fork failed: Device not configured" (macOS)
+PTY device limit exhausted:
+```bash
+sudo sysctl kern.tty.ptmx_max=2048
+echo 'kern.tty.ptmx_max=2048' | sudo tee -a /etc/sysctl.conf
+```
+
+### Session cookie invalid after restart
+Fix AUTH_SECRET so it persists:
+```bash
+echo "AUTH_SECRET=$(openssl rand -hex 32)" >> ~/.forge/data/.env.local
+```
+
+### Orphan processes after Ctrl+C
+Use `forge server stop` or:
+```bash
+pkill -f 'telegram-standalone|terminal-standalone|next-server|cloudflared'
+```
+
+### Tunnel stuck at "starting"
+```bash
+pkill -f cloudflared
+# Then restart tunnel from UI or Telegram
+```
+
+### Forgot admin password
+```bash
+forge --reset-password
+```
+
+### Terminal tabs lost after restart
+Terminal state is saved in `~/.forge/data/terminal-state.json`. If corrupted:
+```bash
+rm ~/.forge/data/terminal-state.json
+# Restart server — tabs will be empty but tmux sessions survive
+```
+
+### gh CLI not authenticated (Issue Scanner)
+```bash
+gh auth login
+```
+
+### Skills not syncing
+Click "Sync" in Skills tab. Check `skillsRepoUrl` in Settings points to valid registry.
+
+### Multiple instances conflict
+Use different ports and data directories:
+```bash
+forge server start --port 4000 --dir ~/.forge/data_demo
+forge server stop --port 4000 --dir ~/.forge/data_demo
+```
+
+### Page shows "Failed to load chunk"
+Clear build cache:
+```bash
+rm -rf .next
+pnpm build  # or forge server rebuild
+```
+
+## Logs
+
+- Background server: `~/.forge/data/forge.log`
+- Dev mode: terminal output
+- View with: `tail -f ~/.forge/data/forge.log`
+
+## Reset Everything
+
+```bash
+# Stop server
+forge server stop
+
+# Reset password
+forge --reset-password
+
+# Clear all data (nuclear option)
+rm -rf ~/.forge/data
+# Restart — will create fresh data directory
+```

package/lib/settings.ts

@@ -26,6 +26,7 @@ export interface Settings {
   skillsRepoUrl: string;              // GitHub raw URL for skills registry
   displayName: string;                  // User display name (shown in header)
   displayEmail: string;                 // User email (for session/future integrations)
+  favoriteProjects: string[];           // Favorite project paths (shown at top of sidebar)
 }
 
 const defaults: Settings = {
@@ -47,6 +48,7 @@ const defaults: Settings = {
   skillsRepoUrl: 'https://raw.githubusercontent.com/aiwatching/forge-skills/main',
   displayName: 'Forge',
   displayEmail: '',
+  favoriteProjects: [],
 };
 
 /** Load settings with secrets decrypted (for internal use) */

package/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/dev/types/routes.d.ts";
+import "./.next/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/package.json

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

package/src/core/db/database.ts

@@ -149,6 +149,18 @@ function initSchema(db: Database.Database) {
       synced_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 
+    -- Tab state (projects, docs, etc)
+    CREATE TABLE IF NOT EXISTS tab_state (
+      type TEXT PRIMARY KEY,
+      data TEXT NOT NULL DEFAULT '{}'
+    );
+
+    -- Project favorites
+    CREATE TABLE IF NOT EXISTS project_favorites (
+      project_path TEXT PRIMARY KEY,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
     -- Session watchers — monitor sessions and notify via Telegram
     CREATE TABLE IF NOT EXISTS session_watchers (
       id TEXT PRIMARY KEY,