# 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.

## 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 |
| **Connectors Marketplace** | Connectors are an independent subsystem with their own registry — fetched from `aiwatching/forge-connectors` (override via `connectorsRepoUrl`). No built-ins; users install only what they need. PAT-style secrets are encrypted at rest. |
| **Memory** | Long-term chat memory. Configure `@aion0/temper` for semantic + graph search, or leave URL/key blank to use the built-in local SQLite store (same block/episode API, keyword search). |
| **Web Chat (simplified)** | `/chat` — minimal in-browser chat UI for use without the extension. Sessions, SSE streaming, memory badge. Full connector UX still lives in the extension. |
| **IDE Plugins** | First-party VSCode extension and IntelliJ plugin — drive workspaces, agents, terminals, pipelines and docs from inside the editor (see `13-ide-plugins.md`) |

## Quick Start

```bash
npm install -g @aion0/forge
forge server start
```

Open `http://localhost:8403`. First launch prompts you to set an admin password.

### Optional — enterprise marketplace at install time

Forge users inside a company that publishes its own connectors / pipelines through a private GitHub repo (an "enterprise marketplace") can register the key at install:

```bash
./install.sh --enterprise-key=<tenant>:<github_pat>
# or multiple
./install.sh --enterprise-key=fortinet:pat_xxx --enterprise-key=acme:pat_yyy
```

Equivalently, do it any time afterwards via `forge --add-enterprise-key --enterprise-key=...`, or paste the key into Forge chat ("here's our enterprise key: …"). See `01-settings.md` for the full picture.

## 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
```

## Dashboard top bar

The top toolbar is split between **at-a-glance signals** (left to right) and a **user menu** (right edge):

- **? Help** — opens the in-app Help AI.
- **Browser ▾** — open an embedded browser (float / right / left dock or external tab).
- **Tunnel** — start/stop the Cloudflare tunnel + online-count badge.
- **Alerts** — notifications (task done, pipeline failed, tunnel events).

Next to the **Automation** tab in the left-side nav sits a small **Activity** sub-pill — running pipelines + upcoming schedules + recent runs (`▶<running>` `⏰<upcoming>`). Click for a 3-section dropdown with a "view" link that jumps to the run. It lives there because its content is the live read-side of Automation.
- **User menu (▾)** — `⚙ Settings` + `💬 Chat (web) ↗` at the top (Chat opens in a new tab so the dashboard isn't replaced); then a divider, then the periodic-check screens `📊 Monitor` (background watches, processes, queues), `🔐 Login Status` (connector creds), `💰 Usage` (token/cost analytics), `📜 Logs`, `📱 Mobile View ↗`; then `⏻ Logout`.

Periodic-check screens (Monitor / Login Status / Usage) live inside the user menu so the top bar only shows things worth glancing at.
