session-forge-hub

session-forge hub

Team intelligence for AI coding — on YOUR infrastructure.

Your developers are making hundreds of decisions, hitting dead ends, and building institutional knowledge every day through AI coding assistants. session-forge hub gives you visibility into all of it — without sending a single byte to anyone else's servers.

https://github.com/420247jake/session-forge-hub/raw/main/promo/sessionforge.mp4

Prerequisites

This project requires session-forge — the MCP server that Claude Code uses to track decisions, dead ends, journal entries, and session state. Each developer on your team needs session-forge installed and configured in their Claude Code setup.

If your developers aren't already using session-forge, start there first:

npx session-forge

session-forge hub does NOT replace session-forge. It sits alongside it. session-forge continues to work exactly as before — hub just gives your team a shared dashboard to see everyone's data in one place.

How the Three Pieces Fit Together

There are three separate npm packages involved. Here's what each one does:

Package	Who installs it	What it does
session-forge	Each developer	MCP server that Claude Code talks to. Saves decisions, dead ends, journal entries as local JSON files. You probably already have this.
session-forge-hub	IT admin / team lead	Dashboard server that runs on your LAN. Collects data from all developers. Shows activity, search, reports.
session-forge-reporter	Each developer	Watches session-forge's local JSON files and syncs new entries to the hub over your local network. This is the bridge between session-forge and the hub.

Developer's Machine                          Company LAN Server
┌─────────────────────────────────┐          ┌──────────────────────────┐
│                                 │          │                          │
│  Claude Code                    │          │  session-forge hub       │
│       ↓ (MCP)                   │          │  http://192.168.x.x:3700 │
│  session-forge                  │          │                          │
│       ↓ (writes JSON)           │          │  Dashboard, Search,      │
│  ~/.session-forge/              │          │  Reports, Audit Log      │
│       ↓ (watches files)         │   HTTP   │                          │
│  session-forge-reporter  ───────────────→  │  REST API + JSON Storage │
│                                 │  (LAN)   │                          │
└─────────────────────────────────┘          └──────────────────────────┘

session-forge works without the hub. The hub is optional — it just adds team-wide visibility. If a developer never runs the reporter, their data stays local and nothing breaks.

Why Local-First Matters

Every AI coding session generates sensitive data: architectural decisions, debugging history, file paths, code context, failed approaches. This is your company's intellectual property.

Cloud-hosted alternatives route this data through third-party servers. You're trusting someone else with your proprietary code intelligence, your team's workflow patterns, and your project architecture.

session-forge hub runs on YOUR network. Zero external calls. Zero analytics. Zero phone-home. Your data never leaves your infrastructure.

What the Hub Dashboard Shows

• Overview — stats cards, agent grid, recent activity feed across all developers
• Agents — register, monitor, and manage each Claude Code instance
• Activity Feed — real-time view of checkpoints, decisions, dead ends across the team
• Cross-Agent Search — search all decisions and dead ends across all developers
• Daily Reports — auto-generated summaries with highlights, top projects, breakthroughs
• Audit Log — every API call logged with timestamp, agent, IP, and action
• Security Page — educational content about why local-first matters
• Sync & Export — export/import all agent data with scope filters (all, self, select)
• Remote Access Guide — setup instructions for VPN, Nginx, and Cloudflare Tunnel
• Donate — optional Stripe integration if you want to support development

Quick Start

1. Make sure developers have session-forge

Each developer needs session-forge configured in their Claude Code. If they don't have it yet:

npx session-forge

Then add it to their Claude Code MCP settings. See the session-forge docs for setup.

2. Start the hub (on your LAN server or any machine)

npx session-forge-hub

On first run, it generates your admin API key and prints it to the terminal. Save it — it's shown once.

3. Open the dashboard

Navigate to http://localhost:3700 (or your server's LAN IP) and enter your admin key.

4. Register each developer as an agent

In the dashboard, click "Register Agent" and fill in:

• Name: e.g. "Alice's Claude Code"
• Developer: e.g. "Alice"
• Machine: e.g. "alice-macbook"

You'll get an agent API key. Give this to the developer.

5. Each developer runs the reporter

On each developer's machine (where session-forge is already saving data):

npx session-forge-reporter --hub http://YOUR_HUB_IP:3700 --key sfh_agent_...

The reporter watches session-forge's local JSON files and syncs new entries to the hub. It does a full sync on startup, then polls for changes every 5 seconds.

Configuration

Hub Server

Variable	Default	Description
PORT	3700	Server port
HOST	0.0.0.0	Bind address
SESSION_FORGE_HUB_DIR	~/.session-forge-hub	Data directory
HUB_NAME	session-forge hub	Name shown in dashboard
MAX_AGENTS	50	Maximum registered agents
RETENTION_DAYS	90	Data retention period
STRIPE_SECRET_KEY	—	Optional: Stripe secret key for donations
STRIPE_PUBLISHABLE_KEY	—	Optional: Stripe publishable key

Reporter

# CLI flags
npx session-forge-reporter --hub <url> --key <key> [--forge-dir <dir>] [--poll <ms>]

# Or config file (~/.session-forge-reporter.json)
{
  "hubUrl": "http://192.168.1.100:3700",
  "agentApiKey": "sfh_agent_..."
}

# Sync mode — export all hub data to a file
npx session-forge-reporter sync --hub <url> --key <admin_key> --output backup.json

# Sync mode — import data from a file
npx session-forge-reporter sync --hub <url> --key <admin_key> --import backup.json

# Export specific agents only
npx session-forge-reporter sync --hub <url> --key <admin_key> --agents id1,id2 --output partial.json

Security Model

API Keys

• Admin key (sfh_admin_...) — full dashboard access, agent management
• Agent keys (sfh_agent_...) — can only submit and read own data
• All keys bcrypt-hashed (cost 12) before storage
• Keys shown exactly once on generation, never stored in plaintext

Network

• All traffic stays on your local network
• No external network calls — ever
• No CDN dependencies (all assets bundled)
• No analytics, no telemetry, no tracking
• Helmet.js security headers

Rate Limiting

• 120 requests/minute per IP
• Prevents abuse without blocking normal usage

Audit

• Every API call logged: timestamp, agent ID, action, IP, success/failure
• Rolling buffer of 10,000 entries
• Viewable in dashboard and via API

API Reference

Agent Management (Admin key)

Method	Path	Description
POST	/api/agents/register	Register new agent
GET	/api/agents	List all agents
GET	/api/agents/:id	Get agent details
DELETE	/api/agents/:id	Deactivate agent
POST	/api/agents/:id/rotate-key	Rotate API key

Data Ingestion (Agent key)

Method	Path	Description
POST	/api/ingest/checkpoint	Submit checkpoint
POST	/api/ingest/decision	Submit decision
POST	/api/ingest/dead-end	Submit dead end
POST	/api/ingest/journal	Submit journal entry
POST	/api/ingest/profile	Update profile
POST	/api/ingest/batch	Batch submit

Dashboard (Admin key)

Method	Path	Description
GET	/api/dashboard/overview	Hub overview stats
GET	/api/dashboard/activity	Recent activity feed
GET	/api/dashboard/agent/:id/activity	Agent activity

Search (Admin key)

Method	Path	Description
GET	/api/search/decisions?q=	Search decisions
GET	/api/search/dead-ends?q=	Search dead ends

Reports (Admin key)

Method	Path	Description
GET	/api/reports/daily?date=	Daily report

Sync & Export (Admin or Agent key)

Method	Path	Description
POST	/api/sync/export	Export data bundle (scope: all, self, select)
POST	/api/sync/import	Import data bundle (admin only)
GET	/api/sync/agents	List agents for sync UI

Admin

Method	Path	Description
GET	/api/admin/health	Health check (no auth)
GET	/api/admin/audit	Audit log

Storage

All data stored as plain JSON files:

~/.session-forge-hub/
  hub.json              # Hub config + admin key hash
  audit.json            # Audit log
  agents/
    {id}.json           # Agent metadata per registered agent
  data/
    {id}/               # Per-agent data directory
      checkpoints.json
      decisions.json
      dead-ends.json
      journal.json
      profile.json
  reports/
    daily/{date}.json   # Generated daily reports

Support

session-forge hub is free and open-source. If it's saving your team time, consider supporting development:

• GitHub Sponsors
• The hub includes a built-in donation page at /donate.html (Stripe integration, optional)

License

MIT

Built by Jacob Terrell