Install

Tabkyra needs Node 20 or newer, git, and a Chromium browser at version 141 or newer, such as Helium, Chrome or Brave. It runs on macOS and Linux. Windows registry entries are written but untested.

Clone it into a folder of its own, because the first build puts two dependencies, pi-mono (pinned and patched) and mini-lit, beside the clone:

Terminal

mkdir tabkyra-src && cd tabkyra-src
git clone https://github.com/baney75/tabkyra && cd tabkyra
(cd cli && npm install && npm run build && npm link)
tabkyra setup

If npm link fails with a permissions error, skip it and run node cli/dist/index.js setup.

tabkyra setup builds the extension, registers the native host with every Chromium browser it finds (Helium, Chrome, Chromium, Brave, Edge, Arc, Vivaldi and Opera), offers to add Tabkyra to Claude Code and Codex, prints the config for OpenCode, Cursor and OMP, and offers to install the skills. --yes accepts every offer, --no-wait skips waiting for the extension, and --timeout <seconds> bounds the wait.

On a Mac with a warm npm cache, a fresh clone reached "Connected" in 45 seconds. A first install with a cold cache downloads more and can take a few minutes.

Load the extension

Browsers make you load an unpacked extension by hand. Setup shows the exact folder:

Open chrome://extensions, turn on Developer mode and click Load unpacked.
Pick the dist-chrome folder inside the clone.
Optional: click Details on Tabkyra and turn on Allow user scripts for faster page scripts.

Setup waits until the extension connects. The extension has a fixed id, kenehmggpggpiolepbjojeenmeapgfoc, in every Chromium browser.

Let an agent install it

The Tabkyra site has a setup prompt you can paste into Claude Code, Codex, pi, OMP or any agent that can run commands. It clones and builds the CLI, runs tabkyra setup --yes --no-wait, stops so you can load the extension, connects the harness, installs the skills and calls status. Inside the extension, Settings › Bridge has a Copy setup prompt for your agent button that does the same for the version you have loaded.

Connect your agent

tabkyra install (run by setup) writes a launcher at ~/.config/tabkyra/tabkyra that pins Node by absolute path, so an agent started from a GUI app doesn't need node on its PATH. JSON configs need the full path, not ~: replace /home/you below with your own home folder (echo $HOME prints it).

Claude Code and Codex:

Terminal

claude mcp add --scope user tabkyra -- ~/.config/tabkyra/tabkyra mcp
codex mcp add tabkyra -- ~/.config/tabkyra/tabkyra mcp

OpenCode (~/.config/opencode/opencode.json):

JSON

{ "mcp": { "tabkyra": { "type": "local", "command": ["/home/you/.config/tabkyra/tabkyra", "mcp"], "enabled": true } } }

Cursor (~/.cursor/mcp.json):

JSON

{ "mcpServers": { "tabkyra": { "command": "/home/you/.config/tabkyra/tabkyra", "args": ["mcp"] } } }

OMP (~/.omp/agent/mcp.json):

JSON

{ "mcpServers": { "tabkyra": { "type": "stdio", "command": "/home/you/.config/tabkyra/tabkyra", "args": ["mcp"], "enabled": true } } }

pi has no MCP client, so tabkyra pi-extension writes a native pi extension instead. Any other MCP client can run the stdio server with ~/.config/tabkyra/tabkyra mcp.

Then ask your agent something like: "Use tabkyra to open news.ycombinator.com and list the top five stories."

Site access

An agent asks before it opens a site you haven't allowed. Claude Code and Codex show the question in the chat; otherwise answer it in the side panel under Settings › Bridge.

Command	What it does
`tabkyra allow <host>`	Let agents open a site without asking. Subdomains are included.
`tabkyra ask`	Ask before any site not yet allowed (the default).
`tabkyra allow-all`	Open any site without asking.
`tabkyra status`	Whether the browser is connected, which sites are allowed, which browsers have the host.

What an agent can do

Tools	What they do
`status`	Connection, allowed sites and the agent's own tabs
`navigate`, `tabs_context`, `tabs_create`, `tabs_select`, `tabs_close`	Open pages in the agent's own background tabs
`read_page`, `find`, `get_page_text`, `get_page_html`, `screenshot`	Read a page as element references and text, or look at it
`click`, `type`, `fill`, `press`, `hover`, `scroll`, `drag`, `actions`	Act with real input events, by reference or by screenshot pixel
`run_js`, `wait`, `read_console`, `read_network`	Scripts, waits and debugging
`handle_dialog`	Answer an alert, confirm or prompt box
`tabs_show`	Bring a tab in front of you, for a sign-in or when you want to see it
`library_add`, `library_search`, `library_cite`	The source library

Each agent session gets its own tab group, such as "Tabkyra · claude", and keeps it across extension reloads. Hidden agent tabs render at a fixed 1280×800 viewport, so screenshot pixels and click coordinates match.

Skills

Terminal

tabkyra skill install            # Claude Code, Codex and OpenCode, wherever they're installed
tabkyra skill list
tabkyra skill print >> AGENTS.md # any other agent, as a section of a project's AGENTS.md

Skill	What it does
`tabkyra`	The browser loop, dialogs, safety rules and cleanup
`academic-research`	Find papers, verify each DOI, metadata and retraction status, save BibTeX and Obsidian notes
`osint`	Public-record research on companies, domains and people, with a purpose check
`news-research`	Primary sources, wire services, more than one side, every statement labeled
`dorks`	Search operators and recipes for Google, Bing, DuckDuckGo, GitHub and Scholar
`autoresearch`	`/autoresearch`: a research loop with sub-questions, a budget and a stop rule
`rsi`	`/rsi`: turn lessons from real work into small, linted, reviewed skill edits
`artifacts`	Self-contained HTML reports, checked in the browser before hand-off
`proton-pass`	Credentials through Proton Pass, 1Password or Bitwarden, never through the model
`kyraskillmaker`	Write a skill to Tabkyra's standard
`fix`	`/fix`: a stronger model rewrites a skill that failed a smaller one, then retests it until it passes
`bug`	`/bug`: a bug report with private details removed, filed only when you say so
`adversarial-review`	A second model tries to prove a change wrong before you accept it

Setup never replaces a skill of the same name that Tabkyra didn't write. Every skill passes tabkyra skill lint, which CI runs on every pull request. It refuses hidden text, instruction overrides, fake system turns, piped remote code, secret exfiltration, credential-file reads, config tampering, safety bypasses, encoded blobs and remote images. The threat model and every rule are in docs/skill-security.md.

Source library

Every source is fetched from its DOI's registry and checked against OpenAlex and Crossref's retraction notices before it's saved. An unregistered DOI is refused. When a check can't finish, the source is saved marked "retraction check incomplete" until tabkyra library verify completes it.

Terminal

tabkyra library add 10.1037/0033-2909.132.3.354 --quote "..." --location "p. 354"
tabkyra library cite cepeda2006distributed --style apa
tabkyra library export --format bibtex --out refs.bib
tabkyra library obsidian ~/Vault

cite supports APA, MLA, Chicago, IEEE, Harvard and Vancouver. export writes BibTeX, RIS or CSL for Zotero, Word and LaTeX. obsidian writes one note per source into the vault's Sources/ folder.

The side panel agent

Press Cmd+Shift+S (Ctrl+Shift+S elsewhere) to open the side panel and chat with a page directly. Add an API key for a provider under Settings › API Keys, or an OpenAI-compatible server such as vLLM or SGLang under Custom Providers. API use is billed by the provider. Subscription sign-ins are not offered: the ones Tabkyra's upstream shipped posed as other companies' apps, which their terms forbid. The sources are in docs/auth-policy.md.

Private mode and bug reports

Settings › Privacy › Private mode limits the side panel agent to OpenRouter, sent with zero data retention required and no fallback on every request, and to models on this computer or on hosts you list as your own. Every other provider is refused. A local server that forwards to a cloud model is still a cloud service. Private mode covers the side panel agent; an outside agent using the bridge follows its own settings.

Bug reports are off by default. When on, side panel errors are kept in the browser with web addresses, IP addresses, emails, key-like strings and home paths removed. Review report shows the text for editing, and Copy and open GitHub copies it and opens a blank issue. Nothing is sent until you paste and submit.

Safety model

The agent asks before it opens a new site.
The MCP server tells every agent that page content is untrusted, that it must ask you before sending, posting, buying, deleting or changing settings under your sign-in, and that it never types passwords or payment details. For a sign-in or a captcha, it brings the tab to you.
These are instructions to the model, not enforcement. A hostile page can still attempt prompt injection. The site permission limits which sites an agent can open, not what it does on a site you've allowed, including running scripts with run_js. Allow only sites you'd let an agent act on, and run agents in a separate, signed-out browser profile for high-stakes accounts.
Agents stay in their own tab group, can't see your other tabs, and their popups don't steal focus. tabs_show is the only tool that changes what you see.
By default nothing listens on the network. The native host relays over a Unix socket in /tmp/tabkyra-bridge-<user>/ (0700 directory, 0600 socket). Any program running as you can reach it, the same trust level as your shell.
The host manifest's allowed_origins names only Tabkyra's extension id, so no other extension can make the browser start it.
Remote access is opt-in. tabkyra serve binds 127.0.0.1 only and requires a bearer token (tabkyra token create <name> --scope ...) limited to the scopes you pick; a session never sees a tool outside them, and remote sessions never answer site-permission requests. Other machines reach it only through tabkyra tunnel tailscale (tailnet only unless you pass --public) or tabkyra tunnel cloudflare, which you start and stop.

Updating

Terminal

tabkyra update --check   # exit 0 up to date, 100 update available
tabkyra update           # download, verify the signature and checksum, swap in, keep the last version
tabkyra update --rollback

Releases are signed with minisign, and an update with a bad signature or checksum is refused. Nothing updates on its own; the side panel shows a quiet "Update available" line. No release has been published yet, so for now update a source install the way you installed it: pull the latest code and run the install steps again.

Troubleshooting

tabkyra doctor checks Node, the build, each browser's host manifest, the live connection, Allow user scripts and each detected agent's config. It prints one fix per problem and exits 1 on any failure.

"Tabkyra isn't connected." The browser isn't running with the extension loaded, or the extension hasn't reached the native host yet. tabkyra doctor says which.
The agent stops and asks about a site. That's the permission prompt. Approve it, or run tabkyra allow <host> ahead of time.
After rebuilding the extension, run tabkyra reload.

Credits

The agent bridge (native messaging host, CLI and MCP server, agent tab groups, background screenshots and input, per-tab side panels and the foreground guard) is the work of 0xSero (0xSero/sitegeist). The extension and its side panel agent are Mario Zechner's Sitegeist, built on his pi and mini-lit libraries. Tabkyra is licensed AGPL-3.0, like upstream.