@aion0/forge 0.1.0

package/CLAUDE.md

@@ -0,0 +1,4 @@
+## Obsidian Vault
+Location: /Users/zliu/MyDocuments/obsidian-project/Projects/Bastion
+When I ask about my notes, use bash to search and read files from this directory.
+Example: find /Users/zliu/MyDocuments/obsidian-project -name "*.md" | head -20

package/README.md

@@ -0,0 +1,264 @@
+# Forge
+
+> Self-hosted AI workflow platform — web terminal, task orchestration, remote access.
+
+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.
+
+No API keys required. Forge runs on your existing Claude Code subscription.
+
+## Features
+
+- **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
+
+- **Node.js** >= 20
+- **pnpm** (recommended) or npm
+- **tmux** — for web terminal sessions
+- **Claude Code CLI** — `npm install -g @anthropic-ai/claude-code`
+
+## Installation
+
+### From npm
+
+```bash
+npm install -g @aion0/forge
+```
+
+### From source
+
+```bash
+git clone https://github.com/aiwatching/forge.git
+cd forge
+pnpm install
+pnpm build
+```
+
+## Quick Start
+
+### 1. Create config
+
+Create `.env.local` in the project root:
+
+```env
+# Auth (generate a random string, e.g. openssl rand -hex 32)
+AUTH_SECRET=<random-string>
+AUTH_TRUST_HOST=true
+
+# Optional: Google OAuth for production
+# GOOGLE_CLIENT_ID=...
+# GOOGLE_CLIENT_SECRET=...
+```
+
+> **API keys are not required.** Forge uses your local Claude Code CLI, which runs on your Anthropic subscription. If you want to use the built-in multi-model chat feature, you can optionally add provider keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, `XAI_API_KEY`) later.
+
+### 2. Start the server
+
+```bash
+# Development
+pnpm dev
+
+# Production
+pnpm build && pnpm start
+```
+
+### 3. 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:
+
+```bash
+forge password
+```
+
+### 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:
+
+```bash
+# Submit a task
+forge task my-app "Fix the login bug in auth.ts"
+
+# Force a fresh session (ignore previous context)
+forge task my-app "Refactor the API layer" --new
+
+# List tasks
+forge tasks              # all
+forge tasks running      # filter by status
+
+# Watch task output live
+forge watch <task-id>
+
+# Task details (result, git diff, cost)
+forge status <task-id>
+
+# Cancel / retry
+forge cancel <task-id>
+forge retry <task-id>
+```
+
+**All CLI shortcuts:** `t`=task, `r`=run, `ls`=tasks, `w`=watch, `l`=log, `s`=status, `f`=flows, `p`=projects, `pw`=password
+
+## YAML Workflows
+
+Define multi-step flows in `~/.my-workflow/flows/`:
+
+```yaml
+# ~/.my-workflow/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"
+```
+
+Run with `forge run daily-review`.
+
+## Bot Integration
+
+Forge ships with a Telegram bot for mobile-friendly control. The bot system is designed to be extensible to other platforms in the future.
+
+### Telegram Setup
+
+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
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `/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 |
+| `/tunnel_password <pw>` | Get login password + tunnel URL |
+| `/help` | Show all commands |
+
+Password-protected commands auto-delete your message to keep credentials safe.
+
+## Configuration
+
+All config lives in `~/.my-workflow/`:
+
+```
+~/.my-workflow/
+  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)
+```
+
+### settings.yaml
+
+```yaml
+# Project directories to scan
+projectRoots:
+  - ~/Projects
+  - ~/Work
+
+# Claude Code binary path (default: claude)
+claudePath: claude
+
+# Cloudflare Tunnel
+tunnelAutoStart: false              # Auto-start on server boot
+
+# Telegram bot (optional)
+telegramBotToken: ""                # Bot API token from @BotFather
+telegramChatId: ""                  # Your chat ID
+telegramTunnelPassword: ""          # Password for tunnel commands
+
+# Task notifications (optional, requires Telegram)
+notifyOnComplete: true
+notifyOnFailure: true
+```
+
+## 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)               │
+└─────────────────────────────────────────────┘
+```
+
+## 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) |
+
+## 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).
+- [ ] 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)
+
+## License
+
+MIT

package/app/api/auth/[...nextauth]/route.ts

@@ -0,0 +1,3 @@
+import { handlers } from '@/lib/auth';
+
+export const { GET, POST } = handlers;

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

@@ -0,0 +1,31 @@
+import { NextResponse } from 'next/server';
+import { getProcess, sendToClaudeSession, killProcess } from '@/lib/claude-process';
+
+// Get session info
+export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const proc = getProcess(id);
+  if (!proc) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+  return NextResponse.json(proc);
+}
+
+// Send a message to the Claude session
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const body = await req.json();
+
+  if (body.type === 'message') {
+    const ok = sendToClaudeSession(id, body.content, body.conversationId);
+    if (!ok) {
+      return NextResponse.json({ error: 'Session not found or already running' }, { status: 400 });
+    }
+    return NextResponse.json({ ok: true });
+  }
+
+  if (body.type === 'kill') {
+    killProcess(id);
+    return NextResponse.json({ ok: true });
+  }
+
+  return NextResponse.json({ error: 'Unknown type' }, { status: 400 });
+}

package/app/api/claude/[id]/stream/route.ts

@@ -0,0 +1,63 @@
+import { attachToProcess } from '@/lib/claude-process';
+
+export const dynamic = 'force-dynamic';
+export const runtime = 'nodejs';
+
+// SSE stream of Claude Code structured messages
+export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+
+  const encoder = new TextEncoder();
+  let unsubscribe: (() => void) | null = null;
+  let heartbeat: ReturnType<typeof setInterval> | null = null;
+  let closed = false;
+
+  const stream = new ReadableStream({
+    start(controller) {
+      // Heartbeat every 15s to keep connection alive
+      heartbeat = setInterval(() => {
+        if (!closed) {
+          try {
+            controller.enqueue(encoder.encode(': heartbeat\n\n'));
+          } catch {
+            // Controller closed
+            cleanup();
+          }
+        }
+      }, 15000);
+
+      unsubscribe = attachToProcess(id, (msg) => {
+        if (closed) return;
+        try {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify(msg)}\n\n`));
+        } catch {
+          cleanup();
+        }
+      });
+
+      if (!unsubscribe) {
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'system', subtype: 'error', content: 'Session not found' })}\n\n`));
+        cleanup();
+        controller.close();
+      }
+    },
+    cancel() {
+      cleanup();
+    },
+  });
+
+  function cleanup() {
+    closed = true;
+    if (heartbeat) { clearInterval(heartbeat); heartbeat = null; }
+    if (unsubscribe) { unsubscribe(); unsubscribe = null; }
+  }
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    },
+  });
+}

package/app/api/claude/route.ts

@@ -0,0 +1,28 @@
+import { NextResponse } from 'next/server';
+import { createClaudeSession, listProcesses, deleteSession } from '@/lib/claude-process';
+import { getProjectInfo } from '@/lib/projects';
+
+// List all Claude Code sessions
+export async function GET() {
+  return NextResponse.json(listProcesses());
+}
+
+// Create a new Claude Code session for a project
+export async function POST(req: Request) {
+  const { projectName } = await req.json();
+
+  const project = getProjectInfo(projectName);
+  if (!project) {
+    return NextResponse.json({ error: `Project not found: ${projectName}` }, { status: 404 });
+  }
+
+  const session = createClaudeSession(project.name, project.path);
+  return NextResponse.json(session);
+}
+
+// Delete a session
+export async function DELETE(req: Request) {
+  const { id } = await req.json();
+  deleteSession(id);
+  return NextResponse.json({ ok: true });
+}

package/app/api/claude-sessions/[projectName]/live/route.ts

@@ -0,0 +1,72 @@
+import { getSessionFilePath, readSessionEntries, tailSessionFile } from '@/lib/claude-sessions';
+
+export const dynamic = 'force-dynamic';
+export const runtime = 'nodejs';
+
+export async function GET(req: Request, { params }: { params: Promise<{ projectName: string }> }) {
+  const { projectName } = await params;
+  const url = new URL(req.url);
+  const sessionId = url.searchParams.get('sessionId');
+
+  if (!sessionId) {
+    return new Response('sessionId parameter required', { status: 400 });
+  }
+
+  const filePath = getSessionFilePath(decodeURIComponent(projectName), sessionId);
+  if (!filePath) {
+    return new Response('Session file not found', { status: 404 });
+  }
+
+  const encoder = new TextEncoder();
+  let cleanup: (() => void) | null = null;
+  let heartbeat: ReturnType<typeof setInterval> | null = null;
+  let closed = false;
+
+  const stream = new ReadableStream({
+    start(controller) {
+      // Send all existing entries
+      const existing = readSessionEntries(filePath);
+      controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'init', entries: existing })}\n\n`));
+
+      // Heartbeat
+      heartbeat = setInterval(() => {
+        if (!closed) {
+          try { controller.enqueue(encoder.encode(': heartbeat\n\n')); } catch { doCleanup(); }
+        }
+      }, 15000);
+
+      // Tail for new entries
+      cleanup = tailSessionFile(
+        filePath,
+        (entries) => {
+          if (closed) return;
+          try {
+            controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'update', entries })}\n\n`));
+          } catch { doCleanup(); }
+        },
+        () => {
+          doCleanup();
+          try { controller.close(); } catch {}
+        },
+      );
+    },
+    cancel() {
+      doCleanup();
+    },
+  });
+
+  function doCleanup() {
+    closed = true;
+    if (heartbeat) { clearInterval(heartbeat); heartbeat = null; }
+    if (cleanup) { cleanup(); cleanup = null; }
+  }
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    },
+  });
+}

package/app/api/claude-sessions/[projectName]/route.ts

@@ -0,0 +1,37 @@
+import { NextResponse } from 'next/server';
+import { listClaudeSessions, deleteSession } from '@/lib/claude-sessions';
+import { getDb } from '@/src/core/db/database';
+import { getDbPath } from '@/src/config';
+
+export async function GET(_req: Request, { params }: { params: Promise<{ projectName: string }> }) {
+  const { projectName } = await params;
+  const sessions = listClaudeSessions(decodeURIComponent(projectName));
+  return NextResponse.json(sessions);
+}
+
+export async function DELETE(req: Request, { params }: { params: Promise<{ projectName: string }> }) {
+  const { projectName } = await params;
+  const project = decodeURIComponent(projectName);
+  const body = await req.json();
+
+  // Support both single sessionId and batch sessionIds
+  const ids: string[] = body.sessionIds || (body.sessionId ? [body.sessionId] : []);
+
+  if (ids.length === 0) {
+    return NextResponse.json({ error: 'sessionId or sessionIds required' }, { status: 400 });
+  }
+
+  const db = getDb(getDbPath());
+  let deletedCount = 0;
+
+  for (const id of ids) {
+    if (deleteSession(project, id)) {
+      deletedCount++;
+    }
+    try {
+      db.prepare('DELETE FROM cached_sessions WHERE project_name = ? AND session_id = ?').run(project, id);
+    } catch {}
+  }
+
+  return NextResponse.json({ ok: true, deleted: deletedCount });
+}

package/app/api/claude-sessions/sync/route.ts

@@ -0,0 +1,17 @@
+import { NextResponse } from 'next/server';
+import { ensureInitialized } from '@/lib/init';
+import { syncSessionsToDb, getAllCachedSessions } from '@/lib/session-watcher';
+
+export async function GET() {
+  ensureInitialized();
+  const all = getAllCachedSessions();
+  return NextResponse.json(all);
+}
+
+export async function POST(req: Request) {
+  ensureInitialized();
+  const body = await req.json().catch(() => ({}));
+  const count = syncSessionsToDb(body.projectName);
+  const all = getAllCachedSessions();
+  return NextResponse.json({ synced: count, sessions: all });
+}

package/app/api/flows/route.ts

@@ -0,0 +1,6 @@
+import { NextResponse } from 'next/server';
+import { listFlows } from '@/lib/flows';
+
+export async function GET() {
+  return NextResponse.json(listFlows());
+}

package/app/api/flows/run/route.ts

@@ -0,0 +1,19 @@
+import { NextResponse } from 'next/server';
+import { runFlow } from '@/lib/flows';
+
+export async function POST(req: Request) {
+  const { name } = await req.json();
+  if (!name) {
+    return NextResponse.json({ error: 'Flow name required' }, { status: 400 });
+  }
+
+  try {
+    const result = runFlow(name);
+    return NextResponse.json({
+      flow: result.flow.name,
+      tasks: result.tasks.map(t => ({ id: t.id, projectName: t.projectName, prompt: t.prompt })),
+    });
+  } catch (err: any) {
+    return NextResponse.json({ error: err.message }, { status: 400 });
+  }
+}

package/app/api/notify/test/route.ts

@@ -0,0 +1,33 @@
+import { NextResponse } from 'next/server';
+import { loadSettings } from '@/lib/settings';
+
+export async function POST() {
+  const settings = loadSettings();
+  const { telegramBotToken, telegramChatId } = settings;
+
+  if (!telegramBotToken || !telegramChatId) {
+    return NextResponse.json({ ok: false, error: 'Telegram bot token or chat ID not configured' });
+  }
+
+  try {
+    const url = `https://api.telegram.org/bot${telegramBotToken}/sendMessage`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        chat_id: telegramChatId,
+        text: '✅ *Forge* — Test notification!\n\nTelegram notifications are working.',
+        parse_mode: 'Markdown',
+      }),
+    });
+
+    if (!res.ok) {
+      const body = await res.text();
+      return NextResponse.json({ ok: false, error: body });
+    }
+
+    return NextResponse.json({ ok: true });
+  } catch (err: any) {
+    return NextResponse.json({ ok: false, error: err.message });
+  }
+}

package/app/api/projects/route.ts

@@ -0,0 +1,7 @@
+import { NextResponse } from 'next/server';
+import { scanProjects } from '@/lib/projects';
+
+export async function GET() {
+  const projects = scanProjects();
+  return NextResponse.json(projects);
+}

package/app/api/sessions/[id]/chat/route.ts

@@ -0,0 +1,64 @@
+import { getSessionManager } from '@/lib/session-manager';
+import { chatStream } from '@/src/core/providers/chat';
+import type { ModelMessage } from 'ai';
+
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const { message } = await req.json();
+  const manager = getSessionManager();
+
+  const session = manager.get(id);
+  if (!session) {
+    return new Response(JSON.stringify({ error: 'Session not found' }), { status: 404 });
+  }
+
+  // Save user message
+  manager.addMessage(id, 'user', message, session.provider, session.model);
+
+  // Get memory-filtered messages
+  const memoryMessages = manager.getMemoryMessages(id);
+  const coreMessages: ModelMessage[] = memoryMessages.map(m => ({
+    role: m.role as 'user' | 'assistant',
+    content: m.content,
+  }));
+
+  manager.updateStatus(id, 'running');
+
+  // Stream response
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    async start(controller) {
+      try {
+        const result = await chatStream({
+          provider: session.provider,
+          model: session.model || undefined,
+          systemPrompt: session.systemPrompt,
+          messages: coreMessages,
+          onToken(token) {
+            controller.enqueue(encoder.encode(`data: ${JSON.stringify({ token })}\n\n`));
+          },
+        });
+
+        // Save assistant message
+        manager.addMessage(id, 'assistant', result.content, result.provider, result.model);
+        manager.recordUsage(id, result);
+        manager.updateStatus(id, 'idle');
+
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify({ done: true, usage: { input: result.inputTokens, output: result.outputTokens } })}\n\n`));
+        controller.close();
+      } catch (err: any) {
+        manager.updateStatus(id, 'error');
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify({ error: err.message })}\n\n`));
+        controller.close();
+      }
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    },
+  });
+}

package/app/api/sessions/[id]/messages/route.ts

@@ -0,0 +1,9 @@
+import { NextResponse } from 'next/server';
+import { getSessionManager } from '@/lib/session-manager';
+
+export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const manager = getSessionManager();
+  const messages = manager.getMessages(id);
+  return NextResponse.json(messages);
+}