Lumen

Every AI, one browser. Lumen is a fast, calm Chromium browser with an AI built into the sidebar. Bring the one you like: Claude (with your own Claude account through Claude Code), ChatGPT, Gemini, Grok, or any model on OpenRouter. Switch between them mid-conversation, or let any AI agent drive it over MCP.

_{A real, unedited run (about 18 seconds) of "Claude · your account (Claude Code)" with a Claude Code login. The capture profile auto-allows actions, so the approval card you'd normally see before the AI first acts on a site isn't shown. MP4 version.}

• An AI that does things, not just chats. It reads the page you're on and acts on it: clicks, types, fills in forms, opens and groups tabs, and researches several pages at once. It asks before acting on a new site, and a form that doesn't fill completely is never submitted.
• Your choice of model. Claude (Opus, Sonnet, Haiku, Fable), OpenAI, Grok, Gemini and OpenRouter. Use your Claude account through Claude Code, add a key, sign in to Anthropic with its CLI, or sign in with OpenRouter. The toolbar button takes on each company's mark.
• A real browser underneath. Tabs that group themselves by site or by topic, a bookmarks menu, a searchable history page, a downloads menu (with a list in Settings), find, zoom, Chrome Web Store extensions, a built-in ad and tracker blocker, fingerprinting and tracking protection on by default, and import from Chrome, Edge, Brave, Vivaldi, Opera or Firefox. Unused background tabs unload to free memory; Settings → Tabs and browsing → Page unloading sets when (a timer, low memory, a cap), which tabs and sites never unload, and what an unloaded tab shows. Your latest tabs, and the one under your pointer, are kept ready so switching back is quick (Keep the latest tabs ready).
• Private by default. No telemetry. Background reading and search run without your cookies, the scripts the AI uses to read pages run where sites can't see them, the current chat is encrypted at rest, and the start page makes no network requests.
• Calm to look at. Light and dark themes that follow your system, and spring animations.

Found a bug or have an idea? Report an issue · Report a security problem privately. In the app, use Help → Report an Issue (macOS) or Settings → Updates and about → Report a problem.

Install

Download the latest build from Releases. Each release lists which file is for which computer; the install guide walks through it step by step.

Computer	File
Windows 10/11 (x64)	Lumen-Setup-<version>.exe: double-click, no admin prompt, no wizard. It installs for you only and opens Lumen. (No installer wanted, or Smart App Control on? Lumen-<version>-win-x64.zip: unzip and run Lumen.exe.)
Mac with Apple silicon (M1 and later)	Lumen-<version>-mac-arm64.dmg: open it and drag Lumen onto Applications
Mac with Intel	Lumen-<version>-mac-x64.dmg: open it and drag Lumen onto Applications

Windows: the builds aren't code-signed. SmartScreen may say "Windows protected your PC": choose More info → Run anyway. On PCs with Smart App Control turned on, the zip is the one that runs. Its Lumen.exe is the untouched Electron binary, which Windows recognises, while a freshly built installer isn't. Or build and install locally (below).

Mac: from 0.4.4 the app is signed with an Apple Developer ID and notarized by Apple, so it opens with no prompt and needs no Open Anyway step (maintainers: docs/mac-signing.md). If you are updating from an older version, macOS asks once on the first launch to allow Lumen access to its Keychain item. Versions before 0.4.4 are self-signed, so their first launch is blocked: on macOS 15 Sequoia and later, open Lumen once (it is refused), then go to System Settings → Privacy & Security, scroll to Security and click Open Anyway next to Lumen; on older macOS, right-click Lumen in Applications and choose Open. If you open Lumen straight from the disk image or Downloads, it offers to move itself to Applications at launch (Settings → Updates and about keeps a Move to Applications button). When a new version is out, the toolbar says Move to Applications to update: one click installs the update into Applications (or into ~/Applications if you aren't an administrator), opens it and you're done, with no disk image and no second step. It never overwrites a newer Lumen that is already there, and asks you to quit another running Lumen first. If an older version won't open, or macOS says the app "is damaged", run:

xattr -dr com.apple.quarantine /Applications/Lumen.app

Updates: Lumen looks for a new release shortly after it starts and every few hours (Settings → Updates and about shows the result and has Check for updates). Every copy that can write to the folder it is installed in (the setup's per-user install, the zip, a hand-copied folder, the Mac app in Applications) updates itself the same way: it downloads the release's zip in the background ("Downloading Lumen vX…"), checks it, unpacks it next to the install, and shows Restart to update in the toolbar (and in Settings). One click applies it and relaunches; click it while it is still downloading and it restarts by itself the moment it is ready. On restart the old folder is swapped for the new one and Lumen reopens with your tabs; your settings, chats and shortcuts are not touched, and if the swap can't happen Lumen keeps the old version and says why in Settings. Turn off Download updates automatically to be asked first. If you quit with an update already downloaded, it is installed as Lumen closes (and Lumen is not reopened). A Mac copy outside Applications, or in an /Applications you can't write to, installs its update into /Applications or ~/Applications the same one-click way. Copies that can't replace themselves (a per-machine install under Program Files, the portable exe) show Lumen vX is available with a Download button for the Setup exe, the zip or the releases page instead. Downloads are checked against the SHA-512 hash in the release's latest.yml / latest-mac.yml; the builds aren't code-signed, so an update is only as trustworthy as the GitHub release it comes from. Lumen 0.2.4 and earlier have no updater: download a newer version by hand once.

On first launch the sidebar opens on a short welcome: connect an AI and bring your bookmarks and history from another browser (both can wait; Start browsing closes it). One optional line under it offers to make Lumen your default browser; it says nothing unless you click it. A question typed before any AI is connected is kept and sent once one is.

Set up an AI any time from the sidebar's empty state or Settings → AI (Ctrl+,; the sidebar's gear opens it): your Claude account through Claude Code, an Anthropic, OpenAI, Grok, Gemini or OpenRouter key (stored encrypted with the OS keychain), or Sign in with OpenRouter. ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, GEMINI_API_KEY and OPENROUTER_API_KEY work too.

The start page

Widgets sit around the search box: weather, a world clock, your calendar, tasks, mail, headlines, markets, a TradingView chart or watchlist, notes, a countdown, a Pomodoro timer, an AI status card, a Routines card (your next scheduled runs and latest results; a click opens the routine in the sidebar), a Files card of the files and folders you pinned or opened lately (and Ctrl+Shift+F to find any of them) and your own custom cards. Add, move, resize and edit them right on the page (Edit layout), and make them solid, frosted or clear.

Search or ask the AI from the same box (Search | Ask AI, Ctrl+/ and Alt+A switch; the choice belongs to that box only and never changes what the address bar does; each question starts a new chat in the sidebar), with your favorites and most-visited sites underneath. It's a local page with a strict Content Security Policy: it loads nothing from the network, and site icons come from a small local cache.

The AI in the sidebar

When the AI names a tab (in its answer, in a step such as switching to or closing a tab, or on the Browser card), the chat shows a tab chip: the tab's icon and current title. Click it to go to that tab, even in another window. A tab that has closed keeps its last title and, when its address is known, a click opens it again. Saved chats keep the chips, and Export chat writes them as "Title (address)".

When a chat finishes or needs your OK while you are elsewhere, Lumen tells you. In another app, it is a system notification. In Lumen on another tab, it is a toast in the tab strip with Open chat, which goes to the tab the AI worked in and opens the chat (macOS shows no banner for the app in front, so a system notification would go unseen). Both follow Tasks → Settings → Notify me when a task finishes or needs me.

Ctrl+J opens it (and moves the keyboard to its message box). On a web page it slides in over a picture of the page; on the new-tab page, and with Reduce motion or Performance mode on, it opens in one step like Chrome's side panel, so the new-tab page's cards and widgets never move. The AI reads the page and operates the browser. The sidebar is open or closed per tab: opening it in one tab never changes another, and a new tab starts with it closed.

• Low-level actions: click, type, keys and shortcuts, scroll, hover, click at a point on a screenshot, tabs, back/forward/reload.
• Uploading files: attach files to a message (the + menu → Attach files, drag and drop or paste take any file, up to 10 of up to 100 MB) and ask "upload my resume to this job form" or "attach this PDF to the assignment": upload_file puts the file in the page's file field, a hidden input behind a button or a drop zone included, and leaves the form for you to submit. See Asking before it acts and Uploading files for you.
• High-level actions:
  • click by visible text
  • fill_form fills a whole form by field labels
  • read_urls reads up to 6 pages in parallel in hidden tabs
  • read_pdf reads the text of a PDF open in a tab, only after you allow that PDF (a card, "Allow the AI to read ?", remembered for that chat; local and web PDFs alike; up to 30,000 characters per call, then a note naming the page to continue from (from), page markers, page ranges, and a query that returns the pages where some text appears). The text counts as page content, like read_page. Scanned pages have no text. A PowerPoint deck (.pptx) open in the slide viewer reads the same way, one page per slide with its speaker notes.
  • video_overview and video_frames let the AI look at a video in a tab: one timestamped contact sheet, then full-size frames at chosen moments (Lumen pauses and seeks the video and puts playback back as it was; DRM videos are refused). /watch-video runs it for you
  • read_tabs reads the text of several open tabs of the window in one call, without switching to them (6,000 characters per tab, 40,000 in all)
  • Ask across open tabs: type @ in the composer to pick tabs (or @all tabs, @this tab); their text goes with that message, labelled [Tab: title — host], and the message shows which tabs were attached. Sleeping tabs are sent by address only.
  • run_script runs JavaScript in the page for bulk extraction or edits
  • wait_for waits for text to appear
  • web search
• The page you're on goes with your message. Whichever AI answers (Claude by key or CLI sign-in, Claude Code, OpenAI, Grok, Gemini, OpenRouter), each message includes the current tab's title, address and first ~7,000 characters of readable text (not for new-tab or internal pages), marked as untrusted page content. The chip above the message box shows Using: ; click × to stop sending the page (remembered), Include to turn it back on.
• Voice input: the mic button in the chat box (the sidebar and the full-page chat) turns what you say into text. Click it to start and again to stop, or hold it, or hold Ctrl+Shift+Space (⇧⌘Space on a Mac) while the box has the focus, and let go to stop. A level meter and a timer show while it records; Esc cancels, and a recording stops by itself after two minutes. The text goes into the box for you to read over (or is sent at once with Send voice messages at once). It uses your own OpenAI key (gpt-4o-mini-transcribe, or whisper-1 when the key can't use it) or Gemini key (a Flash model), set in Settings → AI → Voice input (Automatic tries OpenAI, then Gemini). With neither key, the button says which one to add. The recording goes to that provider only and is never saved. Chromium's built-in speech recognition can't work in Lumen (it needs Google's own key), which is why a key is needed. The Meeting helper's Listen uses the same voice input, in 20-second pieces.
• Context and commands: the ring left of Send shows how full the chat's context window is (hover for the numbers, click for the breakdown). Type / for the chat's commands: /compact (summarize the chat so far to free up room; Claude Code runs its own, an API model writes the summary; optional instructions after it), /context, /clear, /cost, /usage, /model, /memory and /help, plus your skills. Long API chats compact themselves before the oldest messages would be left out (Settings → AI).
• Helpers that act in tabs (off by default): with Settings → AI → Let helpers act in tabs on, the AI can split a browser job with independent parts ("fill in this contact form on these three sites", "check the order status in these accounts") into up to 3 helpers that work at the same time, each in a background tab of its own (marked with the sparkle). A finished helper's tab is closed by When the AI finishes like the AI's other tabs; a helper that is stopped, fails or runs out of time has its tab closed at once, since it may hold a page you're signed in to. Each helper shows in the chat as a small card with what it is doing, a chip for its tab and Stop; Stop in the chat stops them all. Helpers can navigate, click, type, fill forms, find, read the page and take screenshots, at most 20 steps and 5 minutes each, on the cheaper helpers' model. They can't run scripts, upload files, switch tabs or use other apps, and they're told never to buy, send or submit: they stop before that step and report back. fill_form with submit is refused for them, and they open http and https pages only. Several helpers heading to the same new site share one card. Their approval cards are the chat's own, marked "Helper 2: …"; sites you already allowed in the chat carry over. What they report goes back to the AI as page content, not instructions. Only with API key models; Claude Code, Grok Build, Antigravity and Codex use their own subagents.
• Google Drive and Sheets connectors: sign in once with Google in your own browser (Settings → Apps and connections) and the AI can find and read your Drive files and Google Docs, make a folder, upload a file from this computer (one file per card, from a chat attachment or, if you allowed files on this computer, a path that is never in a credentials folder), replace the contents of any Drive file, or up to 25 same-named files in a folder on one card, rename, move, copy or trash a file (never delete it for good), share a file by link, read a spreadsheet and add rows to it. Each write shows a card with exactly what will be sent and needs your click on Allow. See Connectors.
• More connectors: Google Docs, Calendar, Tasks and Contacts on the same Google sign-in; Outlook, OneDrive (including Word, Excel and PowerPoint files) and Outlook Calendar on one Microsoft sign-in; Zotero; and one-click cards that add the official MCP servers of Linear, Atlassian, Sentry, Canva and Hugging Face. Anything that changes something shows a card first. See Connectors.
• Connectors that write, on your say-so: with GitHub, Notion or Todoist connected (Settings → Apps and connections), the AI can comment on an issue or pull request, open an issue, add a Notion page under a page you shared or add text to the end of one, and add a Todoist task. Each one shows a card with exactly what will be sent, in boxes you can edit, and happens only when you click Allow: there is no Always, and Auto-allow and Bypass permissions don't answer it. The result shows in the chat as a step with Open. Background tasks and routines only read. With Gmail, press Allow drafts on its card once (Google asks for permission to make drafts) and the AI can put a new email or a reply in your Gmail Drafts, with To, Cc, Subject and the text editable on the card. A draft is never sent by itself: you open it in Gmail and send it. Sending is a separate switch, Allow sending on the Gmail card (off by default, under Allow drafts). With it on, each email shows on a card with From, To, Cc, Bcc, Subject, the whole text and the attachments, and goes only when you press Send. If you type in a chat that the AI may send, that chat sends to the addresses you typed after a 10 second Undo. At most 10 emails an hour, never from background tasks or routines. Lumen keeps the time, recipients and subject of each send in a plain, unencrypted file (gmail-send-log.json) in the profile folder; Sent by the AI on the card lists it. Calendar events aren't possible yet, because an iCal address is read-only. See Connectors.
• Skills: saved instructions you run with /name (Settings → Skills). Import or export a skill as a SKILL.md folder, the Agent Skills format Claude Code uses, or turn on Use my Claude Code skills to list ~/.claude/skills read-only. Lumen skills are instructions only: scripts in a skill folder are never run. Tick AI can use this on its own and the AI loads the skill (use_skill) when your request matches. With Offer to save and improve skills on (off by default), a long task that went well gets a Save how I did this as a skill? card, and a skill you corrected gets Update the skill with what changed? with a diff to accept. See Skills.
• Notes: ⋯ → Notes is a small notepad that keeps its text across tabs and restarts: several notes, search, plain text you can write Markdown in (with a Preview), saved as you type. Add to notes sits under AI replies (diagrams and pictures come along) and in the right-click menu for text you select on a page. Ask AI sends a note to the chat, and the AI can read your notes and add to them, never edit or delete. Details: Notes.
• Memory (off by default): with Settings → AI → Memory on, the AI keeps short notes about you between chats when you tell it something ("remember that I'm vegetarian"). Each save shows in the chat with Undo and Forget, only what you said is saved (never text from a page), passwords and card numbers are refused, and temporary chats never use it. It can also search your past chats. See and delete the notes in Settings or with /memory. Details: Memory.
• Research: /research <question> (add --quick or --deep, --academic, --since 2020) plans a few sub-questions, searches and reads sources side by side, and answers with a numbered citation after every claim that links to the exact passage, then a Sources list and what to verify. The AI's find_sources tool searches OpenAlex, Crossref, Semantic Scholar, arXiv and PubMed (free, no key) for papers with DOIs, open-access PDFs, citation counts and retraction flags. The Research board (book button in the sidebar) keeps each chat's sources with type, year, citation and retraction chips, your notes and pinned quotes (checked against the text the AI read), "Add this page" for the tab in front, and copies citations or the whole bibliography as APA 7, MLA 9, Chicago, IEEE, BibTeX or RIS.
• ADHD mode (on by default, toggle in Settings → AI): answers lead with the next action, use short numbered steps, and end with one small next step.
• Other AI models: add an OpenAI, Grok (xAI), Gemini or OpenRouter key in Settings → AI. Their models appear in the model menu, work with every browser tool, and can take over a chat mid-conversation.
• OpenRouter: paste a key or Sign in with OpenRouter (OAuth with PKCE through a one-time local address; the key it returns is stored like a pasted one). The menu shows the newest Claude, GPT, Gemini, Llama, DeepSeek and Grok models; More models… searches all of them (the list is cached for a day). Models that can't use tools are marked (chat only): they read the page with you but can't click or type in your tabs.
• Local models (Ollama and LM Studio): in Settings → AI → AI providers → Local, switch on Use local models, pick Ollama or LM Studio, and press Detect. Lumen lists the models you have installed, and they join the model menu under Local. No key, and nothing leaves your computer: only localhost, 127.0.0.1 and ::1 addresses work unless you confirm another one. Models that support tools can click and type in your tabs; the others answer as plain chat (the list says which is which). Auto and the automatic model switching never use a local model, and a local model that fails is never handed to a cloud one. See Local models.

Asking before it acts

• New sites. The first time the AI clicks, types, hovers, presses keys or runs a script on a site in a chat, a card asks you to allow it. The bolt in the sidebar head (Auto-allow actions) skips these cards for the sidebar's own AI. Agents connected over MCP work in a Lumen window of their own and, with Settings → AI → Agents in their own window don't ask (on by default), act there without cards, so they keep working while Lumen is in the background; turn it off to approve each new site.
• Leaving with what it read. Once the AI has read content in a chat (read_page, find, screenshot, run_script, read_urls, list_tabs, batch, read_pdf, read_tabs, video_overview, video_frames, or the page text Lumen sends with your message), navigating to, opening or fetching a site not yet approved in that chat shows a card ("Claude wants to open "), one per new site. Approving adds the site to the chat's approved sites. This lasts for the whole chat and resets on New chat; a chat restored after a restart counts as having read content. Approved sites, and everything while Auto-allow is on, skip the card; MCP agents are always asked. This is so a page can't quietly tell the AI to carry what it read off to another site. The same card appears when an approved site redirects to a new one, and before the AI's web_search sends its query to DuckDuckGo, or find_sources sends its query to the scholarly databases (the card shows the query).
• Your content stays put. When the AI types, presses Delete, runs a script or clicks a Delete button, Lumen measures the field or editor it touched. If that would remove (or did remove) a lot of what you wrote, or any image or table, it asks first, or puts the content back and asks Keep the change / Undo it, even with Auto-allow on. Under a reply, Undo the AI's edits on this page restores the fields and editors it changed, and the AI checks what it really changed (verify_changes) before saying content is unchanged. Details: The AI and your content.
• The AI's tabs in one group. Every tab the AI opens in a window goes into one gray AI tabs group, folded, so a task that opens dozens of pages adds one label to your tab strip instead of a row of tabs. Click the label to unfold it (it stays unfolded). A tab you start typing in leaves the group and is yours. Research tabs keep their own purple AI: … groups. Turn it off in Settings → AI → Tabs the AI opens → Group tabs the AI opens.
• Closing the AI's tabs. Tabs the AI opens are marked with a small sparkle on their icon and open behind your tab, and close again when it finishes (with Undo), except the tab you are looking at, one playing sound or holding text you typed, and one the AI marks as still needed (a page you asked to see, a sign-in or checkout left for you). With When the AI finishes set to Leave open, a reply that opened tabs shows Close N tabs this chat opened instead; the tab menu's Close tabs the AI opened and a chat's ⋯ menu do the same. A tab you pin, navigate, group, move to another window or type in becomes yours and stays. A tab a chat is still working in is kept. Settings → AI → Tabs the AI opens has the controls for them: Hide AI tabs, When the AI finishes (Close, the default, Ask or Leave open) and Bring tabs the AI opened to the front. The Hide button in the tab strip says "1 needs you" when a hidden tab wants an answer, and clicking it shows that tab; right-click it (or press the Menu key or Shift+F10) for Close tabs the AI opened, in all windows.
• Uploading files. The AI can never name a file on your computer: upload_file takes only the refs of files you attached to the chat, or asks you with a card whose Choose file… button opens your computer's file picker (you pick; it learns the name). A page can't talk it into uploading anything else. An attached file's contents are never sent to the AI (a picture goes as a picture, as before; other files only by name and size). It is an acting tool: a site with AI off, a tab you keep it off and hands-off mode all refuse it, the first action on a site asks as above, and the first upload of an attached file to a site in a chat shows a card with the file names and the site (Upload / Don't upload; later uploads there are a step in the reply). Auto-allow skips those cards, never the need for you to have attached or picked the file. Files wait in your profile's uploads folder and go with the chat when you delete it. Details: Uploading files for you.
• Your signed-in accounts. read_urls reads pages signed out. When the AI needs your own account page (your grades, your orders) it can ask with as_user: a card "Let the AI use your signed-in account?" offers No (the default), Just this once or Always for . Allowed, the page opens in a background tab of your own session, grouped "AI: (signed in)", is read, and closes when the reply is done unless you switched to it. It is per host, read only (clicking or typing there still asks as above), and a redirect to any other host is read signed out instead. Banks, payment services, password managers and account-security pages are only ever Just this once. The sites you allowed always are listed, with Remove and Remove all, in Settings → AI → Signed-in sites the AI can use. Auto-allow doesn't cover this card, and agents connected over MCP (and background tasks) always read signed out. The AI's own tab actions (navigate, open_tab) work in your tabs as before, signed in.
• Files the AI makes. When the AI writes a page, diagram, picture or PDF for you, or names a file on your computer, the reply shows a file card with Open, Show in folder and Copy path instead of telling you to open it in a browser. A page or SVG the AI wrote previews live in the card (in the same sandbox as the canvas: no network, no way into Lumen) and opens in the canvas on the full-page chat; a picture shows as a thumbnail; a Word, Excel or PowerPoint file shows its first page (the first sheet's top-left cells, the first slide), and a click on it opens the file in Lumen's own viewer in a tab (on the full-page chat, Open in canvas shows it larger); a PDF opens in Lumen's viewer in a new background tab. Only a file the AI wrote in that chat previews or opens by itself: a file it only mentioned gets a card, and Open asks you first. Programs and scripts are never run from a card. Off for local files when Turn off AI here is on for them.
• Everything at once: AI activity. lumen://tasks (Ctrl+Shift+X, the sidebar's ⋯ menu, or Open full view in the Tasks panel) shows on one page what is waiting for you, what is running (chats, background tasks, routines and outside agents, with Stop and Go to), what is scheduled and the last 50 runs. Plain approval cards can be answered there, through the same path as the card itself. Details: AI activity.
• Schedule from the full-page chat. The clock button beside Copy on a reply, /routine, or typing a message that starts with a schedule ("every weekday at 8am: check my email", then Schedule it) opens a small Schedule this dialog on lumen://chat. It saves a routine that runs in the background; you edit it in the sidebar's Routines tab or Settings.
• Plan first. For a task you want to see before it happens, turn on Plan next to the message box (or type /plan <task>). The AI then only reads: the page, your tabs, other pages in the background and web searches. Anything that clicks, types, navigates, opens tabs, uploads or runs a script is refused for that message, in the tool layer, not just by instruction. It ends with a plan card: numbered steps, the sites it will act on and the risky steps (buying, paying, sending, posting, submitting, deleting). Run plan sends the plan as your next message, turns Plan off for the chat and lets the AI click and type on the sites on the card without asking again. Those sites come from the AI, which may have read them on a page, so opening a site, searching or sending something to one after reading a page still shows its card, and so does a script, and the AI is still told to stop before buying or sending. Edit makes the steps editable and lets you remove sites before you run it; Keep planning keeps Plan on so your next message changes the plan. Start new chats in plan mode (Settings → AI, just under Asking before it acts; off by default) starts every new chat with Plan on. Plan first works with API models (Claude, OpenAI, Gemini, Grok, OpenRouter); Claude Code, Codex, Grok Build and Antigravity bring tools of their own that Lumen can't hold back, so the button is off on them.
• From your phone (Telegram). Send requests to your own Telegram bot and Lumen runs each one as a background task, then sends the result back to the chat. Each task starts with no allowed sites, so every site it opens, and every step that buys, sends or submits, asks in the chat with Allow and Deny buttons. Forwarded messages are never run. Set it up in Settings → AI → Phone (Telegram): a bot token from @BotFather, then Pair with a 6-digit code; only the paired chat is answered. Only while Lumen is open; off by default. Messages and results pass through Telegram's servers. How it works.
• Phone to Lumen files and links. Send a photo or a file to the same bot and it is saved to Downloads/From phone, with an Attach to chat toast; its caption goes into the prompt, never sent by itself. Send a link and it opens as a tab. The other way round, Send to phone in a page's or a download's menu sends the link or the file to your chat. Up to 20 MB in and 50 MB out (Telegram's limits). Details.
• Phone to Lumen over Wi-Fi, no app. File → Receive from phone (Wi-Fi)… (or From your phone (Wi-Fi) in the chat's + menu) shows a QR code. Scan it, pick photos or files on your phone (up to 2 GB each), and they arrive in Downloads/From phone; from the + menu they go straight into the message box. Lumen listens only while the code is on screen, on your local network, for the first phone that opens it. Use it on Wi-Fi you trust. How it works.
• Several messages in a row. Keep typing while the AI replies: each message waits under the reply as a dimmed bubble ("Queued", "Queued · 2nd"), with Send now, Edit and ×, and goes by itself, in order, when the reply ends. Send all as one sends the waiting ones together as one message. A small mark on each of your messages says where it is: a clock (queued), one check (sent), two (read by the AI: its reply began). Stop, or a reply that fails, puts the waiting messages back in the box. While the AI works and its card is scrolled out of sight, a pill over the chat shows what it is doing and for how long, with Stop; click it to go back to the card.
• Bypass permissions. One switch for "stop asking me": the button in the sidebar head (and the full-page chat header) shows the current level's icon and name, one click switches to the next (Ask, Auto, Bypass, back to Ask; going up asks for a second click to confirm), and a right-click opens a small menu (with a link to Settings) with three levels, Ask (the default), Auto-allow actions (the per-site cards only, as before) and Bypass permissions (also in Settings → AI → Asking before it acts, with a longer explanation). With Bypass on, every approval card above is answered Allow for you: new sites, leaving with what it read, a script after reading, the picture and search cards, a PDF, your signed-in accounts, an attached file going to a site, an MCP tool you added, Grok Build's terminal commands, and for connected agents too. Each one shows as a step in the chat ("Allowed automatically: …"), a red bolt and a Bypass permissions on badge above the message box say it is on, and turning it on takes a second click. The AI won't ask before acting, reading PDFs, using your signed-in accounts, or sending what it read anywhere, so a page it reads could steer it: use it only when you trust the sites. What still holds: sites where you turned AI off, tabs you keep it off, hands-off mode, and uploads only ever using files you attached or picked (the Choose file… card still waits for you, since Lumen can't pick a file for you). The model is still told to stop before purchases and sending messages, but that is an instruction, not a block. Background tasks and routines don't bypass unless you also turn on Bypass in background tasks and routines too (Settings → AI): then their cards, including the steps that buy, send, post or submit something, are answered Allow with nobody watching, and each shows in the task's steps. That option switches itself off when you leave Bypass permissions. Off by default.
• What it can see of your tabs. list_tabs shows the AI only web pages and blank new tabs, with query strings and #fragments removed; internal pages (settings, history) and file:// tabs are left out, and switch_tab can only go to the tabs it lists.
• Only web pages. The AI can only open http and https addresses.
• Sensitive steps. The AI is instructed to stop and ask before purchases, payments, sending messages, posting, deleting data, changing account settings, or submitting personal information, and never to type passwords, card numbers or one-time codes. These are instructions to the model, not hard blocks. What Lumen enforces itself: the values of password fields are never included when the AI reads a page, and fill_form does not submit a form when any field failed to fill.
• Saved passwords (off by default). Settings → Privacy and security → Save passwords offers to save a sign-in on https sites and fills it when you click the key in the address field; Lumen never fills or submits by itself. They're encrypted with your OS keychain. The AI and outside agents have no way to read them: after you fill one, run_script is refused on that site in that tab, and fills are refused while a CDP client is connected.
• Page content is untrusted. Page text, search results and screenshots reach the model marked as data, not instructions.

Your own Claude account, through Claude Code

If Claude Code is installed, the model menu starts with a Your Claude account group: Claude · your account (Claude Code). Each message runs your own claude CLI headless, signed in with your own login (including a school or work plan), and it drives Lumen through Lumen's MCP server:

• Lumen never sees your claude.ai credentials; the CLI keeps its own login. Not signed in? Run claude once in a terminal and type /login.
• The CLI only gets Lumen's browser tools (no shell, no file edits), and Lumen's approval cards still apply. Follow-ups continue the same Claude Code session; New chat starts a fresh one. Stop ends the CLI and everything it started.
• Background helpers show on the card. With full access, Claude Code can start a helper (a subagent or a background task) and end its reply at once. The reply's card then says Helper working (with the helper's name) instead of Done, the helper's own steps and Lumen tool calls appear on it as they happen, and it says Done when the helper ends. Claude Code's follow-up on the helper's result lands in the same chat as a reply under the first. You can keep writing meanwhile; Lumen keeps Claude Code's process for the helper (up to three hours).
• Claude Code uses the model set in Claude Code; Claude Code · Fable / Opus / Sonnet / Haiku pass --model with that alias. Switching between them mid-chat keeps the same session. (Grok Build, when offered, lists the models grok models reports the same way; switching its model starts a new Grok session that is handed the conversation so far.)
• Uses your Claude Code login. For personal use; apps offered to others need Anthropic's approval to use claude.ai logins.

Tabs that organize themselves

⋯ → Tab groups → Group automatically Off / By site / By topic. By topic finds related tabs (recipes, one trip, a library's docs) on your computer from titles and addresses. Turn on Use AI to name and group topics in Settings to send tab titles and site names (hostnames only) to the cheapest model of your chat's provider instead. Organize Tabs by Topic (tab menu or ⋯ → Tab Groups) regroups on demand, with Undo Organize. Groups you made and tabs you moved by hand are left alone.

Tabs down the side

Settings → Tabs and browsing → Tab layout lists the tabs down the left of the window instead of across the top (Top is the default). Each row has the favicon and title; pinned tabs are icon tiles at the top, groups are sections you click to fold, and the new-tab button is above the list. Drag a tab up or down to reorder it, or out past the list to open it in a window of its own; drag the list's right edge to resize it (Lumen remembers the width). Icons only narrows it to a column of icons that opens out while the pointer is over it. Right-click an empty part of the list to switch layouts or fold it; Up and Down step through the tabs. The page area and the AI sidebar fit around the list. Dragging a tab onto another window's side list doesn't drop it there yet; use the tab menu's Move tab to window for that.

Two tabs side by side

Right-click a tab → Open in split view to show it next to the tab you are on, or drag a tab out of the strip and drop it on the right edge of the page. Drag the divider to resize (double-click for an even split); the button on the divider, or Close split view in the tab menu, ends it. The tab you clicked last is the one the address bar, the AI and the shortcuts use, so the AI can work in one side while you read the other. Split views are not kept across restarts.

A real browser underneath

• PDFs open in Chromium's own viewer, from the web or from disk.
• Word and Excel files (.docx, .xlsx) open in a tab of their own, read-only, like decks and emails do: a document shows its headings, text, lists, tables and pictures, a workbook its sheets (with sheet tabs) and cells as the file formats them (numbers, percents, dates, bold, colors, merged cells). It opens from File → Open, a drag onto the window, a typed or pasted path, a card the AI made, or Preview in a tab on a download. Nothing in the file runs and nothing is fetched; a link is shown, not followed. To change the file, use Word or Excel (Open in app on a card). A big file shows its first part and says so.
• Saved emails (.eml) open in a tab of their own, from File → Open, a drag onto the window, the Downloads panel or "Open with": headers, the message, and its attachments (Save, or Open for PDFs, pictures, text and other emails). The message is shown with no scripts, and remote pictures stay blocked until you press Load remote images. The AI can read an open email like any local file you share with it.
• Make it yours (Settings → Appearance): an accent color (nine presets or any color) across Lumen and its pages, and a new-tab page with a background (Plain, Aurora, Dusk, Ocean, Forest, Sunset, Graphite, or your own picture, kept in your profile), a big clock, a greeting with your name, and the sections you want. Open new-tab pages change as you pick.
• Music-reactive home screen (Settings → Appearance → New tab page, off by default; Windows only): a field of soft dots behind the widgets drifts slowly and, with the sound your PC is playing (any program, the Spotify desktop app included), bursts on the beat, swirls with the mids and twinkles with the highs. It listens to a copy of the PC's output, so music is never muted or interrupted, only while the new tab is on screen; only loudness numbers are used and nothing is recorded or sent. A Preview button shows it without music. Light visual effects get fewer dots, and Reduce motion or Performance mode turn it off. Music cards (Spotify, Apple Music) have their own React to music option: the cover breathes on the beat and a soft glow rims the card.
• New-tab widgets (Settings → Apps and connections): cards under the search box for the weather in a city you type (Open-Meteo, no account, °F or °C), your calendar from any ICS / webcal link (Muse, Google Calendar, Outlook, iCloud: today and upcoming events, with repeating and all-day events), your Todoist tasks due today or overdue (tick one off right on the card), Spotify (by default Spotify's own web player playing inside Lumen, with a now-playing card, search, and control of Spotify Connect devices; or the web player in the card; or a now-playing card driven by Spotify's API with your own Client ID), Apple Music (a now-playing card like Spotify's with seek, search, recent plays and playlists, playing inside Lumen through Apple's own MusicKit page where you sign in on Apple's site and Lumen never sees your Apple ID, with the Apple Music desktop app as a fallback source; or Apple's web player in the card), your Gmail unread count and latest unread messages (read-only; by default it uses the Google account you are signed in to in Lumen, through Gmail's own unread feed, with nothing to set up; choose Advanced for your own Google Cloud OAuth client, with a guided setup, if you want read mail too), Slack unread DMs, mentions and recent channel messages (read-only, through your own Slack app that Lumen helps you create in a few clicks: one button opens Slack's prefilled create-app page, then you copy one token and Lumen connects), your GitHub review requests, assigned issues and pull requests and unread notification count (press Sign in with GitHub for a one-time code, or use the GitHub CLI you are already signed in with; see Sign in with GitHub), news headlines from any RSS or Atom feed, a world clock with sunrise and sunset, stock and crypto prices with a simulated paper portfolio (Lumen never places an order), a saved prompt answered by Meta’s Muse model, a live TradingView chart for any symbol (TradingView’s own chart in a frame, no account or key), a note that saves as you type, a countdown to a date, a timer or Pomodoro (focus, then a break; it keeps running while the page is closed), AI status (which of your AIs are ready, working or at a limit, from what Lumen already knows here; nothing is sent anywhere), a custom widget built from a short JSON recipe (any https address that answers JSON, shown as numbers or a list; see Custom widgets), or any https page in a frame (a Muse board, a dashboard). Sites that refuse to be framed get an Open button instead, and Settings tells you which. Lumen fetches everything itself, so the new-tab page never goes online (which service gets what: PRIVACY.md; "My location" asks ipapi.co for your city after you allow it, and sends it your IP address), and your Todoist token and your Spotify, Gmail, Slack and GitHub sign-ins are stored encrypted and never reach the page. Framed pages (the Web page and TradingView cards) load from their own site, like any tab. New kinds of widget are one entry in src/features/widgets.js.
• Spotify Library (a large Spotify card connected to Spotify's API, or playing as Lumen with the account connected): the Library tab lists Liked Songs first, then all your playlists (read as you scroll), with Albums and Artists chips and a filter box. Open a playlist, album, artist or Liked Songs to see its songs inside the card (Play, Shuffle, a row's Play and Add to queue); a song plays inside its list. Back, Esc or Backspace returns to the list where you were.
• Spotify Home (a large Spotify card, connected to Spotify's API or playing as Lumen with the account connected): the card's Home tab shows shelves like open.spotify.com's Home from what Spotify's API gives apps: quick picks, Jump back in, Made for you (your Spotify-made Daily Mixes, Discover Weekly and Release Radar), Recently played, your top songs and artists, New releases, and your playlists, albums and followed artists. Press a tile to play it, or a song's Queue button to add it to the queue. It needs the "top artists" permission; if the account was connected before, the card offers "Reconnect Spotify to show more", and its button starts the Spotify sign-in right there (no Settings detour). A "Plays in Lumen" card needs the account connected once for Home (the music still plays in Lumen); its button says Connect Spotify. Lumen's own Spotify app only lets 25 listed accounts in while Spotify keeps it in development mode: if Spotify refuses yours, the card says so and offers your own Spotify app (the steps are in the card's editor). Spotify's other generated sections are not in its public API and are not shown. Below them are suggestion shelves (Recommended for you and Fans also like where Spotify allows them; otherwise New from artists you love, More from your top artists, Based on your genres and Artists to try, built from your top and followed artists), each with a line saying what it is built from.
  • Files: the Files card lists what you pinned (a file or a folder, with + on the card, "Pin to Files" on a file tab's right-click menu, or on a download in the downloads panel) and, under it, the last dozen local files you opened in Lumen: files you opened in a tab, PDFs, presentations, mail files, downloads you opened, and files the AI opened, read or made. A click opens a file in a tab (a folder in File Explorer); right-click gives Open, Show in folder, and Pin or Remove from Files (Unpin on a pinned one); removing or unpinning can be undone for a few seconds. A new profile's new-tab page starts with the card. A file that was moved or deleted turns grey and says so, and a click on its row (or Find it) looks for it near its old place and lets you pick the match. Hovering a Word, Excel or PowerPoint file on the card shows its first page beside the row. Ctrl+Shift+F ("Open a recent file") opens a quick picker over every page (the selected Word, Excel or PowerPoint file shows its first page beside the list on a wide window): type a few letters of a name to search what is pinned, what you opened lately and what is inside your pinned folders (Enter opens, Ctrl+Enter shows it in its folder, Alt+Enter attaches it to the sidebar chat, Esc closes); with no match it offers Search Documents, Desktop and Downloads, a bounded search of those folders. The AI looks in the same places first when you ask for a file by name ("get my chapter 4 slides"). Lumen keeps only names, places, sizes and times (never what is inside a file), encrypted, on this computer; Settings → Downloads and files → Files turns off Remember files I open and clears the list.
  • TradingView watchlist: set a TradingView widget's Style to Watchlist for rows of symbols with logo, price and change, one tab per section (like TradingView's phone home-screen widget), optionally with a chart on top. Type or paste symbols (TradingView's “Export list” .txt works, ###Name starts a section), or press Import from TradingView to pick one of your own watchlists: Lumen reads it with your TradingView sign-in in Lumen and, with Keep in sync on, re-reads it every 15 minutes. Indices TradingView won't price in widgets (SPX, NDQ, DJI, VIX, DXY) are shown through their CFD twins; futures stay blank.
  • Add and edit on the page: Notes, Countdown, Timer, Apple Music, TradingView, Custom and Web page widgets can be added from the page's Add widget menu and changed with the pencil on the card (or the gear in Edit layout), without opening Settings. Widgets with an account or a key are still set up in Settings, so keys never pass through the new-tab page.
  • Saved as you go: editing a widget in Settings saves by itself a moment after each change. If a change can't be saved (a missing date, a bad symbol) Settings says why, and leaving the form or closing the tab asks first.
  • See-through cards: Settings → Appearance → Widget cards is Solid, Frosted glass or Clear (as transparent as possible while the text stays readable, best on a gradient or your own picture).
• Usage (Settings → Usage, and a meter under the sidebar's composer while a Claude Code model is picked): your Claude plan's 5-hour and weekly limits with reset times, read with the free claude /usage and live from each turn, and how much of them Lumen uses: tokens per engine (Claude Code, Grok Build, API key) and roughly how far each Claude Code turn moved the 5-hour meter. Claude Code driving Lumen over MCP shows as its share of this computer's Claude Code use.
• Record a tab or your screen (⋯ → Record, File → Record on a Mac): a video of the current tab, or of a whole screen or one window, saved as a .webm in Downloads with the sound from the tab or PC and, if you tick it, your microphone. A small bar shows the time and has Pause and Stop; afterwards it offers Show in folder. For class demos and bug reports; nothing is uploaded (details).
• Focus mode (the toolbar's circle button, /focus, or typing "focus for 90 minutes" in the chat; off until you start it): for a homework session, the sites on your list (YouTube, Reddit, TikTok, Instagram, X, Facebook, Twitch and Netflix by default; Settings → General → Focus mode) are blocked until the timer ends and the tab shows a calm page with the time left. I need this for school opens that one site for 10 minutes and is noted in the focus log; End focus takes a 10-second hold. Recurring sessions ("weekdays 7-9 pm") start by themselves. More.
• Downloads panel (the toolbar's download button): progress with speed and time left, pause, resume, cancel, retry, show in folder, remove. Drag a finished file out of the panel into Finder, Explorer, mail or chat. The list is kept across restarts.
• Ad blocker built into the browser, not an extension. It uses uBlock Origin–compatible lists (Ghostery engine). Toggle it, or allow ads on one site, from ⋯ → Ad blocker. Hidden-element rules are applied in a way pages can't read, and uBlock's scripts disarm known anti-adblock checks. Blocked requests are cancelled, so a determined site can still notice that its ad request failed. Captcha checks (hCaptcha, reCAPTCHA, Turnstile, Arkose and others) and sign-in pages are never filtered, so forms behind them keep working.
• Chrome extensions from the Chrome Web Store: open ⋯ → Extensions → Get extensions… and click Add to Lumen. Extension buttons appear in the toolbar. The ad blocker takes over Electron's request hooks, so extensions that block requests through the old chrome.webRequest API (Manifest V2) can't block. Manifest V3 extensions work; content blockers that rely on static declarativeNetRequest rulesets are refused at install.
• Reading list (Save for later): Ctrl+Shift+Y, a tab's or a page's right-click menu, or a link's Save link for later sets a page aside; ⋯ → Bookmarks → Show reading list (lumen://readinglist) lists them with site icon, title, site and date, unread in bold, with Unread / All, search, Mark as read, Remove (with Undo) and Mark all read. Opening a page from the list marks it read. It is kept on your computer (reading-list.json in your profile), only the address, title and dates; nothing is sent anywhere, and it is off in private windows. In the sidebar chat, "save this for later" and "what's on my reading list?" work.
• Search engine: Google, DuckDuckGo, Bing, Brave Search, Ecosia or Startpage (Settings, or ⋯ → Search engine).
• Import: bookmarks and history from Chrome, Edge, Brave, Vivaldi, Opera or Firefox (Settings, or ⋯ → Import bookmarks and history). Passwords and cookies are never read.
• Permissions: sites must ask before using your camera, microphone, location, or notifications. Click the lock next to the address for the site's page info: its connection, Ask / Allow / Block for each permission, its cookies (with Clear Cookies and Site Data… for that site), and its remembered zoom. Settings → Privacy and security → Site data lists every site that keeps cookies, with Remove for each.
• Zoom is remembered per site, across restarts; Ctrl+0 goes back to the default from Settings.
• Safe Browsing (optional, off by default): with your own Google API key (Settings → Privacy and security), pages listed by Google Safe Browsing as suspected phishing or malware show a warning instead of loading. Pages are checked against lists kept on your computer; Google only ever sees partial hashes. Only you can choose to visit a flagged page; the AI can't. Like any list, it can miss unsafe sites and flag safe ones by mistake.

Keyboard shortcuts

Ctrl is Cmd on macOS. The in-app sheet (Ctrl+Shift+/) is the complete list. A website that uses a shortcut itself (Google Docs, VS Code for the web) gets the key first; the ⋯ menu shows the same shortcut for Lumen's action.

Action	How
Command bar: search open tabs, bookmarks, history, Settings sections and commands (new tab, pin tab, mute tab, switch theme, clear data...), or ask the AI	Ctrl+K (a site that uses Ctrl+K itself keeps it; the ⋯ menu has Command bar…). Up and Down pick, Enter runs, Ctrl+Enter opens a page in a new tab, Esc closes. With nothing typed it lists the commands you ran lately, then your open tabs. The last row, Ask AI: …, sends what you typed to the sidebar. Ctrl+E is still the address bar's search
Open or close the AI sidebar	Ctrl+J or the toolbar's AI button
New chat in the sidebar (opens it if closed)	Ctrl+Shift+K
On the full-page chat: fold or open the chat list / new chat	Ctrl+Shift+S / Ctrl+Shift+O
Ask the AI from the address bar	type, then Alt+Enter
Ctrl+Enter, in the box you are typing in	Send it now: asks the AI on the new-tab page; in the sidebar chat, stops a running reply and sends yours
Meeting helper	Ctrl+Shift+E
AI activity: everything the AI is doing (lumen://tasks)	Ctrl+Shift+X
Voice input, in the chat box (hold to talk, or press to start and again to stop)	Ctrl+Shift+Space
New-tab page: go to the search box / switch Search and Ask AI	/ / Ctrl+/ or Alt+A
New tab / close tab / focus address	Ctrl+T / Ctrl+W / Ctrl+L
New window / close window	Ctrl+N / Ctrl+Shift+W
Switch tabs	Ctrl+Tab, Ctrl+Shift+Tab, Ctrl+1–9
Reopen closed tab	Ctrl+Shift+T
Open a local file (HTML, PDF, images, media)	Ctrl+O, drop it on the window, type or paste its path, or Open With → Lumen
Back / forward	Alt+← / Alt+→ (macOS: Cmd+[ / Cmd+])
Reload / stop loading	Ctrl+R or F5 / Esc
Find in page	Ctrl+F
Zoom	Ctrl+= / Ctrl+- / Ctrl+0
Bookmark this page	Ctrl+D
Save this page for later (the reading list)	Ctrl+Shift+Y
History	Ctrl+H (macOS: Cmd+Y)
Settings	Ctrl+,
Clear browsing data	Ctrl+Shift+Delete (macOS: Shift+Cmd+Backspace)
Every shortcut, in a sheet	Ctrl+Shift+/ (or ⋯ → Keyboard shortcuts)
Print	Ctrl+P
Full screen	F11 (Windows, Linux)
Ask the AI about selected text	right-click → Ask AI About Selection
Site information (connection, permissions, cookies)	click the lock next to the address
Tab devtools	F12

Use Lumen from Claude Code, Codex, Antigravity

Lumen is an MCP server: any MCP-capable agent can drive the browser with the same tools the sidebar uses (read_page, click by text, fill_form, navigate, tabs, screenshot, read_urls, run_script, web_search, group_tabs…; all 28 with their parameters are in the MCP tool reference). It's off until you turn on Settings → AI → Allow AI agents to connect. For Claude Desktop, Cursor, VS Code and Claude Code outside Lumen, Settings → AI → Let other apps use Lumen gives each app a token of its own, shows a pill while it works, and lets you Stop, Take over or Revoke it (guide). The exact commands for your install, with the right paths, are under Connect an AI agent in the same place (each with a Copy button). Claude Code, Codex CLI, Gemini CLI and Grok Build also get a one-click Add to … button, which turns the setting on (Claude Code's says Already connected if claude mcp get lumen finds it). They run Lumen's own executable in Node mode on mcp.js:

# Easiest: Settings, AI, Let other apps use Lumen, Claude Code tab, Connect Claude Code (it does the steps below, with a key of its own).
# By hand, Claude Code on Windows (PowerShell or cmd). Use claude.cmd: in PowerShell the npm claude.ps1
# shim swallows the "--", and the command fails with "missing required argument 'commandOrUrl'".
claude.cmd mcp add lumen --scope user -e ELECTRON_RUN_AS_NODE=1 -e "LUMEN_CLIENT_TOKEN_FILE=C:\Users\<you>\AppData\Roaming\Lumen\external-app-tokens\<id>.token" -- "C:\Users\<you>\AppData\Local\Programs\Lumen\Lumen.exe" "C:\Users\<you>\AppData\Local\Programs\Lumen\resources\app\mcp.js"

# Claude Code on macOS / Linux (the token file is the one Settings shows after Connect Claude Code or Add app)
claude mcp add lumen --scope user -e ELECTRON_RUN_AS_NODE=1 -e LUMEN_CLIENT_TOKEN_FILE="$HOME/Library/Application Support/Lumen/external-app-tokens/<id>.token" -- /Applications/Lumen.app/Contents/MacOS/Lumen /Applications/Lumen.app/Contents/Resources/app/mcp.js

# Codex CLI: ~/.codex/config.toml (or $CODEX_HOME/config.toml). The Add to Codex CLI button in Settings
# writes this for you and finds codex however it was installed (npm, winget, the standalone .exe, Homebrew…).
[mcp_servers.lumen]
command = 'C:\Users\<you>\AppData\Local\Programs\Lumen\Lumen.exe'
args = ['C:\Users\<you>\AppData\Local\Programs\Lumen\resources\app\mcp.js']
env = { ELECTRON_RUN_AS_NODE = "1" }
startup_timeout_sec = 30   # Codex's own 10 s start and 60 s tool-call limits are too short for Lumen's approval cards
tool_timeout_sec = 600

// Antigravity (~/.gemini/config/mcp_config.json), Cursor, Claude Desktop and other MCP clients
{ "mcpServers": { "lumen": {
  "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\Lumen\\Lumen.exe",
  "args": ["C:\\Users\\<you>\\AppData\\Local\\Programs\\Lumen\\resources\\app\\mcp.js"],
  "env": { "ELECTRON_RUN_AS_NODE": "1" } } } }

How it works and what keeps it safe:

• The agent starts a small bridge that connects to the running Lumen over a per-user local channel (a named pipe on Windows, a Unix socket elsewhere) and proves it can read the random token in Lumen's profile folder (HMAC challenge-response; the token itself never crosses the channel). If Lumen isn't open, the bridge starts it.
• Every new site still needs your OK: an approval card appears in the sidebar ("An external agent (Claude Code) wants to interact with example.com"). Auto-allow doesn't apply to outside agents.
• Each agent works in a window of its own, opened behind yours (it takes no focus and never comes in front of what you are doing) on its first call that needs a tab, titled and badged with the agent's name. Its tools see only that window's tabs: your tabs, and the tab Lumen's own assistant is working in, are out of reach, and two agents get two windows. The window closes a few seconds after the agent disconnects unless you used it or pinned a tab in it; close it yourself and the agent's next call opens a new one. It is never saved with your session, its pages are muted and ask nothing (an alert is dismissed, a confirm says no, popups are refused), and an approval card waits quietly (the AI button gets a badge) instead of opening the sidebar. The Playwright server below is different: it works in your own tabs.
• While an agent is connected, the toolbar says Lumen is being driven by …, each tool call shows as a step in the sidebar, and Stop disconnects it.
• Lumen --mcp also works as the command, but on Windows GUI-mode Electron prints one blank line on stdout first, which strict clients may log as a parse error; the Node-mode command above avoids that.

Drive Lumen with Playwright (Chrome DevTools Protocol)

Off by default. Turn on Settings → Advanced → Automation → Allow automation tools (Chrome DevTools Protocol), pick a port (default 9222) and restart Lumen. Then click Copy address: the address includes a secret key (http://127.0.0.1:9222/<token>), and the port refuses requests without it.

# Playwright MCP, from Claude Code
claude mcp add playwright-lumen -- npx @playwright/mcp@latest --cdp-endpoint http://127.0.0.1:9222/<token>

// Playwright
const browser = await chromium.connectOverCDP('http://127.0.0.1:9222/<token>');
const page = browser.contexts()[0].pages()[0]; // your open tabs
const tab = await browser.contexts()[0].newPage(); // opens a real Lumen tab

• Lumen listens on 127.0.0.1 only, through a proxy (src/automation/automation.js) that shows only your tabs: Lumen's own UI, hidden reader tabs and extension pages can't be seen or attached to.
• newPage() opens a Lumen tab, page.close() closes it, and browser.close() only disconnects.
• The toolbar says Lumen is being driven by Playwright (CDP) while connected; Stop disconnects.
• CDP clients don't get approval cards. Any program on your computer that has the address can use the port while it's on, including on signed-in sites. Turning the setting off closes the proxy immediately.
• The proxy is the only way in, and no debugging port is ever opened. On Windows and Linux, Lumen starts through a small launcher (src/automation/launcher.js) that gives Chromium a private pipe. On macOS there is no launcher (it would lose links opened from other apps): src/automation/cdp-inproc.js answers the protocol inside Lumen from each tab's own debugger.
• Through the macOS (in-process) backend, some browser-level features aren't available and answer with an error: browser.newContext(), context.grantPermissions(), download events and blocking downloads, window bounds. Clients share one debugger session per tab, so Fetch interception (page.route) works for one client at a time, and an iframe or worker that starts paused may already be running when a client resumes it.

The AI using other apps (Windows and macOS)

Settings → AI → Let the AI use other apps on this computer (off by default) lets the AI read and operate programs such as Word, File Explorer, Finder or MATLAB, on Windows and on macOS. It asks before each app, a banner shows it working with a Stop button, Esc held stops it, and a card in the chat shows the app with a live thumbnail. Passwords, security prompts, password managers, banking apps, system settings and Lumen itself are never available. On a Mac, macOS has to allow Lumen once under System Settings → Privacy & Security → Accessibility (and Screen Recording for pictures of a window); Lumen shows a button that opens the right pane and never turns these on itself. Details: docs/desktop-apps.md.

Token-efficient tools (all AIs)

The sidebar agent, MCP clients and OpenAI/Grok/Gemini get the same cheaper tools:

Tool	What it returns
read_page with mode: "compact"	an outline with [id] refs (headings, landmarks, text with inline links, controls with values) instead of JSON plus raw text. mode: "full" (the default) is unchanged.
read_page with since_last: true	only what changed since the last read
find	matching controls and short text snippets, instead of reading the page
batch	several actions (type, click, select, press, wait_for, scroll, hover) in one call, ending with what changed
read_page with `extract: "tables"	"links"
navigate / open_tab with read: true (and wait_for: "text")	the new page's outline in the same call, instead of a separate read_page
click, click_at, type_text, press_key with observe: true	the action's result plus what changed on the page, instead of a follow-up read or screenshot
screenshot	720 px JPEG by default, with max_width, quality and region crop

What one call costs on real pages (tokens ≈ characters / 4, measured with Lumen's own tools):

Page	read_page (full, default)	mode: "compact"	since_last (unchanged page)	find (one word)
Wikipedia: WebKit	~6,800	~1,500	~21	~180
DuckDuckGo results	~2,700	~760	~21	~360
Long article: World War II	~7,600	~1,500	~21	~180

Compact is about 4–5× smaller than a full read. The big savings come from not reading again: since_last after an action, find for one thing, and batch for several steps in one call. node test/e2e/measure.js runs whole tasks both ways.

Privacy and security

• No telemetry, no analytics, no crash reports. Lumen has no servers of its own. What leaves your computer, and to whom: PRIVACY.md.
• Sites see less of you, by default. Pages can't tell when you leave the tab, switch apps, use split screen or move the pointer off the page. They see a screen the size of your window. Canvas, WebGL and audio fingerprints change from site to site, WebRTC can't reveal your local or VPN-hidden IP address, tracking parameters (utm_, fbclid, gclid…) come off links before the page opens, link-click pings and beacons are blocked, and Global Privacy Control is sent. Each one has its own switch in Settings → Privacy and security. Details and limits: docs/privacy-protections.md.
• Keys and the chat are encrypted with the OS keychain. Chats are saved in Chat history; New chat starts a fresh one and keeps the old one there. Deleting a chat erases it after 8 seconds (Undo). Without a keychain, keys aren't saved (use the environment variables) and the chat isn't kept between sessions.
• Background reading and web search run in a separate in-memory session with none of your cookies or logins. That session denies every permission request and cancels downloads.
• Lumen's own UI is locked down. The browser UI, the address-bar suggestions and the dialog overlay can't be navigated away or open popups (links open as tabs), web pages in tabs can't send the UI's privileged messages, and a link dropped on the window opens as a tab.
• Passkeys, Windows Hello and security keys (Windows 10 1903 and later; Settings → Privacy and security → Use passkeys and security keys, on by default). Sites that offer "Sign in with a passkey" get the Windows Security prompt (face, fingerprint, PIN, a USB/NFC/Bluetooth security key, or a phone over QR); Windows keeps the passkeys and Lumen stores nothing. Lumen's main process checks every request itself (the page's real origin, the relying party, a secure page, the tab in front of a focused window) and refuses any page the AI opened or is working in, so no AI tool can start or approve a passkey prompt. Not yet: passkey autofill in the address/username field (conditional mediation), related-origin requests, macOS and Linux (there sites see no passkey API and offer a password or a code, as with the setting off). On Windows 11 with a third-party passkey provider, a cancelled "save this passkey" picker can stay up until you close it.
• Sync between your computers, through a folder you choose (off by default). Settings → General → Sync: pick a folder your own cloud drive (OneDrive, Dropbox, Google Drive, iCloud Drive) syncs and a sync passphrase, and Lumen keeps your bookmarks, history, chats, home page widgets and settings the same on every computer. Lumen has no server and no account; the folder holds only encrypted files, the passphrase stays on each computer, and API keys and sign-ins never sync. Saved passwords sync only with a separate switch. Details: Sync through a folder.
• Approvals for the AI and for MCP agents are described in Asking before it acts.
• Found a vulnerability? See SECURITY.md.

Build from source

npm install
npm start             # run from source
npm test              # the core Playwright suites, one at a time, with a pass/fail summary
npm test -- tabstrip  # just the named suites
npm run test:units    # only the pure-node suites (no window; what CI runs)

Build and install locally

npm run dist          # this computer's platform (Windows or macOS); or dist:win / dist:mac
npm run install_app   # Windows: installs to %LOCALAPPDATA%\Programs\Lumen with Desktop + Start menu shortcuts

Builds go to a local folder that isn't synced, even when the project itself lives in OneDrive:

• Windows: %LOCALAPPDATA%\Lumen\build
• macOS: ~/Library/Caches/Lumen/build

Set LUMEN_BUILD_DIR to use a different folder. The installed Windows app lives on the local drive at %LOCALAPPDATA%\Programs\Lumen.

Set LUMEN_GOOGLE_CLIENT_ID and LUMEN_GOOGLE_CLIENT_SECRET (a Google Cloud OAuth client of type Desktop app, with the Gmail API enabled) when building to include Lumen's own Google client, which gives the Gmail widget a one-click "Sign in with Google". The same variables work when running from source. Without them the Gmail widget's Advanced mode asks for the user's own Google Cloud client (the default mode needs neither). The release workflow reads them from repository secrets of the same names.

The Windows build ships the official Electron .exe byte for byte (signAndEditExecutable: false, asar: false, and Electron taken from node_modules), and scripts/build/build.js checks this after every build. Windows 11 Smart App Control blocks unsigned executables it doesn't recognise, and editing the exe (icon, version info, asar integrity) produces one. The untouched Electron binary is recognised, so it runs. The window, taskbar, shortcuts and the icons of the file types Lumen opens (HTML, PDF, SVG) use Lumen's icon at runtime (the installed Lumen points them at icon.ico on start). For a normal signed installer, sign the build with a trusted code-signing certificate.

Release installers are built by GitHub Actions (.github/workflows/release.yml) and attached to Releases when a version tag (v*) is pushed. Manual runs of the workflow keep the builds as run artifacts instead. To ship an update: bump version in package.json (npm version patch --no-git-tag-version), commit and push, then tag that commit with the same version and push the tag (git tag v0.2.5 && git push origin v0.2.5). The workflow refuses a tag that doesn't match package.json. Next to the installers the release gets latest.yml, latest-mac.yml and .blockmap files, which installed copies read to find and verify the update (src/features/updates.js; the Windows zip is listed in latest.yml by scripts/release/add-zip-to-latest.js; the updater is electron-updater).

DRM (Widevine)

electron is castlabs' ECS build (electron-releases#v44.1.0+wvcus), which adds a Widevine CDM that stock Electron doesn't have. On startup Lumen calls components.whenReady() (with a 10s timeout so a failed/offline CDM download never blocks the window opening) and logs components.status(); the CDM itself downloads on first run.

That's enough for sites that accept the plain Widevine CDM. Production DRM providers (Netflix, Disney+, Spotify and others) also check that the binary is VMP-signed by castlabs. An unsigned build still plays where a site accepts software Widevine (L3); services that require a VMP signature may refuse or downgrade. electron-builder renames electron.exe to Lumen.exe, which invalidates the stock signature, so Lumen re-signs during packaging (scripts/release/after-pack.js, Windows and macOS). It warns and carries on if signing isn't set up.

Local builds: sign up once for a free castlabs EVS account; after that, npm run dist signs automatically:

python -m pip install --upgrade castlabs-evs
python -m castlabs_evs.account signup      # or: python -m castlabs_evs.account reauth

Headless / CI: set EVS_ACCOUNT_NAME and EVS_PASSWD instead. The release workflow does this on the Windows and macOS jobs when the repository secrets of the same names exist; without them it builds unsigned.

To check DRM playback manually (not part of npm test): node test/e2e/drm.js.

Screenshots and GIFs

The images in this README are captured from a throwaway profile by node scripts/measure/capture-media.js (needs ffmpeg on PATH for the GIFs and the MP4; Windows only for the screen recording).

Report an issue

Something broken, or something missing? Open an issue on GitHub and pick Bug report or Feature request. Include your Lumen version (Settings → Updates and about) and your operating system, and search the open issues first in case it's already reported. Security problems go to a private security advisory, not a public issue (SECURITY.md).

Documentation

• Install and update: which file to download, installing on Windows and Mac, first launch, how updates work, and troubleshooting
• Architecture: processes, the UI and tabs, the AI and its approvals, outside agents, updates
• Let other apps use Lumen: set up Claude Desktop, Cursor, VS Code and Claude Code with a token each, and watch, stop or revoke them
• Connectors: let the AI use Canvas, Gmail, Google Drive, Docs, Sheets, Calendar, Tasks and Contacts, Outlook, OneDrive, GitHub, Todoist, Notion, Zotero and more once you connect them, what each can read and do (including the writes it asks you to allow), and where the secrets go
• MCP tool reference: every tool with its parameters
• Local models: chat with Ollama or LM Studio models on your own computer, no key, what stays local, and tools versus plain chat
• Settings reference: every setting, its key in settings.json and its default
• Privacy protections: what Lumen hides from websites (leaving the tab, window size, fingerprints, WebRTC IP, tracking links and pings), and the limits
• Meeting helper: real-time answers with Ctrl+Shift+E, agenda/resume context, stealth mode (hidden from screen share), live audio listening, and post-call summaries
• Sign in with GitHub: one sign-in for the GitHub card and the GitHub connector (a one-time code, or the GitHub CLI), what it asks for, and how a maintainer registers the OAuth App
• Screen recording: record a tab, a screen or a window to a .webm file, with the tab's sound and your microphone if you want it
• Custom widgets: the recipe format for your own new-tab cards, with examples
• The AI working in Word: reads and edits Word documents directly (Windows), or .docx files without Word, with an approval for every change and a live card in the chat
• The AI using other apps: Word, File Explorer, Finder and more on Windows and macOS: per-app approval, what is never available, the banner and Stop
• Skills: saved instructions you run with /, SKILL.md folders shared with Claude Code and other agents, skills the AI uses on its own, and the opt-in offers to save and improve them
• Sync through a folder: keep bookmarks, history, chats, widgets and settings the same on your computers through a cloud-drive folder, encrypted with a passphrase only you know, with no Lumen server
• Notes: the sidebar notepad, adding from a reply or a page, asking the AI about a note, and where notes are kept
• Memory: what the AI remembers about you between chats, how it decides, Search past chats, and where to see and delete it
• Projects: files, pages and memory the AI works from in a project's chats
• AI activity: lumen://tasks, one page with what waits for you, what runs, what is scheduled and what finished, across chats, tasks, routines and outside agents
• Focus mode: block distracting sites for a homework session, the ten-minute "I need this for school" pass, ending it with a hold, schedules in words, and the focus log
• Routines: requests the AI repeats on a schedule, from a local web link or when new email arrives, when they run, and what they may do (all of them, with templates, quiet hours and web links, in Settings → AI → Routines)
• Receive from phone (Wi-Fi): scan a QR code and send photos and files from your phone to Lumen over your Wi-Fi, and how it is kept to that one phone
• Phone (Telegram): send requests to Lumen from your own Telegram bot, pair your chat, answer the AI's questions with Allow and Deny, send photos, files and links both ways
• Feature gaps: how the browser underneath compares with Chrome, Arc, Safari, Brave and Edge, and what's next

Layout

Everything that ships in the app is under src/; the repository root holds only configuration, docs and the tools around the code.

src/                    the app (package.json "main": src/main.js)
├── main.js             windows, tabs (WebContentsView), shortcuts, menus, permissions, history, extensions, IPC
├── ai/                 the sidebar's agent loop (agent.js, default model claude-opus-5-5), its page tools
│                       (snapshot.js, page-scripts.js, frames.js, loop-guard.js), model adapters (providers.js) and the
│                       Claude Code / Grok Build engines that run your own CLI (claude-code.js, grok-build.js, cli-*.js)
├── automation/         MCP server for outside agents (mcp.js, mcp-http.js) and the opt-in CDP endpoint for
│                       Playwright (automation.js, cdp-inproc.js, launcher.js)
├── browser/            tab grouping (tab-groups.js), browser import, search engines, favicons, address-bar input, fetch
├── settings/           lumen://settings backend (settings-backend.js) and the atomic settings file (settings-file.js)
├── preload/            preloads for the UI, dialogs, downloads, history, suggestions and extensions
│                       (preload.js is bundled into preload.bundle.js by scripts/build/bundle-preload.js)
├── features/           split-out features, each a pure part tested in Node plus a create…() that main.js wires in
├── renderer/           the browser's own pages: toolbar and tab strip, sidebar, new-tab page and widgets, settings, history
├── locales/            UI strings (en.json), used through t()
├── assets/             app icons
└── vendor/             third-party code shipped as is (Readability)
mcp.js                  the MCP bridge's stable address (<app>/mcp.js in agents' configs); it starts src/automation/mcp.js
test/                   units/ (pure-Node suites, `npm run test:units`), e2e/ (Playwright suites, one file per area), helpers/ (shared rigs, fixtures builders), fixtures/, acceptance/
scripts/                build/ (build, bundle, check), release/ (release, land, signing), test/ (test-all, test-units), measure/ (measure-*, profile-*, capture-media)
docs/                   reference pages (below) and docs/media (the README's screenshots, not shipped)
site/                   the website on GitHub Pages; its docs pages render README.md, CHANGELOG.md and docs/*.md

src/features/ in groups: AI (ai-agents, background-*, chat-*, mission-control, organize-*, research-tabs, signed-in-sites, skills, usage), widgets (widgets and widget-*, one *-view.js per kind), privacy and security (adblock*, hide-activity, tracking-params, passwords, password-page, passkeys, webauthn-windows, private-*, safe-browsing, site-security, page-info, site-data), tabs and pages (tab-*, page-tools, pdf-*, translate, screenshot, qr, link-menu, site-zoom), app (sync-* (sync through a folder), updates, zip-update, whats-new, instance, dialogs, downloads, managers, i18n, performance, crash-recovery, shortcuts-help).

Tests: npm test runs the core suites (listed in scripts/test/test-all.js) one after another; npm test -- widgets passwords runs just those. npm run test:units runs every pure-node suite (scripts/test/test-units.js, no window), which CI runs on pull requests and the release build runs before packaging. LUMEN_TEST_BACKGROUND=1 npm test keeps every test window invisible and never takes focus, so you can keep using your own Lumen; the few checks that need real keyboard focus or macOS fullscreen then print SKIP. Suites that need the network, an API key or a signed-in CLI (claudecode, grokgate, drm, the measure-* scripts) are run by hand. npm run lint runs ESLint.

License

GPL-3.0 (see LICENSE), because it uses electron-chrome-extensions (GPL-3.0).