@aion0/forge 0.2.2 → 0.2.4

package/CLAUDE.md

@@ -19,11 +19,15 @@ npm install -g /Users/zliu/IdeaProjects/my-workflow
 npm install -g @aion0/forge
 
 # Run via npm global install
-forge-server              # foreground (auto-builds if needed)
-forge-server --dev        # dev mode
-forge-server --background # background, logs to ~/.forge/forge.log
-forge-server --stop       # stop background server
-forge-server --rebuild    # force rebuild
+forge-server                          # foreground (default port 3000)
+forge-server --dev                    # dev mode
+forge-server --background             # background, logs to ~/.forge/forge.log
+forge-server --stop                   # stop background server
+forge-server --restart                # stop + start (safe for remote)
+forge-server --rebuild                # force rebuild
+forge-server --port 4000              # custom web port
+forge-server --terminal-port 4001     # custom terminal port
+forge-server --dir ~/.forge-staging   # custom data directory
 
 # CLI
 forge                     # help

package/README.md

@@ -1,42 +1,51 @@
-# Forge
+<p align="center">
+  <img src="app/icon.svg" width="80" height="80" alt="Forge">
+</p>
 
-> Self-hosted AI workflow platform — web terminal, task orchestration, remote access.
+<h1 align="center">Forge</h1>
 
-Forge is a self-hosted web platform built around [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a browser-based terminal backed by tmux, a task queue for running Claude Code in the background, and one-click remote access via Cloudflare Tunnel — all behind a simple daily-rotating password.
+<p align="center">
+  <strong>Self-hosted Vibe Coding platform — browser terminal, task orchestration, remote access</strong>
+</p>
 
-No API keys required. Forge runs on your existing Claude Code subscription.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@aion0/forge"><img src="https://img.shields.io/npm/v/@aion0/forge" alt="npm"></a>
+  <a href="https://github.com/aiwatching/forge/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@aion0/forge" alt="license"></a>
+  <a href="https://github.com/aiwatching/forge"><img src="https://img.shields.io/github/stars/aiwatching/forge?style=social" alt="stars"></a>
+</p>
 
-## Features
+<p align="center">
+  <a href="#installation">Install</a> · <a href="#features">Features</a> · <a href="#quick-start">Quick Start</a> · <a href="#telegram-bot">Telegram</a> · <a href="#configuration">Config</a> · <a href="#roadmap">Roadmap</a>
+</p>
 
-- **Web Terminal** — Full tmux-backed terminal in the browser. Multiple tabs, persistent sessions that survive page refresh, browser close, and server restart
-- **Task Orchestration** — Submit tasks to Claude Code, queue them by project, track progress with live streaming output
-- **Remote Access** — One-click Cloudflare Tunnel for a secure public URL (zero config, no account needed)
-- **Session Continuity** — Tasks for the same project automatically continue the previous conversation context
-- **YAML Workflows** — Define multi-step flows that chain tasks together
-- **Bot Integration** — Telegram bot for mobile task management and tunnel control (extensible to other platforms)
-- **Session Watcher** — Monitor Claude Code sessions for changes, idle state, keywords, or errors
-- **CLI** — Full-featured command-line interface for task management
-- **Auth** — Auto-generated daily rotating password + optional Google OAuth
+---
 
-## Prerequisites
+Forge turns [Claude Code](https://docs.anthropic.com/en/docs/claude-code) into a full web-based vibe coding platform. Open your browser, start coding with AI from anywhere — your iPad, phone, or any device with a browser.
 
-- **Node.js** >= 20
-- **pnpm** (recommended) or npm
-- **tmux** — for web terminal sessions
-- **Claude Code CLI** — `npm install -g @anthropic-ai/claude-code`
+**No API keys required.** Runs on your existing Claude Code CLI subscription. Your code stays on your machine.
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Vibe Coding** | Browser-based tmux terminal. Multiple tabs, persistent sessions that survive refresh, browser close, and server restart |
+| **Remote Access** | One-click Cloudflare Tunnel — secure public URL, zero config, no account needed |
+| **Task Queue** | Submit tasks to Claude Code in the background. Live streaming output, cost tracking, session continuity |
+| **Docs Viewer** | Render Obsidian vaults / markdown directories with a dedicated Claude Console |
+| **Project Manager** | Browse projects, view files, git status, commit, push, pull — all from the browser |
+| **Demo Preview** | Preview local dev servers through the tunnel with a dedicated Cloudflare URL |
+| **Telegram Bot** | Submit tasks, check status, control tunnel, take notes — all from your phone |
+| **File Browser** | Code viewer with syntax highlighting, git changes, diff view, multi-repo support |
+| **YAML Workflows** | Define multi-step flows that chain Claude Code tasks together |
+| **CLI** | Full command-line interface for task management |
 
 ## Installation
 
-### From npm
+### npm (recommended)
 
 ```bash
 npm install -g @aion0/forge
-
-# Start the server
 forge-server
-
-# Or in development mode
-forge-server --dev
 ```
 
 ### From source
@@ -48,224 +57,206 @@ pnpm install
 pnpm dev
 ```
 
-## Quick Start
-
-### 1. Log in
-
-Open `http://localhost:3000`. A login password is auto-generated and printed in the console:
-
-```
-[init] Login password: a7x9k2 (valid today)
-```
-
-The password rotates daily. Forgot it? Run:
+### Options
 
 ```bash
-forge password
+forge-server              # Production (auto-builds if needed)
+forge-server --dev        # Development with hot-reload
+forge-server --background # Run in background, logs to ~/.forge/forge.log
+forge-server --stop       # Stop background server
+forge-server --rebuild    # Force rebuild
 ```
 
-### 4. Configure projects
-
-Open **Settings** (gear icon) and add your project root directories (e.g. `~/Projects`). Forge will scan for git repositories automatically.
-
-## Web Terminal
-
-The core feature. A browser-based terminal powered by tmux:
-
-- **Persistent** — Sessions survive page refresh, browser close, and server restart
-- **Multi-tab** — Create, rename, and manage multiple terminal tabs
-- **Remote-ready** — Access your terminal from anywhere via Cloudflare Tunnel
-- **Large scrollback** — 50,000 lines with mouse support
-
-The terminal server runs on `localhost:3001` and is auto-proxied through the main app for remote access.
-
-## Remote Access (Cloudflare Tunnel)
-
-Access Forge from anywhere without port forwarding or DNS config:
-
-1. Click the **tunnel icon** in the header bar, or go to **Settings > Remote Access**
-2. Click **Start** — Forge auto-downloads `cloudflared` and creates a temporary public URL
-3. The URL is protected by the daily login password
-
-Enable **Auto-start** in Settings to start the tunnel on every server boot.
-
-> The tunnel URL changes each time. Use the Telegram bot `/tunnel_password` command to get the current URL and password on your phone.
-
-## Task Orchestration
-
-Submit AI coding tasks that run in the background:
+## Prerequisites
 
-```bash
-# Submit a task
-forge task my-app "Fix the login bug in auth.ts"
+- **Node.js** >= 20
+- **tmux** — `brew install tmux` (macOS) / `apt install tmux` (Linux)
+- **Claude Code CLI** — `npm install -g @anthropic-ai/claude-code`
 
-# Force a fresh session (ignore previous context)
-forge task my-app "Refactor the API layer" --new
+## Quick Start
 
-# List tasks
-forge tasks              # all
-forge tasks running      # filter by status
+1. **Start Forge**
 
-# Watch task output live
-forge watch <task-id>
+   ```bash
+   forge-server
+   ```
 
-# Task details (result, git diff, cost)
-forge status <task-id>
+2. **Open browser** → `http://localhost:3000`
 
-# Cancel / retry
-forge cancel <task-id>
-forge retry <task-id>
-```
+3. **Log in** — password is auto-generated and printed in the console:
 
-**All CLI shortcuts:** `t`=task, `r`=run, `ls`=tasks, `w`=watch, `l`=log, `s`=status, `f`=flows, `p`=projects, `pw`=password
+   ```
+   [init] Login password: a7x9k2 (valid today)
+   ```
 
-## YAML Workflows
+   Forgot it? Run `forge password`
 
-Define multi-step flows in `~/.forge/flows/`:
+4. **Configure projects** — Settings → add your project directories
 
-```yaml
-# ~/.forge/flows/daily-review.yaml
-name: daily-review
-steps:
-  - project: my-app
-    prompt: "Review open TODOs and suggest fixes"
-  - project: my-api
-    prompt: "Check for any failing tests and fix them"
-```
+5. **Start vibe coding** — open a terminal tab, run `claude`, and go
 
-Run with `forge run daily-review`.
+## Remote Access
 
-## Bot Integration
+Access Forge from anywhere — your phone, iPad, or another computer:
 
-Forge ships with a Telegram bot for mobile-friendly control. The bot system is designed to be extensible to other platforms in the future.
+1. Click the **tunnel button** in the header
+2. Forge auto-downloads `cloudflared` and creates a temporary public URL
+3. Open the URL on any device — protected by the daily login password
 
-### Telegram Setup
+> The tunnel URL changes each time. Use the Telegram `/tunnel_password` command to get it on your phone.
 
-1. Create a bot via [@BotFather](https://t.me/botfather)
-2. In **Settings**, add your **Bot Token** and **Chat ID**
-3. Optionally set a **Tunnel Password** for remote access control
+## Telegram Bot
 
-### Commands
+Control Forge from your phone. Create a bot via [@BotFather](https://t.me/botfather), add the token in Settings.
 
 | Command | Description |
 |---------|-------------|
+| `/task` | Create a task (interactive project picker) |
 | `/tasks` | List tasks with quick-action numbers |
-| `/tasks running` | Filter by status |
-| `/sessions` | Browse Claude Code sessions |
-| `/watch <project>` | Monitor a session for changes |
-| `/tunnel start <pw>` | Start Cloudflare Tunnel |
-| `/tunnel stop <pw>` | Stop tunnel |
+| `/peek` | AI summary of a Claude session |
+| `/docs` | Docs session summary or file search |
+| `/note` | Quick note — sent to Docs Claude |
+| `/tunnel_start` | Start Cloudflare Tunnel |
+| `/tunnel_stop` | Stop tunnel |
 | `/tunnel_password <pw>` | Get login password + tunnel URL |
-| `/help` | Show all commands |
 
-Password-protected commands auto-delete your message to keep credentials safe.
+Whitelist-protected — only configured Chat IDs can interact with the bot.
 
-## Configuration
-
-All config lives in `~/.forge/`:
+## CLI
 
-```
-~/.forge/
-  .env.local           # Environment variables (AUTH_SECRET, API keys, etc.)
-  settings.yaml        # Main configuration
-  password.json        # Daily auto-generated login password
-  data.db              # SQLite database (tasks, sessions)
-  terminal-state.json  # Terminal tab layout
-  flows/               # YAML workflow definitions
-  bin/                 # Auto-downloaded binaries (cloudflared)
+```bash
+forge task <project> <prompt>   # Submit a task
+forge tasks [status]            # List tasks
+forge watch <id>                # Live stream output
+forge status <id>               # Task details + result
+forge cancel <id>               # Cancel a task
+forge retry <id>                # Retry a failed task
+forge run <flow-name>           # Run a YAML workflow
+forge projects                  # List projects
+forge password                  # Show login password
 ```
 
-### .env.local (optional)
+Shortcuts: `t`=task, `ls`=tasks, `w`=watch, `s`=status, `f`=flows, `p`=projects, `pw`=password
 
-```env
-# Fixed auth secret (optional — auto-generated if not set)
-AUTH_SECRET=<random-string>
+## Configuration
 
-# Optional: AI provider API keys for multi-model chat
-# ANTHROPIC_API_KEY=sk-ant-...
-# OPENAI_API_KEY=sk-...
-# GOOGLE_GENERATIVE_AI_API_KEY=AI...
+All data lives in `~/.forge/`:
+
+```
+~/.forge/
+├── .env.local            # Environment variables (optional)
+├── settings.yaml         # Main configuration
+├── password.json         # Daily auto-generated password
+├── data.db               # SQLite database
+├── terminal-state.json   # Terminal tab layout
+├── preview.json          # Demo preview config
+├── flows/                # YAML workflow definitions
+└── bin/                  # Auto-downloaded binaries
 ```
 
-### settings.yaml
+<details>
+<summary><strong>settings.yaml</strong></summary>
 
 ```yaml
-# Project directories to scan
 projectRoots:
   - ~/Projects
-  - ~/Work
-
-# Claude Code binary path (default: claude)
+docRoots:
+  - ~/Documents/obsidian-vault
 claudePath: claude
+tunnelAutoStart: false
+telegramBotToken: ""
+telegramChatId: ""              # Comma-separated for multiple users
+telegramTunnelPassword: ""
+notifyOnComplete: true
+notifyOnFailure: true
+```
 
-# Cloudflare Tunnel
-tunnelAutoStart: false              # Auto-start on server boot
+</details>
 
-# Telegram bot (optional)
-telegramBotToken: ""                # Bot API token from @BotFather
-telegramChatId: ""                  # Your chat ID
-telegramTunnelPassword: ""          # Password for tunnel commands
+<details>
+<summary><strong>.env.local</strong> (optional)</summary>
 
-# Task notifications (optional, requires Telegram)
-notifyOnComplete: true
-notifyOnFailure: true
+```env
+# Fixed auth secret (auto-generated if not set)
+AUTH_SECRET=<random-string>
+
+# Optional: AI provider API keys for multi-model chat
+# ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
 ```
 
+</details>
+
 ## Architecture
 
 ```
-┌─────────────────────────────────────────────┐
-│  Web Dashboard (Next.js + React)            │
-│  ┌──────────┐ ┌──────────┐ ┌─────────────┐ │
-│  │  Tasks   │ │ Sessions │ │  Terminal   │ │
-│  └──────────┘ └──────────┘ └─────────────┘ │
-├─────────────────────────────────────────────┤
-│  API Layer (Next.js Route Handlers)         │
-├──────────┬──────────┬───────────────────────┤
-│  Claude  │  Task    │  Bot Integration      │
-│  Code    │  Runner  │  (Telegram, ...)      │
-│  Process │  (Queue) │                       │
-├──────────┴──────────┴───────────────────────┤
-│  SQLite (better-sqlite3)                    │
-├─────────────────────────────────────────────┤
-│  Terminal Server (node-pty + tmux + WS)     │
-├─────────────────────────────────────────────┤
-│  Cloudflare Tunnel (optional)               │
-└─────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────┐
+│  Web Dashboard (Next.js 16 + React 19)           │
+│  ┌─────────┐ ┌──────┐ ┌────────┐ ┌───────────┐  │
+│  │  Vibe   │ │ Docs │ │Projects│ │Demo       │  │
+│  │ Coding  │ │      │ │        │ │Preview    │  │
+│  └─────────┘ └──────┘ └────────┘ └───────────┘  │
+├──────────────────────────────────────────────────┤
+│  API Layer (Next.js Route Handlers)              │
+├───────────┬───────────┬──────────────────────────┤
+│  Claude   │  Task     │  Telegram Bot            │
+│  Code     │  Runner   │  + Notifications         │
+│  Process  │  (Queue)  │                          │
+├───────────┴───────────┴──────────────────────────┤
+│  SQLite · Terminal Server · Cloudflare Tunnel    │
+└──────────────────────────────────────────────────┘
 ```
 
 ## Tech Stack
 
 | Layer | Technology |
 |-------|-----------|
-| Frontend | Next.js 16, React 19, Tailwind CSS 4 |
-| Backend | Next.js Route Handlers, SQLite |
-| Terminal | xterm.js, node-pty, tmux, WebSocket |
-| Auth | NextAuth v5 |
-| Tunnel | Cloudflare (cloudflared) |
-| Bot | Telegram Bot API (extensible) |
+| Frontend | Next.js 16, React 19, Tailwind CSS 4, xterm.js |
+| Backend | Next.js Route Handlers, SQLite (better-sqlite3) |
+| Terminal | node-pty, tmux, WebSocket |
+| Auth | NextAuth v5 (daily rotating password + OAuth) |
+| Tunnel | Cloudflare cloudflared (zero-config) |
+| Bot | Telegram Bot API |
 
 ## Troubleshooting
 
-### macOS: "fork failed: Device not configured"
+<details>
+<summary><strong>macOS: "fork failed: Device not configured"</strong></summary>
 
-This means the system ran out of pseudo-terminal (PTY) devices. macOS defaults to 511, which can be tight when running IDEs and many terminal sessions. Increase the limit:
+PTY device limit exhausted. Increase it:
 
 ```bash
-# Temporary (until reboot)
 sudo sysctl kern.tty.ptmx_max=2048
 
 # Permanent
 echo 'kern.tty.ptmx_max=2048' | sudo tee -a /etc/sysctl.conf
 ```
 
+</details>
+
+<details>
+<summary><strong>Session cookie invalid after restart</strong></summary>
+
+Fix the AUTH_SECRET so it persists:
+
+```bash
+echo "AUTH_SECRET=$(openssl rand -hex 32)" >> ~/.forge/.env.local
+```
+
+</details>
+
 ## Roadmap
 
-- [ ] **Multi-Agent Workflow** — DAG-based pipelines where multiple Claude Code instances collaborate, passing outputs between nodes with conditional routing and parallel execution. See [docs/roadmap-multi-agent-workflow.md](docs/roadmap-multi-agent-workflow.md).
+- [ ] **Multi-Agent Workflow** — DAG-based pipelines where multiple Claude Code instances collaborate ([design doc](docs/roadmap-multi-agent-workflow.md))
 - [ ] Pipeline UI — DAG visualization with real-time node status
-- [ ] Additional bot platforms — Discord, Slack, etc.
-- [ ] Multi-model chat with API keys (Anthropic, OpenAI, Google, xAI)
+- [ ] Additional bot platforms — Discord, Slack
+- [ ] Excalidraw rendering in Docs viewer
+- [ ] Multi-model chat (Anthropic, OpenAI, Google, xAI)
+
+## Contributing
+
+Contributions welcome! Please open an issue first to discuss what you'd like to change.
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/app/api/pipelines/[id]/route.ts

@@ -0,0 +1,28 @@
+import { NextResponse } from 'next/server';
+import { getPipeline, cancelPipeline, deletePipeline } from '@/lib/pipeline';
+
+// GET /api/pipelines/:id
+export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const pipeline = getPipeline(id);
+  if (!pipeline) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+  return NextResponse.json(pipeline);
+}
+
+// POST /api/pipelines/:id — actions (cancel)
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const { action } = await req.json();
+
+  if (action === 'cancel') {
+    const ok = cancelPipeline(id);
+    return NextResponse.json({ ok });
+  }
+
+  if (action === 'delete') {
+    const ok = deletePipeline(id);
+    return NextResponse.json({ ok });
+  }
+
+  return NextResponse.json({ error: 'Unknown action' }, { status: 400 });
+}

package/app/api/pipelines/route.ts

@@ -0,0 +1,52 @@
+import { NextResponse } from 'next/server';
+import { listPipelines, listWorkflows, startPipeline } from '@/lib/pipeline';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import YAML from 'yaml';
+
+const FLOWS_DIR = join(homedir(), '.forge', 'flows');
+
+// GET /api/pipelines — list all pipelines + available workflows
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url);
+  const type = searchParams.get('type');
+
+  if (type === 'workflows') {
+    return NextResponse.json(listWorkflows());
+  }
+
+  return NextResponse.json(listPipelines().sort((a, b) => b.createdAt.localeCompare(a.createdAt)));
+}
+
+// POST /api/pipelines — start a pipeline or save a workflow
+export async function POST(req: Request) {
+  const body = await req.json();
+
+  // Save workflow YAML from visual editor
+  if (body.action === 'save-workflow' && body.yaml) {
+    try {
+      mkdirSync(FLOWS_DIR, { recursive: true });
+      const parsed = YAML.parse(body.yaml);
+      const name = parsed.name || 'unnamed';
+      const filePath = join(FLOWS_DIR, `${name}.yaml`);
+      writeFileSync(filePath, body.yaml, 'utf-8');
+      return NextResponse.json({ ok: true, name, path: filePath });
+    } catch (e: any) {
+      return NextResponse.json({ error: e.message }, { status: 400 });
+    }
+  }
+
+  // Start pipeline
+  const { workflow, input } = body;
+  if (!workflow) {
+    return NextResponse.json({ error: 'workflow name required' }, { status: 400 });
+  }
+
+  try {
+    const pipeline = startPipeline(workflow, input || {});
+    return NextResponse.json(pipeline);
+  } catch (e: any) {
+    return NextResponse.json({ error: e.message }, { status: 400 });
+  }
+}