Forge

A local-first operating system for planning, execution, memory, health context, and agents.

Forge gives humans and AI agents one shared place to turn goals into projects, issues, tasks, evidence, health signals, and durable memory. It is built for people who need the chain between intention, action, context, and review to stay visible.

React 19 + Vite 6 Fastify 5 + OpenAPI 3.1 SQLite-backed wiki OpenClaw + Hermes + Codex + Claude Iroh iPhone pairing

Why Forge Install Forge

Why Forge

The hard part is not remembering one task. It is keeping the full chain of meaning intact.

The problem

Real work carries strategy, constraints, notes, meetings, emotional friction, recovery, preferences, and unfinished reasoning. Most tools split those pieces apart: tasks in one place, notes in another, health on the phone, and agent work in chat transcripts or terminal history.

That split makes the user carry the system in their head. They have to remember why a project mattered, what changed, which evidence supports it, and what action is safe to take next.

The value

Forge exists so the work, the reason for the work, the context around the work, and the record of what changed can point at the same local records. It is not only a productivity dashboard. It is a system of record for planning, execution, reflection, health context, and agent collaboration.

Forge does not replace the unstructured memory of agent harnesses such as OpenClaw, Codex, Hermes, and Claude Code. It complements that memory with structured memory. Prose can stay in notes and wiki pages, trusted files can become Artifact Store records, and goals, beliefs, decisions, triggers, tasks, preferences, sleep, movement, and evidence can become records with identity, links, state, and history when they need to be reviewed, compared, updated, or acted on.

How Forge Solves It

Forge uses one local runtime and one shared entity model instead of another disconnected app silo.

Explicit planning ladder

Forge turns goals into strategies, PRD-backed projects, vertical-slice issues, one-session tasks, and small subtasks. The board and hierarchy views show the same structure from different working angles.

Structured memory plus prose

Notes, wiki pages, trusted file artifacts, preferences, Psyche records, sleep, workouts, movement history, and nutrition context can stay beside the work they explain instead of becoming detached side records. Artifact files keep provenance, static scans, danger scores, versions, and human-only downloads while using the same generic entity-link graph as the rest of Forge.

Shared agent runtime

OpenClaw, Hermes, Codex, Claude Code, the browser app, and the iPhone companion use the same Forge runtime, API, and local data model when they are configured together.

Local-first storage

Forge keeps the database local by default, with explicit data folders, backups, and a Settings -> Data surface for inspection and recovery.

Health and recovery context

The iPhone companion imports HealthKit sleep and workouts, captures movement history, and helps Forge treat recovery and location context as first-class signals.

Open contracts

The Fastify API publishes generated OpenAPI 3.1, and the docs include both human guides and agent-facing route references.

Getting Started

One command installs Forge and guides the rest.

1. Check Node.js

Forge Memory requires Node.js 22 or newer. Node includes npm and npx.

node --version
npm --version

Install a current Node.js LTS release and reopen the terminal if the first command reports a version older than 22.

2. Run the guided install

Start here for the browser UI, OpenClaw, Hermes, Codex, Claude Code, or all of them together. The guided installer sets up the local Forge runtime, discovers agent hosts in the background, and lets you keep or change the real data folder before optional iPhone pairing.

npx forge-memory

The adapter menu selects every detected host by default, shows missing hosts as disabled rows, and supports Space to toggle OpenClaw, Hermes, Codex, and Claude Code.

3. Complete the choices

Keep or change the detected host adapters.
Confirm the Forge data folder, normally ~/.forge.
Leave optional Forge-to-Forge sharing off unless you need it.
Pair the iPhone now, or skip it and run npx forge-memory pair-ios later.

Run the installer as the normal operating-system user who will own this Forge installation.

4. Verify success

Wait for Forge Memory configured and checked. and Doctor: passed, then open and verify Forge.

npx forge-memory ui
npx forge-memory status
npx forge-memory doctor

The normal local app is http://127.0.0.1:4317/forge/. The base install stays local and does not expose Forge to another machine.

Optional iPhone prompts

Forge Companion must already be installed. The current app is distributed to invited testers through TestFlight. The CLI creates pairing material; it does not install the app or enroll a TestFlight account.

Phone pairing may ask before installing Tailscale, configuring Tailscale Serve, installing Rust/Cargo for the Iroh fallback, compiling the bundled native host, or restarting only the managed Forge runtime to bind its verified HTTPS origin.

You can decline or skip phone pairing during the base install. Tailscale Funnel is not required.

npx forge-memory pair-ios

Remote browser approval

A remote browser first needs an explicitly configured private HTTPS route, such as the consented Tailscale Serve path offered during iPhone pairing. Network reachability alone never authorizes Forge.

Start pairing in the remote browser. Then approve the exact pending request from an unlocked local-owner Forge window, or run this on the Forge host as the operating-system owner:

npx forge-memory pairing

Review the client, enter its short code once, and approve.

Platform differences

The macOS install includes the owner-only forge:// browser handoff and macOS Keychain storage for renewable remote CLI credentials. Linux and Windows do not receive those macOS features in 0.3.52; use the verified Forge-host CLI for pending browser approvals.

Forge-to-Forge sharing is available on macOS and Linux. It is not available on Windows in 0.3.52 and should remain disabled there.

Development install

Use the same polished flow when you are working from a Forge checkout. Dev mode links adapters to this source tree and defaults to the real shared Forge data folder.

npx forge-memory --dev

Reconfigure any time

Reopen the full setup flow after install. Forge uses the current config as defaults, so changing adapters, data folders, or iOS pairing does not require starting over.

npx forge-memory configure

Operate the local runtime

Check health, open the UI, restart the runtime, or pair the iPhone companion from the same CLI instead of hunting through adapter-specific commands.

npx forge-memory status
npx forge-memory doctor
npx forge-memory update
npx forge-memory ui
npx forge-memory restart
npx forge-memory stop
npx forge-memory export
npx forge-memory uninstall
npx forge-memory pair-ios

Update creates a pre-update backup, refreshes the runtime cache, and updates selected adapters without deleting data. Export keeps a portable backup path close at hand. Uninstall removes the runtime manager and cache while keeping your Forge data folder unless you explicitly ask to delete it.

Safe updates

Use the update command when you want the current runtime, OpenClaw, Hermes, or Codex integration refreshed. It prints the backup path before continuing and asks before overwriting any Forge-related skill folder that may have manual edits.

npx forge-memory update

Agent prompt: run npx forge-memory update --yes, verify npx forge-memory doctor, report the backup path, and stop if Forge cannot create a backup first.

Exact guide and advanced adapters

Read the complete numbered guide for platform-specific setup, pairing, update, recovery, and data-preservation details. Manual adapter commands remain reference paths for recovery, source-linking, and host-specific debugging.

Exact install guide Advanced adapters Source app

Guide Map

Once Forge is running, use the docs in the order that fits your goal.

Features

Learn what you can do in Forge across planning, knowledge, movement, sleep, health, and reflection.

How Forge is built

Understand the architecture, storage model, runtime surfaces, and technical stack.

Run it yourself

Start Forge locally, verify the main app paths, and review the contributor workflow model.

Integrations

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

Companion transport

Keep the base install simple, then go deeper into Forge's own Iroh and QUIC pairing path, relay behavior, QR payload, stream protocol, fallback mode, and license boundary.

Agent identity

Understand why OpenClaw, Hermes, Codex, and Claude Code are stable agents, why reconnects are sessions, and how those agents link to human or bot users with their own Kanban ownership.

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.

Product At A Glance

The core surfaces show how Forge keeps work, memory, movement, and recovery in one local-first system.

Forge overview dashboard showing execution, planning, memory, and health cards. — The overview dashboard is the fastest way to understand the product: active work, linked context, health signals, and reflection all show up in one local-first runtime.

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 Kanban board showing execution lanes and task controls. — Execution stays operational instead of decorative, with lane movement, owner scopes, and fast task actions directly in the board.

Forge wiki memory view showing linked written context and shared notes. — Notes and wiki memory stay close to execution, so context becomes part of the system instead of getting stranded in external documents.

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 overview showing the latest night summary and sleep calendar. — Health surfaces such as sleep are first-class product areas, not side widgets bolted onto a project tracker.

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

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 `apps/api/src/openapi.ts`.
Storage	SQLite-backed wiki memory	Forge keeps canonical runtime records locally first.
Desktop / native	Tauri 2, Swift iOS companion, Rust Iroh bridge	Desktop shell plus HealthKit-powered iPhone companion with default Iroh pairing.
Docs	GitHub Pages static site + rendered OpenAPI reference	The Pages artifact includes this site and the generated spec.

Where Records 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/