Kan (看, "look") — a browser where your agent looks for you.
Kan is a macOS browser built on Chromium (via CEF) for people who work with coding agents. Everything the browser can do is exposed as a tool, so an agent can open, read, operate and debug pages, then point you at what matters.
Status: early prototype. Not ready for daily use.
| Path | What |
|---|---|
Sources/KanApp |
AppKit shell: title-bar tab strip, address bar, session restore, crash handling, RPC server |
Sources/CEFBridge |
Objective-C++ wrapper over the CEF C++ API, consumed from Swift |
Sources/KanHelper |
CEF sub-process executable (GPU, renderer, plugin, alerts helpers) |
Sources/KanRPC |
Socket path and wire format shared by the app and the CLI |
Sources/KanCLI |
kan command-line client |
packages/kan-plugin |
@kan/plugin: the typed client plugins use, generated from the command table |
plugins |
Plugins that come with Kan, built and copied into the app bundle |
assets |
The app icon: icon.svg, and Kan.icns made from it by scripts/icon.sh |
scripts/cef.sh |
Fetches the pinned CEF binary distribution and builds libcef_dll_wrapper |
scripts/bundle.sh |
Builds everything and assembles build/Kan.app |
Requirements: Apple Silicon Mac, macOS 13+, Xcode command line tools (Swift 6), CMake.
scripts/bundle.sh # release build → build/Kan.app
open build/Kan.appFor daily use, install a copy so development builds never touch the Kan you browse with:
scripts/install.sh # copies build/Kan.app to ~/Applications/Kan.app
scripts/install.sh --no-restart # refuse instead of quitting a running KanThe installed copy is the one that can be your default browser: choose Kan > Make Kan the Default Browser and confirm in the macOS dialog (or pick Kan in System Settings > Desktop & Dock > Default web browser). Links from other apps then open in a new Kan tab. Development builds use a different bundle identifier (dev.kan.browser.build), so links never go to them. A running development build keeps working through bundle.sh. If the installed Kan is running, install.sh quits it cleanly (as Cmd+Q does, so tabs are saved), installs the new version and reopens it. Open tabs are restored on every launch (URLs passed on the command line open as extra tabs), and logins live in the Chromium profile. Only the active tab loads at launch; the others load when shown. As in Chrome, background tabs are discarded (and reload when shown) only when macOS reports critical memory pressure, least recently used first, and never while they play media, use the camera or microphone, or hold unsubmitted form input.
To run a development instance next to it, give it its own data directory and CDP port:
export KAN_HOME=~/Library/Caches/kan/dev # profile, session and socket; keep the path short (socket limit)
build/Kan.app/Contents/MacOS/Kan --home=$KAN_HOME --cdp-port=9335
build/Kan.app/Contents/Resources/bin/kan tab list # the CLI follows KAN_HOME tooThe first run downloads CEF (~130 MB) into ~/Library/Caches/kan/cef and extracts it into vendor/cef.
While Kan is running it listens on ~/Library/Application Support/Kan/kan.sock (override with KAN_SOCKET). The kan CLI ships inside the app bundle:
scripts/install.sh also links kan into ~/.local/bin and the kan skill (skills/kan) into ~/.claude/skills and ~/.codex/skills, so Claude Code and Codex know Kan's commands. The skill only lists them: kan help <group> [verb] and kan app commands give exact usage, and errors say what was wrong. Codex's default sandbox blocks Kan's socket; allow it with [sandbox_workspace_write] network_access = true in ~/.codex/config.toml.
Settings live in ~/.config/kan/config.json ($KAN_HOME/config.json for a development instance), with no settings screen: edit the file and it applies the next time a setting is used (nothing watches it); kan app config shows its path, values and any error. Settings: library (default ~/Kan), the folder where agents keep files worth keeping; plugins.disabled, plugins that do not load (default none); plugins.enabled, plugins turned on that are off by default; side_panel, the plugin the side panel opens with (default navigation, null for none). Local files open by path (kan open report.html from the caller's directory); an agent that edits a page you have open reloads it with kan page reload, which keeps the scroll position.
Every action in Kan is a named command, <group>.<verb>, kept in one table (Sources/KanRPC/CommandTable.swift), as in Emacs: menus, shortcuts and toolbar buttons run these commands for the person, and agents run the same ones. kan help lists the groups, kan help <group> their commands.
alias kan="$PWD/build/Kan.app/Contents/Resources/bin/kan"
kan tab list # tabs; each reports state: ok | crashed | unresponsive
kan open https://example.com # = kan tab open (--background to keep the current tab)
kan text --tab 2 # = kan page text: visible text of a page
kan page eval 'document.title' # run JavaScript, print the JSON result
kan page shot page.png # screenshot a page, background tabs included
kan window shot window.png # screenshot the whole window
kan window new --tabs 3,4 # move tabs into a new window, as they are
kan page reload --hard --tab 3 # also recovers a crashed tab
kan page zoom in # in | out | reset, per site as in Chrome
kan tab discard 3 # free a background tab's memory; it reloads when shown or used
kan devtools open bottom # right | bottom | left | window
kan group create 3,5 --name Research --color blue # tab groups, as in Chrome
kan group list # also add, remove, rename, color, collapse, expand, ungroup, close
kan history search rust --by agent # visits opened by agents (--limit N)
kan history graph --tab 3 # how today's pages led to each other, around this tab's page, and back to where its trail began
kan history time --per host # where today's time went, by site (or by page, or by resource)
kan history resources --tab 3 # what this tab's page is part of: its repository, workspace, project
kan history search --resource 415 --until $(date -v0H -v0M -v0S +%s000) # that resource's visits before today
kan history import # import Chrome's history (again: adds only new visits)
kan statement add marks.layer '{"marks":[…]}' --tab 3 # say something about a page (here: a layer of marks)
kan statement list --tab 3 # what has been said about this tab's page, newest first (--kind, --by)
kan cdp call Network.getCookies # any Chrome DevTools Protocol method
kan app key cmd+shift+t # press any Kan shortcut, as a keyboard wouldA resource is what pages are part of, found from addresses: the path's first two segments, one more while that prefix holds over 80% of the site's pages (the person's own pages, so it adapts as history grows); a page can be part of several. Kan classes a page when it is first recorded and a whole site again whenever its page count reaches a power of two.
history graph costs what it returns, not what history holds: around a page it walks from that page's visits along indexes (at most 300 pages), and without one it reads at most the latest 5,000 visits of the range.
kan app status shows what Kan itself uses: each of its processes (the app, every renderer, the GPU process, Chromium's utility services) with its memory (the footprint Activity Monitor shows), CPU time since it started, and the tabs (by id) and other pages (side panels, DevTools, plugin backgrounds) each renderer runs, plus kan.db's size. It is one reading, with nothing sampled in the background: for CPU usage, read it twice and divide the change in cpuTime by the change in at. A renderer reports itself when a page starts in it, so a tab whose page has not started yet (not loaded, or discarded) has no process; a page restored from the back/forward cache into another process keeps the old one until its next navigation. Showing this is a plugin's job.
Page calls never hang: they fail when the tab's renderer process dies and time out after 30 s (--timeout S to change). Each tab runs in its own Chromium renderer process, so a crashed or stuck page does not affect other tabs or the shell.
History lives in kan.db (SQLite) in the data directory: one row per page and one per visit, with how the visit happened (typed, link, search, back/forward, from another app, agent) and who opened it (human or agent:<name>, from $KAN_AGENT). Kan stores addresses, not page content. Reloads, redirect hops and restored tabs are not visits; a restored tab continues its page's latest visit. A visit belongs to the day it started: looking again on a later day at a page a tab kept (open overnight, or restored) records a restore visit of that day, linked to the old one. Each visit also records how long the person actually looked at it (active_ms): time counts while Kan is the active app, the visit's window is the one used last and is on screen, the screen is unlocked, the visit is the visible tab's, and the person is there (some input within a minute, or the page playing media or in a call). Unlike Chrome's visit duration, background tabs and time away count nothing. kan app info reports what is being looked at now (attention), and kan history time sums it per page or site.
Statements are what people and agents say about pages: each has a kind (lowercase words joined by dots, such as marks.layer), a JSON object body, the page it is about (its address without the #fragment, and an optional anchor within it), who wrote it and when. Kan keeps them in kan.db and never reads a body: what a kind means, how it is checked and shown belongs to the plugin that uses it. A page can have any number of statements; update replaces a body and keeps its author and time. Forgetting a page with history delete does not delete what was said about it.
The protocol is one JSON object per line: {"id":1,"method":"tab.list","params":{}}, validated against the command table. Calls over the socket are recorded as an agent ($KAN_AGENT names it); menus and shortcuts as the person.
Tabs can be grouped as in Chrome: right-click a tab to add it to a new or existing group; click a group's name to collapse or expand it, right-click it to rename, recolor, ungroup or close the group. Links opened from a grouped tab join its group, and groups come back after a restart. Agents sort tabs into groups with the same group commands. Drag a tab between two tabs of a group to add it, past the group's edge to take it out, or drag a group's name to move the whole group, in either layout (kan tab move, kan group move). Shift+Cmd+A searches open tabs. View > Show Tabs Vertically moves tabs to a sidebar on the left, as in Chrome: full titles, scrolling, groups as collapsible sections, a resizable edge, and Shift+Cmd+L to collapse it to icons (kan window tabs-vertical, kan window tabs-collapse).
Kan can have several windows, each with its own tabs, groups and side panel, as workbenches: File > New Window (Cmd+N), Close Window (Shift+Cmd+W). Drag a tab, or a group by its name, out of the tabs into a window of its own, or onto another window's tabs, in either layout. A tab or a whole group moves to another window as it is, without reloading, keeping what was typed, its history and its DevTools (kan window new --tabs … or --group …, kan tab move <tab> --window <id>, kan group move <group> <index> --window <id>). Closed windows' tabs come back with Shift+Cmd+T; closing the last window quits Kan, and every window comes back at the next launch where it was. Commands act on the window used last unless given --window; kan window list lists them, and tab list and group list report each tab's and group's window. Vertical tabs and the sidebar's width apply to every window.
The address bar works like Chrome's omnibox: typing completes addresses you typed or visit often inline (gi → github.com, localhost:3 → localhost:3302) and opens a dropdown of the address, a search, open tabs, matching commands and history, ranked by how often and how recently pages were used. Up/Down move, Return opens, Escape closes, Shift+Delete forgets a history entry. Start with > to run a command by name. Agents get the same suggestions with kan omnibox suggest <text>. Nothing typed leaves the machine.
Menus and shortcuts follow Chrome's for every feature Kan shares with it. DevTools (View > Developer: Cmd+Opt+I, Inspect Elements Cmd+Opt+C, JavaScript Console Cmd+Opt+J, View Source Cmd+Opt+U) docks right of, below or left of the page, or opens in a separate window: use Dock side in DevTools' own menu, or Cmd+Shift+D inside DevTools to switch back to the previous side. Every tab has its own DevTools. CEF's built-in DevTools cannot be embedded in a window it does not own, so Kan loads the DevTools frontend served by its CDP port in a regular browser view, the way remote debugging works. In that mode the frontend's host object is a stub; Kan wraps its dock and close calls and reports them back through a CDP binding.
Kan also exposes a standard CDP endpoint on 127.0.0.1:9333 (--cdp-port=N to change), so tools such as Playwright or agent-browser can attach with connectOverCDP.
Plugins are pages that run Kan commands. A plugin is a folder of static files (a built Svelte or React app works as is) in ~/.config/kan/plugins/<id>/ ($KAN_HOME/plugins/ for a development instance) with an index.html and a manifest.json shaped like a Chrome extension's: {"name": "…", "version": "…", "description": "…", "icon": "icon.png"}, name and version required.
Open it at kan://<id>/; there await kan.call("tab.list") runs any command in the table, with the same validation and errors as the CLI, and pages it opens are recorded as plugin:<id>, or as the person's when the call follows their click or key press in the plugin page (within Chromium's few seconds of user activation, as for popups).
Plugins written in TypeScript use @kan/plugin (packages/kan-plugin), a typed client generated from the command table and named as in the CLI: kan tab open is kan.tab.open({ url }), kan history graph is kan.history.graph({ tab }), with parameter and result types:
import { createClient } from "@kan/plugin";
const kan = createClient(); // in a plugin page: the bridge Kan injects
const tabs = await kan.tab.list(); // Tab[]
kan.on("tab.updated", e => { if (e.url) refresh(); });The same client runs from Node over Kan's socket (createClient({ transport: socketTransport() }) from @kan/plugin/node), for agents' scripts and tests. With Vite, build with base: "./" and develop with vite build --watch into the plugin folder: Vite's dev server serves pages from localhost, and only kan:// pages get the bridge.
A plugin can teach agents how to use it: name a markdown file in the manifest, "skill": "SKILL.md", and kan plugin skill <id> prints it; kan app plugins shows that command for each plugin that has one, and the kan skill tells agents to read it before using the plugin.
Each plugin is its own origin; web pages cannot open plugin pages, embed them or load their files, and only a plugin page's main frame gets kan.
A plugin reads any http(s) address through Kan, whether or not the site allows it by CORS: its pages request kan://<id>/_kan/fetch?url=<encodeURIComponent(address)> (relative: ./_kan/fetch?url=…) and get the site's answer under their own origin, as the person's request (their cookies; method, body and headers as sent, Range too, so a large file can come in parts). Only the plugin's own pages' requests are answered, never a page opened there, and _kan/ in a plugin's folder belongs to Kan. A file:// address is read from this Mac, whole or, with Range, the part asked for (206). A failure Kan meets itself is a 400 (not an http(s) or file address), a 404 (no such file), a 416 (a range the file does not have) or a 502 (the site could not be reached), with the reason as text. Not yet: sites that ask for a password in the browser's own dialog (HTTP authentication), and bodies of several parts with files (FormData with a file).
A plugin can also live in the side panel, right of the page as in Chrome: add "side_panel": {"default_path": "panel.html"} to its manifest, then use the toolbar's side panel button, View > Show Side Panel or kan panel open <id>. The panel belongs to the window and stays while tabs change; kan.on("tab.activated", e => …) and kan.on("tab.updated", e => …) (Chrome's tabs events, with only the fields that changed) let it follow the current page, kan.on("statement.changed", e => …) ({id, kind, change: "added" | "updated" | "deleted", urls}) what is said about it, and its commands act on the tab the user sees. Links out of the panel open in a new tab.
Kan comes with one, Navigation (plugins/navigation, Svelte and TypeScript on @kan/plugin, built by bundle.sh with npm run build): Path shows how you got to the page you are on, as a tree of today's pages, each under the page whose link or new tab led to it, back to where the trail began even on an earlier day, with branches away from the current page folded and sign-in or redirect pages dimmed; Time shows where today's time went, by site and as a timeline of pages with how long each was looked at. Click a page to switch to its tab or open it again.
Kan also comes with Marks (plugins/marks), a blackboard on the page: an agent reads a page and adds a layer of marks (marks.layer statements: highlights, underlines, circles, boxes, brackets, arrows, numbered steps and handwritten notes in the margin, anchored to quoted text, never to coordinates), and the page draws them, stroke by stroke as they arrive and again whenever it loads. Its side panel lists the page's layers: turn one off, delete it, click a mark to scroll to it, or play them again in order. PDFs open in its reader (kan://marks/pdf.html?src=<PDF address>), where agents read and mark them a page at a time. Its skill (kan plugin skill marks) tells agents how.
Kan also comes with Monitor (plugins/monitor), off by default, for developing Kan: app.status shown at kan://monitor/ or in the side panel, every two seconds while visible: Kan's memory and CPU in total and over the last minutes, then each process: Kan itself, the tabs each renderer runs (click one to switch to it), Kan's own pages (panels, DevTools, plugin backgrounds) and Chromium's helpers (GPU, network, storage).
Kan also comes with Auto Group (plugins/auto-group), off by default: a background that puts an ungrouped tab, whenever its title changes, into the existing group it clearly belongs to, by the group's other tabs' addresses and then by words in their titles, and leaves a tab alone when unsure, when it is already grouped, or when you changed its group yourself.
A plugin can also have a background: a function Kan runs on events, without any page of the plugin being open. Name it in the manifest, "background": {"script": "background.js", "events": ["tab.created", "tab.updated", "tab.grouped"]} (also tab.loaded, when a page has finished loading, and statement.changed), and export it by default from that ES module:
import type { Background } from "@kan/plugin";
export default (async (event, kan) => {
if (event.type === "tab.updated" && event.changed.title) { /* … kan.group.add(…) */ }
}) satisfies Background;Each event carries the whole tab (as tab.list shows it, with groupedBy, kept by Kan: who last moved it into, out of or between groups, human, agent (agent:<name> when named) or plugin:<id>; none for a tab opened into a group and left there); tab.updated says what changed (address or title), tab.grouped the group it left and joined and who moved it. Each run is stateless: the module loads in a fresh page in a hidden browser, is called once, and nothing in it survives to the next event, so it asks Kan for what it needs through kan, the same client as in pages (it can also fetch). A plugin's runs are queued one at a time and end after 30 s; the hidden browser closes 30 s after the last run. What a background does is recorded as plugin:<id>, like an agent's actions under its name. kan app plugins shows each background's runs, failures and last run, and kan plugin run <id> '<event JSON>' runs it once on an event of your choice.
Every installed plugin is on until it is listed in config.json's plugins.disabled ({"plugins": {"disabled": ["navigation"]}}), unless its manifest says "enabled": false: then it is off until listed in plugins.enabled (plugins.disabled wins over both; kan app plugins shows "default": false for such a plugin); a disabled plugin's pages do not load, one already open gets no events and its kan.call fails, and it leaves the side panel's menu. The side panel opens with the plugin named (kan panel open <id> or its menu), else the one used last, else side_panel from config.json (Kan's default is its own Navigation). With none of them, showing the panel (the toolbar button, View > Show Side Panel, kan panel toggle) opens it empty for you to pick, and kan panel open says which there are: Kan does not pick one for you.
Nothing watches the folder or the settings: after changing a plugin, reload its page. kan app plugins lists plugins, whether each is enabled, and says why one does not load.