session-forge-reporter

session-forge-reporter

Syncs your local session-forge data to a session-forge hub server.

This is the bridge between session-forge (running on each developer's machine) and session-forge-hub (running on your company's LAN). It watches your local session-forge JSON files for changes and sends new entries to the hub over HTTP.

How It Fits Together

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)   │                          │
└─────────────────────────────────┘          └──────────────────────────┘

Prerequisites

• session-forge must be installed and configured in your Claude Code setup. This is what generates the data.
• session-forge hub must be running on your network. Your team lead or IT admin sets this up.
• You need an agent API key (sfh_agent_...) — your admin creates this in the hub dashboard.

Quick Start

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

That's it. On startup, it does a full sync of all existing data, then polls for new changes every 5 seconds.

Configuration

CLI Flags

npx session-forge-reporter \
  --hub <url>          # Hub server URL (required)
  --key <key>          # Agent API key (required)
  --forge-dir <dir>    # session-forge data directory (auto-detected)
  --poll <ms>          # Poll interval in milliseconds (default: 5000)

Config File

Instead of CLI flags, create a config file:

Linux/Mac: ~/.session-forge-reporter.json Windows: %APPDATA%/session-forge-reporter.json

{
  "hubUrl": "http://192.168.1.100:3700",
  "agentApiKey": "sfh_agent_..."
}

CLI flags override config file values.

What It Syncs

The reporter watches these session-forge data files:

File	What it contains
decisions.json	Architectural decisions with reasoning and alternatives
dead-ends.json	Failed approaches with lessons learned
journal.json	Session summaries with breakthroughs and frustrations
sessions/active.json	Current session checkpoint (task, status, next steps)
profile.json	Developer profile and preferences

Only new entries are sent after the initial sync. The reporter tracks how many entries it has already synced and only sends the delta.

How It Works

• Startup — full sync: reads all local data files and sends everything to the hub
• Polling — every 5 seconds (configurable), checks file modification times
• Delta sync — if a file changed, reads it and sends only new entries (by array index)
• Retry — failed sends are retried with exponential backoff (up to 5 attempts)
• Auth errors — 401/403 responses are not retried (bad key, deactivated agent)

Zero Dependencies

This package uses only Node.js built-in modules (fs, http, path). No external dependencies.

Related Packages

• session-forge — the MCP server that generates the data
• session-forge-hub — the dashboard server that collects and displays it

License

MIT

Built by Jacob Terrell