Lumen
Download
Docs

How to actually use Lumen.

Short, opinionated, no marketing. If anything here is wrong, file an issue on GitHub.

Install

Windows is the supported platform today. Grab either build from the releases page.

  1. Installer (recommended). Download Lumen-Setup-vX.Y.Z.exe. SmartScreen will warn — Lumen isn’t code-signed yet. Click More info → Run anyway. Installs per-user at %LOCALAPPDATA%\Programs\Lumen\. No admin needed, clean uninstall via Apps & Features.
  2. Portable zip. Download lumen-vX.Y.Z-windows-x64.zip, extract, run lumen.exe. No auto-update — you grab the next zip manually.

First run

On first launch a wizard walks you through picking at least one LLM provider — Ollama if you want local and free, or any of the cloud ones. You can skip it and configure later from Help → Setup Wizard… or Settings.

At least one provider has to be configured for chat, chat summaries, and skill generation to work. Everything else — editor, file explorer, terminal, SSH, Teams, YouTube — runs fine without any LLM.

Providers

Lumen talks to:

  • Ollama — local, no API key, free. If the daemon isn’t running, a banner shows up above the composer with a one-click open setup button. No silent failures.
  • Ollama Cloud — same protocol, hosted.
  • Anthropic (Claude) — paste your API key.
  • Gemini — Google AI Studio API key.
  • GitHub Copilot — uses your existing subscription via the Copilot CLI. Sign in once.
  • OpenAI-compatible — any endpoint matching the OpenAI chat-completions schema. xAI, Mistral, Together, local gateways, etc.

You can have multiple providers configured simultaneously and switch models per-chat from the composer.

Chat & tools

The composer has chip-based file and folder references, image attachments (clipboard paste works), prompt queueing, and per-tool approval. Tool approvals are persisted per-command so you only approve pip install once.

Files mutated by the agent get inline accept/revoke decorations in the editor — so you can stage changes turn-by-turn before they hit disk as final.

Council mode

Multi-agent orchestrated deep work. You give it a brief, it builds a team (architect, researcher, tester, reviewer, etc.), assigns roles, and runs them through Discovery → Architecture → Build → Review → Polish/Ship phases with a quality gate and a one-shot adversarial critic at the end.

The visual layer is theatrical — bobbing cards, sweep gradients, mention tethers, return packets on done — but the orchestration is real. Every agent has its own model, system prompt, tool budget, and the orchestrator routes mentions and subtasks through a shared blackboard.

Sessions persist. Open the Council pane → recent sessions to replay or branch off an earlier run.

SSH & Remote

A proper SSH layer baked into the IDE, not a plugin.

  • Vault. Hosts stored in a two-tier vault: labels, addresses, fingerprints, and key paths in fast cold-read storage; passwords and key passphrases in the OS keystore (DPAPI on Windows). Nothing in a plaintext .json you’ll forget about.
  • Terminal pane. xterm-based session with OSC-7 cwd tracking. On-connect helper install drops lumen-edit, lumen-grab, and OSC-7 glue so the IDE knows where you are remotely.
  • SFTP browser. Modal browser that walks the remote filesystem from your OSC-7 cwd. Breadcrumbs, hidden-file toggle, direct-open into the editor.
  • Drag-and-drop upload. Drop a local file onto the Remote pane and it uploads via SFTP on the active session. Virtual drags from WinRAR, 7-Zip, and Gmail web work.
  • Remote-edit-on-save. Open a remote file via the browser, edit it locally, hit Ctrl+S. The diff is pushed back over the existing SFTP channel.
By design, the agent has no access to the SSH layer. It can’t see your hosts, read keys, open sessions, or run remote commands. This is a security choice. See the SSH section in the repo’s README for what is and isn’t on the roadmap.

Side panes (Teams / YouTube / Twitch / GitHub)

The right-side dock hosts webviews:

  • Microsoft Teams — sign-in works, channels, chats, calls. Keep work chat docked next to the editor.
  • YouTube — embedded player with workspace-scoped tab state. Auto-routes to the chat pane when SSH or Teams is using the main side slot.
  • Twitch — same treatment.
  • GitHub — for casual browsing without leaving the IDE.

Workspace skills, rules & knowledgebase

Every workspace gets a .lumen/ and .agents/ folder of LLM-facing context:

  • .lumen/skills/ — reusable skill files the agent can call. Skills can be auto-generated from your project’s README on first run if you opt in.
  • .lumen/rules.md — silently injected into every system prompt at workspace + global scope. Use it for project conventions: "always run flutter analyze after edits","the API folder is in services/, not lib/".
  • .agents/knowledgebase.md — the workspace knowledgebase, surfaced as a synthetic editor tab (Knowledge Base in the open-files row). Persistent memory between chats. Auto-injected into the system prompt on every turn. Auto-summarize button if it grows too large.

The trio together is what makes a long-running agent project survivable — you don’t have to re-explain your codebase every chat.

File timeline (revision history)

Every meaningful file mutation goes into a content-addressed blob store + append-only journal under <app-support>/lumen/timeline/<workspace>/. That includes:

  • Agent tool ops — every EDIT_FILE, MULTI_EDIT, WRITE_FILE, with (sessionId, turnId, messageId) correlation IDs.
  • Manual saves (your Ctrl+S writes).
  • External FS writes (files changed by other tools while Lumen is running).
  • Explorer actions — rename, move, delete via the file tree.

Scroll the Timeline rail, diff against any past version, restore in one click. Because every entry carries the agent correlation IDs, "go back to before the agent broke this" is one click.

Updates

Lumen polls GitHub Releases once per 12 hours, surfaces an Update available pill in the menu bar when there’s something new. On click it downloads the next installer to %TEMP%, closes itself via Restart Manager, runs the silent installer, and reopens. SHA-256 verified if the release asset carries a digest.

Force a check from Help → Check for Updates. The portable zip does not auto-update — you grab the next zip manually.

Build from source

Requirements: Flutter SDK, Visual Studio Build Tools with the C++ workload, Inno Setup 6 or 7 if you want the installer. flutter doctor will tell you what’s missing.

git clone https://github.com/haviduck/lumen.git
cd lumen
flutter pub get
flutter run -d windows

Release build:

flutter build windows --release

Installer build:

.\tools\installer\build.ps1

Outputs dist\Lumen-Setup-vX.Y.Z.exe and dist\lumen-vX.Y.Z-windows-x64.zip. The installer name is regex-matched by the auto-updater — don’t rename it.

Get help

Lumen is a solo project. The best path for anything broken is a GitHub issue with steps to reproduce — bug reports are gold.