AI Coding Assistant Integrations

Works with Any AI

LumenFlow is friction-free for any AI coding assistant. If your AI can read project files, it can use LumenFlow.

Universal Entry Points

Every project includes plain markdown files that work with ANY AI: - AGENTS.md — Universal agent instructions - LUMENFLOW.md — Workflow fundamentals - .lumenflow/constraints.md — Non-negotiable rules

No Vendor Lock-in

Point any AI at these files and it understands the workflow. No special setup, no proprietary formats.

# Initialize with universal files only (works with any AI)
lumenflow init

---

Enhanced Integrations

For popular AI coding assistants, LumenFlow provides optional enhanced integrations with deeper features like auto-detection, skills, vendor-specific configurations, and agent-plugin discovery where the vendor supports it.

Assistant	Config File	Auto-detected	Enhanced Features
Claude Code	CLAUDE.md, .claude/	Yes	Skills, agents, hooks, settings, plugin distribution
Cursor	.cursor/rules/lumenflow.md	Yes	Rules integration
Windsurf	.windsurf/rules/lumenflow.md, .agents/skills/	Yes	Rules integration plus shared-skill discovery
Cline	.clinerules	No	Rules file
Codex	AGENTS.md, .agents/skills/, .codex/agents/	No	Universal files, shared skills, subagent overlays
Aider	.aider.conf.yml	No	Config file

Agent plugins are an on-ramp

The LumenFlow Claude/Codex plugin path is a planned capability. Installing a plugin helps the AI client discover skills and first-run guidance, but it does not create Work Unit state, gates, hooks, GitHub Actions, or evidence in your repository. Run lumenflow init for new repositories or pnpm lumenflow:integrate --sync for existing LumenFlow repositories when you want enforcement.

---

Context Discipline Guidance

pnpm lumenflow:integrate --client <x> projects a configurable context-discipline rule into supported shared and vendor-specific surfaces. The rule is advisory by default: it changes generated agent guidance, not gates or hooks.

software_delivery:
  agents:
    context_discipline:
      enabled: true
      full_file_read_exceptions: []

When enabled, generated guidance tells agents to search before reading files, prefer range reads over whole-file reads, and read a full file only when preparing to edit that file or when an explicit full_file_read_exceptions entry applies. Set enabled: false to stop future projection of the generated guidance.

---

Semantic Model Routing

Generated agent overlays can be routed through a vendor-neutral model contract:

model_profile: fast | balanced | deep
reasoning_effort: low | medium | high | xhigh

Shared agent definitions express intent with those semantic fields. Vendor-specific overlays remain projections: Claude Code receives frontmatter such as model and effort, while Codex receives model_reasoning_effort and may omit a model when the client default should apply.

Profiles are translations

model_profile is intentionally leaky. A Claude model family, an OpenAI-style reasoning effort knob, and a future client route are not identical capabilities. Treat profiles as routing intent and inspect the resolved vendor fields when behavior matters.

Workspace owners can override the per-client profile map in workspace.yaml:

software_delivery:
  agents:
    clients:
      claude-code:
        routing:
          model_profiles:
            fast: haiku
            balanced: inherit
            deep: opus
      codex-cli:
        routing:
          model_profiles:
            deep: inherit

Use the debug command to see the effective route:

pnpm agent:resolve --client claude-code
pnpm agent:resolve --client codex-cli --json

The report lists each agent alias, model_profile, reasoning_effort, mapping source, resolved model, and rendered vendor fields. pnpm lumenflow:integrate --client claude-code and pnpm lumenflow:integrate --client codex-cli render the same semantic contract into the vendor overlay files and record schema-valid agent:model_resolved telemetry for downstream consumers.

---

Quick Setup

1. Any AI (universal)

   lumenflow init

   Creates AGENTS.md, LUMENFLOW.md, .lumenflow/, and agent onboarding docs (including CLI command reference) — works with any AI that can read files. Use --minimal to skip onboarding docs.

2. Specific AI (enhanced)

   lumenflow init --client claude    # Claude Code
   lumenflow init --client cursor    # Cursor
   lumenflow init --client windsurf  # Windsurf
   lumenflow init --client cline     # Cline
   lumenflow init --client aider     # Aider

   Adds vendor-specific configs alongside universal files.

3. All integrations

   lumenflow init --client all

   Creates config files for all supported AI assistants.

---

Integration Details

Claude Code (Anthropic)

Claude Code has the deepest integration with LumenFlow.

Config Files:

• CLAUDE.md — Root-level instructions
• .claude/settings.json — Permission configuration
• .claude/agents/ — Agent definitions
• .claude/skills/ — Skill definitions (domain expertise)

Auto-detection: Environment variables CLAUDE_PROJECT_DIR or CLAUDE_CODE

Unique Features:

• Skills system for loading domain expertise on demand
• Agent spawning for parallel work
• Hooks for automated workflows
• Memory layer integration

Enforcement Hooks

LumenFlow generates Claude Code hooks in .claude/settings.json to enforce workflow compliance at the tool level. Configure enforcement in workspace.yaml:

agents:
  clients:
    claude-code:
      enforcement:
        hooks: true # Master switch for all hooks
        block_outside_worktree: true # Block Write/Edit to main
        require_wu_for_edits: true # Require claimed WU
        warn_on_stop_without_wu_done: true # Warn on incomplete session

After configuration, generate the hooks:

pnpm lumenflow:integrate --client claude-code

Hook Types

LumenFlow generates hooks for the following Claude Code hook events:

Hook Event	When It Fires	What LumenFlow Does
PreToolUse	Before Write/Edit operations	Blocks edits outside worktree or without claimed WU
PostToolUse	After every tool call	Auto-checkpoints at configured interval (counter-based)
SubagentStop	When a sub-agent finishes	Always creates a checkpoint (sub-agent completed work)
Stop	When session ends	Warns about active worktrees without wu:done
PreCompact	Before context compaction	Saves checkpoint + writes durable recovery file
SessionStart	After compact/resume/clear	Reads recovery file, surfaces unread coordination signals

PostToolUse and SubagentStop Hook Wiring

When memory.enforcement.auto_checkpoint.enabled: true, the enforcement generator creates hooks for automatic checkpointing:

memory:
  enforcement:
    auto_checkpoint:
      enabled: true
      interval_tool_calls: 30

PostToolUse fires after every tool call. The generated hook script:

1. Detects the active WU from the worktree path
2. Increments a per-WU counter stored at .lumenflow/state/hook-counters/<WU_ID>.json
3. When the counter reaches interval_tool_calls, creates a checkpoint in a background subshell and resets the counter
4. Returns immediately (exit 0) so the agent is never blocked

SubagentStop fires when a spawned sub-agent completes. The generated hook script:

1. Detects the active WU from the worktree path
2. Always creates a checkpoint (no counter — sub-agent completion is a natural milestone)
3. Checkpoint writes are backgrounded to avoid blocking

Both hooks use the same generated script (auto-checkpoint.sh) and branch on the hook_event_name environment variable set by Claude Code.

Caution

Auto-checkpoint hooks require the enforcement master switch (agents.clients.claude-code.enforcement.hooks: true). When auto_checkpoint.enabled is true but the master switch is off, LumenFlow emits a warning and remains advisory-only.

PreCompact and SessionStart Recovery

The PreCompact hook saves a checkpoint and writes a durable recovery file before context compaction. The SessionStart hook reads recovery files after compaction, resume, or clear events, restoring context for the agent.

For non-worktree orchestrators (agents running on main), these hooks surface unread coordination signals via mem:inbox so agents retain coordination awareness after compaction.

Cursor

Config Files:

• .cursor/rules/lumenflow.md — LumenFlow rules

Auto-detection: Environment variables starting with CURSOR_

Windsurf

Config Files:

• .windsurf/rules/lumenflow.md — LumenFlow rules

Auto-detection: Environment variables starting with WINDSURF_

Cline

Config Files:

• .clinerules — LumenFlow rules (root-level)

Auto-detection: Not supported

Aider

Config Files:

• .aider.conf.yml — Aider configuration

---

Using Another AI?

Tip

If your AI coding assistant isn’t listed above, LumenFlow still works perfectly:

1. Run lumenflow init to create universal entry points
2. Tell your AI to read AGENTS.md and LUMENFLOW.md
3. The workflow commands (wu:claim, wu:prep, wu:done) work the same

---

Keep Configs in Sync

All vendor configs are generated from a single template:

# Check if configs are in sync
./scripts/sync-vendor-configs.sh --check

# Regenerate all configs from template
./scripts/sync-vendor-configs.sh

The template lives at templates/vendor-rules.template.md.

---

Adding New Integrations

Want to add support for another AI assistant? Contributions welcome:

1. Update templates/vendor-rules.template.md (single source of truth)
2. Add vendor config path to scripts/sync-vendor-configs.sh
3. Add scaffolding in packages/@lumenflow/cli/src/init.ts
4. Update this documentation
5. Test with lumenflow init --client <vendor>