F Forge Project Guide

What Forge Is

Forge is a local-first operating system for your work and life.

Forge is a local-first system for goals, projects, tasks, task runs, notes, wiki pages, calendar planning, preferences, health records, movement history, sleep, and Psyche data. This site explains the product itself: what each area is for, how the pieces fit together, and where to go when you want to plan, act, reflect, or connect Forge to your tools.

Forge's planning model is explicit: Goal > Strategy > Project > Strategy > Issue > Task > Subtask. Projects are PRD-backed, issues are vertical slices, and tasks are sized for one focused AI session.

The PM workspace is also shared: one mixed board for projects, issues, tasks, and subtasks, plus one compact hierarchy view with shared search, visible-level multi-selects, hierarchy-aware linking, and guided modal flows for create, move, link, and closeout actions.

React 19 + Vite 6 Fastify 5 + OpenAPI 3.1 SQLite + file-backed wiki Direct commits to main
Run Forge locally Open API reference

Ways To Use Forge

Pick the setup that matches how you want to work with Forge.

OpenClaw plugin

Use this when OpenClaw is your main control surface and you want Forge available as an integrated operating environment inside it. 

openclaw plugins install forge-openclaw-plugin
openclaw plugins enable forge-openclaw-plugin
openclaw gateway restart
openclaw forge health

OpenClaw fallback (`2026.4.x`)

If a current OpenClaw build blocks the normal plugin install path, this temporary npm route keeps Forge usable. 

npm install -g forge-openclaw-plugin
node -e 'const cp=require("child_process"); const fs=require("fs"); const path=require("path"); const p=process.env.HOME+"/.openclaw/openclaw.json"; const j=JSON.parse(fs.readFileSync(p,"utf8")); const pluginPath=path.join(cp.execSync("npm root -g",{encoding:"utf8"}).trim(),"forge-openclaw-plugin"); j.plugins ??= {}; j.plugins.allow = Array.from(new Set([...(j.plugins.allow || []), "forge-openclaw-plugin"])); j.plugins.load ??= {}; j.plugins.load.paths = Array.from(new Set([...(j.plugins.load.paths || []), pluginPath])); j.plugins.entries ??= {}; j.plugins.entries["forge-openclaw-plugin"] = { enabled: true, config: { origin: "http://127.0.0.1", port: 4317, actorLabel: "aurel", timeoutMs: 15000 } }; fs.writeFileSync(p, JSON.stringify(j, null, 2)+"\n"); console.log("Configured", pluginPath);'
openclaw gateway restart
openclaw plugins info forge-openclaw-plugin
openclaw forge health

Hermes plugin

Use this when Hermes is the agent environment you want Forge to power. 

~/.hermes/hermes-agent/venv/bin/python -m ensurepip --upgrade
~/.hermes/hermes-agent/venv/bin/python -m pip install --upgrade ./plugins/forge-hermes

Standalone repo runtime

Use this when you want the full Forge app and API running locally in the browser. 

npm install
npm run dev

iPhone Companion

Forge Companion for iPhone is currently in beta.

TestFlight Beta Health, movement, and sync

Forge Companion is the native iPhone bridge for Forge. It pairs with your Forge runtime, imports HealthKit sleep and workouts, captures passive movement history, and gives you a native life timeline plus diagnostics while Forge itself stays local-first.

The app is currently in beta through TestFlight while the sync, movement repair, and timeline systems are being tightened in real-world usage.

Forge Companion pairing and discovery screen in portrait.
Pairing and runtime discovery
Forge Companion paired home screen in portrait.
Paired home and sync controls
Forge Companion life timeline screen in portrait.
Life Timeline with stays and moves
Forge Companion diagnostics screen in portrait.
Diagnostics, payloads, and logs

Guide Map

Each page explains a different part of the Forge experience.

Features

Learn what you can do in Forge, from planning work to tracking movement, sleep, knowledge, and reflection.

How Forge is built

Understand the architecture, storage model, major surfaces, and how the web app, API, and companion stay aligned.

Run it yourself

Start Forge locally, verify the main app paths, and understand how the docs and API reference are generated.

Integrations

See how Forge connects to OpenClaw, Hermes, Codex, and the iPhone companion without splitting your data into silos.

API reference

Interactive API explorer with route descriptions, typed payloads, live Try it out support, and the downloadable generated spec.

Support

Get help with pairing, sync, HealthKit, movement history, and the companion app.

Privacy policy

Read how Forge Companion handles HealthKit, location, and paired-device sync.

Current Stack

The product runs on a modern local-first web and sync stack.

Layer Current stack Notes
Web UI React 19, TypeScript 5.8, Vite 6, Tailwind CSS 4 Served under /forge/ in production and local dev.
Backend Fastify 5, TypeScript, OpenAPI 3.1 Spec is generated from server/src/openapi.ts.
Storage SQLite + file-backed wiki vault Forge keeps canonical runtime records locally first.
Desktop / native Tauri 2 and iOS companion Desktop shell plus HealthKit-powered iPhone companion.
Docs GitHub Pages static site + rendered OpenAPI reference The Pages artifact includes this site and the generated spec.

Where Things Live

These are the main entry points for the app, API, and docs.

Local development

UI:  http://127.0.0.1:3027/forge/
API: http://127.0.0.1:4317/api/v1/
Spec: http://127.0.0.1:4317/api/v1/openapi.json

GitHub Pages

Docs home: /forge/
Engineering: /forge/engineering.html
Development: /forge/development.html
Integrations: /forge/integrations.html
API docs: /forge/api/
Forge overview dashboard
Forge keeps execution, planning, memory, health, and Psyche records in one runtime. Use the UI when the work is visual; use the API or agent adapters when the work is operational.

Core Product Areas

These screenshots show how Forge turns planning and reflection into daily practice.

Forge Kanban board showing task lanes and execution controls.
Kanban is the flagship execution board, with lane movement, filters, owner scopes, and direct task actions.
Forge hierarchy view showing the goal-to-subtask tree, shared filters, and operational progress.
The hierarchy view keeps the whole planning ladder visible at once, so goals, projects, issues, tasks, and subtasks stay legible without flattening them into one lane list.
Forge Movement page showing the life timeline with stays and trips.
Movement turns passive place and trip history into a life timeline with stays, places, corrections, and linked context.
Forge Sleep page showing the last-night summary, sleep calendar, and selected-night detail.
Sleep is now night-first: last-night recovery, weekly baseline, calendar browsing, selected-night phases, and raw evidence on demand all live in one health workspace.