Linforge

Embeddable workbench for LangGraph Agent applications — design topology on canvas, implement logic in code, compile into executable graphs.

Why Linforge

| LangGraph Studio (official) | Linforge | |------------------------------|----------| | Desktop app | Web-embeddable — integrates into your product UI | | Code-only graph definition | Visual canvas + code hybrid | | Dev-only tool | Product managers sketch graphs, developers implement nodes | | Dev-time debugging | Built-in run history, step replay, and prompt versioning |

Install

npm install linforge
# or
pnpm add linforge

Peer dependencies (install only what you need):

# Server
pnpm add koa @koa/router

# UI
pnpm add react react-dom @xyflow/react

Quick Start

A minimal server in ~30 lines:

import Koa from 'koa';
import cors from '@koa/cors';
import bodyParser from 'koa-bodyparser';
import { StateSchema } from '@langchain/langgraph';
import { z } from 'zod/v4';
import { defineNodeFor } from 'linforge/core';
import { linforgeMiddleware } from 'linforge/server';

// 1. Define state
const MyState = new StateSchema({
  messages: z.array(z.string()).default([]),
  result: z.string().default(''),
});

// 2. Define nodes — state type is inferred automatically
const defineMyNode = defineNodeFor(MyState);

const greeter = defineMyNode({
  key: 'greeter',
  label: 'Greeter',
  run: async (state) => ({
    messages: [...state.messages, '[greeter] Hello!'],
    result: 'Greeting complete.',
  }),
});

// 3. Start server
const app = new Koa();
app.use(cors());
app.use(bodyParser());
app.use(linforgeMiddleware({
  stateSchema: MyState,
  nodes: [greeter],
}));

app.listen(3001);

This gives you a full REST API at http://localhost:3001/linforge — graph CRUD, run execution, step recording, and prompt management.

Package Exports

linforge          Re-exports all submodules
linforge/core     defineNode, Registry, Compiler, RunManager, PromptLoader, Store interfaces
linforge/server   Koa HTTP API (linforgeMiddleware + mountRoutes)
linforge/react    React hooks for graph editing, runs, and prompts
linforge/testing  In-memory Store implementations (dev/test)

Core Concepts

Three-Layer Architecture

Code Layer:    Node implementations + StateSchema + Route predicates    [developer]
Visual Layer:  Topology + Wiring + Prompts + Parameters                [canvas / DB]
Auto Layer:    Compiler merges both into a LangGraph Runnable           [linforge]

defineNode

Create node implementations with defineNode() or the type-safe defineNodeFor():

import { defineNodeFor } from 'linforge/core';

const defineMyNode = defineNodeFor(MyState);

const planner = defineMyNode({
  key: 'planner',
  run: async (state) => ({
    plan: 'Step 1: fetch. Step 2: analyze.',
  }),
  // Optional: conditional routing
  routes: {
    has_plan: (state) => !!state.plan,
  },
});

Store Interfaces

Four database-agnostic interfaces — implement them to plug in any database:

| Interface | Purpose | |-----------|---------| | GraphStore | Graph definition CRUD | | RunStore | Run record lifecycle | | StepPersister | Step data write/query | | PromptStore | Prompt version management |

PromptLoader

createPromptLoader(store) creates a cached prompt loader with Mustache template rendering:

import { createPromptLoader, renderPrompt } from 'linforge/core';

const loader = createPromptLoader(promptStore);

// Load active prompt, render variables, with fallback
const result = await loader.render('node-id', { name: 'World' }, {
  template: 'Hello {{name}}!',
  temperature: 0.7,
});
// result.text → "Hello World!"
// result.source → 'store' | 'fallback'

// Pure function (no store needed)
const text = renderPrompt('Hello {{name}}!', { name: 'World' });

Linforge ships in-memory implementations (linforge/testing) for development. For production, use an adapter package (e.g., linforge-adapter-prisma) or implement the interfaces yourself.

Server API

linforgeMiddleware (recommended)

One-line setup that auto-creates all internal components:

// Single-agent mode (backward compatible)
app.use(linforgeMiddleware({
  stateSchema: MyState,     // required — LangGraph StateSchema
  nodes: [planner, tools],  // required — node definitions
  prefix: '/linforge',      // default: "/linforge"
  stores: {                 // optional — custom Store implementations
    graphStore,
    runStore,
    stepPersister,
    promptStore,
  },
}));

Multi-Agent mode

Bind distinct stateSchema and nodes per Agent:

app.use(linforgeMiddleware({
  agents: [
    { slug: 'qa-bot', name: 'QA Bot', stateSchema: QAState, nodes: [retriever, answerer] },
    { slug: 'coder', name: 'Coder', stateSchema: CoderState, nodes: [planner, coder] },
  ],
  sharedNodes: [logger],  // available to all agents
}));

Each agent gets its own NodeRegistry and GraphCompiler. Routes resolve context by slug. The middleware auto-creates empty graph definitions in GraphStore on first request (code-first mode).

| Option | Type | Default | Description | |--------|------|---------|-------------| | agents | AgentConfig[] | — | Multi-agent config (mutually exclusive with stateSchema/nodes) | | sharedNodes | NodeDefinition[] | [] | Common nodes registered to every agent | | stateSchema | StateSchema | — | Single-agent: LangGraph StateSchema | | nodes | NodeDefinition[] | — | Single-agent: node definitions |

mountRoutes (low-level)

For full control over component creation. See examples/full-stack/ for a complete example.

REST Endpoints

All endpoints are prefixed with /linforge by default.

| Method | Path | Description | |--------|------|-------------| | GET | /graphs | List graphs | | POST | /graphs | Create graph | | PATCH | /graphs/:slug | Update graph metadata | | GET | /graph/:slug | Get graph definition | | PUT | /graph/:slug | Save graph definition | | POST | /graph/:slug/run | Trigger a run | | GET | /graph/:slug/runs | List run history | | GET | /runs/:runId | Get run details | | GET | /runs/:runId/steps | List steps for a run | | GET | /registry/nodes | List registered nodes | | GET | /prompts/:nodeId | List prompt versions | | GET | /prompts/:nodeId/active | Get active prompt | | POST | /prompts/:nodeId | Create prompt version | | POST | /prompts/:nodeId/versions/:id/activate | Activate prompt version | | GET | /templates | List available templates | | POST | /graph/:slug/apply-template | Apply template to graph |

Optional stores (runStore, stepPersister, promptStore) return 501 when not provided.

React Hooks

import {
  useLinforgeGraph,
  useLinforgeGraphList,
  useLinforgeRuns,
  useLinforgePrompt,
} from 'linforge/react';

| Hook | Purpose | |------|---------| | useLinforgeGraph | Graph editing (nodes, edges, save) | | useLinforgeGraphList | Graph list CRUD | | useLinforgeRuns | Run management (trigger, list, detail) | | useLinforgePrompt | Prompt version management |

Custom Store Adapter

Implement the four interfaces to connect any database:

import type { GraphStore, RunStore, StepPersister, PromptStore } from 'linforge/core';

class MyGraphStore implements GraphStore {
  async getGraph(slug: string) { /* ... */ }
  async saveGraph(graph) { /* ... */ }
  async listGraphs() { /* ... */ }
}

// Pass to middleware
app.use(linforgeMiddleware({
  stateSchema: MyState,
  nodes: [planner],
  stores: { graphStore: new MyGraphStore() },
}));

See linforge-adapter-prisma for a reference implementation.

Examples

• Quick Start — Minimal server (~30 lines)
• Full Stack — Manual assembly with all components

License

MIT