Skip to content
LumenFlow

What is LumenFlow?

LumenFlow is an open-source runtime kernel that governs what AI agents can do, proves what they did, and enforces policies they cannot bypass. Like an operating system kernel mediates between programs and hardware, LumenFlow mediates between agents and everything they touch — filesystem, git, APIs, and cloud services.

The Problem

Section titled “The Problem”

AI agents are powerful but unconstrained. They can read any file, write anywhere, and call any tool — with no audit trail and no policy enforcement. When agents go wrong, there is no proof of what happened and no mechanism to prevent recurrence.

LumenFlow solves this by inserting a governance layer between agents and the world.

How It Works

Section titled “How It Works”

Every agent action passes through three stages before it executes:

Agent calls a tool (e.g., file:write, git:commit)
      ↓
Scope intersection: does the agent have permission?
  workspace ∩ lane ∩ task ∩ tool scopes must all agree
      ↓
Policy evaluation: does any policy deny this action?
  deny-wins cascade — a deny at any level is final
      ↓
Execution + evidence: tool runs, receipt is recorded
  content-addressed input, timestamped trace, immutable log

Core Architecture

Section titled “Core Architecture”

LumenFlow has two layers:

LayerWhat it does
KernelScope intersection, policy engine, evidence store, tool dispatch. Domain-agnostic.
PacksPluggable extensions that teach the kernel how to work in a specific domain.

The kernel provides four guarantees:

  1. Scope intersection — 4-level permission model (workspace, lane, task, tool) where all levels must agree
  2. Deny-wins policies — restrictive policies at any level cannot be loosened by a lower level
  3. Evidence receipts — every tool call produces an immutable, content-addressed audit record
  4. OS-enforced isolation — bwrap sandbox with write confinement and secret deny overlays

Packs are self-contained plugins that declare tools, policies, and evidence types. The first-party pack set currently includes:

  • Software Delivery — Work Units, lanes, gates, worktree isolation, and memory for software teams
  • Sidekick — workspace-local tasks, memory, routines, channels, and status under .sidekick/
  • Agent Runtime — governed model turns, tool gating, and agent-session orchestration

Works with Any AI

Section titled “Works with Any AI”

LumenFlow is friction-free for any AI coding assistant. If your AI can read project files, it can use LumenFlow — just point it at AGENTS.md and LUMENFLOW.md.

Any AIEnhanced Integrations
Works out of the box with plain markdown instructionsClaude Code, Cursor, Windsurf, Cline get deeper features
No vendor lock-inAuto-detection, skills, vendor-specific configs
Universal entry points: AGENTS.md, LUMENFLOW.mdOptional overlays: .claude/, .cursor/, .windsurf/
CLI commands work everywhereMCP server for programmatic access

Quick Example

Section titled “Quick Example”
# workspace.yaml
version: '2.0'
lanes:
  enforcement:
    require_parent: true
  definitions:
    - name: 'Framework: Core'
      code_paths: ['src/core/**']
    - name: 'Experience: UI'
      code_paths: ['src/components/**']
gates:
  format: npx prettier --check .
  lint: npm run lint
  typecheck: npm run typecheck
  test: npm test
# Create and claim a work unit
pnpm wu:create --title "Add user auth" --lane "Framework: Core" \
  --type feature --exposure backend-only \
  --description "Add authentication" --acceptance "Users can log in" \
  --code-paths "src/auth/" --test-paths-unit "src/auth/__tests__/" \
  --plan

# wu:create prints the generated ID (example: WU-123)
pnpm wu:claim --id WU-123 --lane "Framework: Core"
pnpm wu:brief --id WU-123 --client <client>

# Work in the worktree
cd worktrees/framework-core-wu-123
# ... make changes ...

# Run gates in the worktree, then complete from main
pnpm wu:prep --id WU-123
cd /path/to/repo && pnpm wu:done --id WU-123

Next Steps

Section titled “Next Steps”