TabHelm
GitHub ↗

Setup guideПосібник із налаштування

From zero to an agent clicking on your tab in about five minutes — then updates, more agents, a remote host, Windows notes and what to do when something does not work. Від нуля до агента, що клікає на вашій вкладці, за п'ять хвилин — а далі оновлення, інші агенти, віддалений хост, нюанси Windows і що робити, коли щось не працює.

1. Requirements1. Що потрібно

  • Node.js 20+ — nodejs.org. Check with node -v.Node.js 20+ — nodejs.org. Перевірка: node -v.
  • Chrome, Chromium, Brave or Edge on Linux, macOS or Windows 10/11.Chrome, Chromium, Brave або Edge на Linux, macOS чи Windows 10/11.
  • At least one agent: a CLI you already use (Claude Code, Codex, Cursor agent, OpenCode, Qoder, Antigravity, Kilo, Cline, CodeBuddy, Grok) or a free OpenRouter key for the built-in agent or Ollama with a model. Nothing else — no accounts with TabHelm, no cloud.Хоча б один агент: CLI, яким ви вже користуєтесь (Claude Code, Codex, Cursor agent, OpenCode, Qoder, Antigravity, Kilo, Cline, CodeBuddy, Grok), або безкоштовний ключ OpenRouter для вбудованого агента, або Ollama з моделлю. Більше нічого — жодних акаунтів TabHelm чи хмари.

2. Install the host2. Встановіть хост

The host is a small Node program that Chrome starts on demand; it launches your agents and bridges them to the panel. One command installs it into ~/.tabhelm/app and registers it with every supported browser.Хост — маленька програма на Node, яку Chrome запускає за потреби; вона запускає ваших агентів і з'єднує їх із панеллю. Одна команда встановлює його в ~/.tabhelm/app і реєструє в усіх підтримуваних браузерах.

Linux / macOS

curl -fsSL https://ivlad003.github.io/tabhelm/install.sh | bash

Windows — PowerShell

irm https://ivlad003.github.io/tabhelm/install.ps1 | iex

Windows — Command Prompt (cmd)

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://ivlad003.github.io/tabhelm/install.ps1 | iex"

The installer downloads the latest release, runs npm ci for the host and writes the native-messaging manifest (files under ~/.config/…/NativeMessagingHosts on Linux, ~/Library/Application Support/… on macOS, registry keys under HKCU on Windows). It ends by printing the folder to load in the next step.Інсталятор завантажує останній реліз, виконує npm ci для хоста й записує маніфест native messaging (файли в ~/.config/…/NativeMessagingHosts на Linux, ~/Library/Application Support/… на macOS, ключі реєстру в HKCU на Windows). Наприкінці він показує папку для наступного кроку.

The installer records your current PATH, because Chrome starts the host with a minimal environment. After installing a new CLI, run the installer again so the host can find it.Інсталятор запам'ятовує ваш поточний PATH, бо Chrome запускає хост із мінімальним оточенням. Після встановлення нового CLI запустіть інсталятор ще раз, щоб хост його знайшов.

3. Load the extension3. Завантажте розширення

  1. Open chrome://extensions (brave://extensions, edge://extensions).Відкрийте chrome://extensions (brave://extensions, edge://extensions).
  2. Turn on Developer mode (top right).Увімкніть Developer mode (праворуч угорі).
  3. Click Load unpacked and choose ~/.tabhelm/app/extension (%USERPROFILE%\.tabhelm\app\extension on Windows).Натисніть Load unpacked і виберіть ~/.tabhelm/app/extension (%USERPROFILE%\.tabhelm\app\extension на Windows).
  4. Optional: pin TabHelm in the toolbar (puzzle icon → pin).За бажанням закріпіть TabHelm на панелі інструментів (іконка пазла → шпилька).
The extension's ID is fixed by a key in its manifest, so the host's manifest always matches it — no need to copy IDs around.ID розширення зафіксований ключем у маніфесті, тож маніфест хоста завжди йому відповідає — нічого копіювати не треба.

4. First chat4. Перший чат

  1. Open any page and click the TabHelm icon — the side panel opens for this tab.Відкрийте будь-яку сторінку й натисніть іконку TabHelm — бічна панель відкриється для цієї вкладки.
  2. Pick an agent in the list (only installed ones are enabled; the others show how to install them) and, if you like, a model next to it.Оберіть агента в списку (активні лише встановлені, решта показує, як їх поставити) і за бажанням модель поруч.
  3. Type a task — “Find the cheapest item on this page and open it” — and press Send. The agent starts with your first message; the first run may ask you to sign in (a browser window opens).Напишіть завдання — «Знайди найдешевший товар на цій сторінці й відкрий його» — і натисніть Send. Агент стартує з першим повідомленням; перший запуск може попросити увійти (відкриється вікно браузера).
  4. Watch the Steps block: every click, typed text and navigation is listed. Actions that change the page ask for approval unless Auto-approve is on.Стежте за блоком Steps: кожен клік, введений текст і перехід у списку. Дії, що змінюють сторінку, потребують підтвердження, якщо не ввімкнено Auto-approve.
The agent works in your real, logged-in browser. Give it tasks the way you would give them to a colleague at your keyboard, and keep Auto-approve off on sites where a wrong click costs money.Агент працює у вашому справжньому браузері з вашими логінами. Давайте йому завдання так, як дали б колезі за вашою клавіатурою, і не вмикайте Auto-approve на сайтах, де хибний клік коштує грошей.

5. Agents and logins5. Агенти й логіни

AgentАгентHow TabHelm finds itЯк TabHelm його знаходитьSign-inВхід
Claude Codeclaude on PATHclaude → /login (orабо ANTHROPIC_API_KEY)
Codexcodex on PATHcodex login
Cursor Agent CLIagent / cursor-agentagent login
OpenCodeopencodeopencode auth login (free models tooє безкоштовні моделі)
Qoder, Antigravity, Kilo, Cline, CodeBuddynpm run install-agent -- <name> inу ~/.tabhelm/app/hostthe agent asks on first useагент попросить при першому використанні
OpenRouter (built-inвбудований)alwaysзавждиnpm run set-key -- openrouter — free :free models are listed firstбезкоштовні моделі :free йдуть першими
Ollama (built-in, localвбудований, локально)ollama runningзапущенийollama pull qwen3:30b (needs tool callingпотрібна підтримка tool calling)

npm run install-agent -- --list shows every agent in the official ACP registry (40+); any of them installs into ~/.tabhelm/agents/<name> and appears in the panel automatically. API keys for the built-in agents live in ~/.tabhelm/env.npm run install-agent -- --list показує всіх агентів з офіційного реєстру ACP (40+); будь-який ставиться в ~/.tabhelm/agents/<name> і автоматично з'являється в панелі. Ключі API для вбудованих агентів зберігаються в ~/.tabhelm/env.

6. Updating6. Оновлення

  1. Run the same install command again. It stops a running host, replaces ~/.tabhelm/app and re-registers the host.Запустіть ту саму команду встановлення. Вона зупинить запущений хост, замінить ~/.tabhelm/app і перереєструє хост.
  2. On chrome://extensions press ↻ on the TabHelm card, then reopen the panel.На chrome://extensions натисніть ↻ на картці TabHelm і знову відкрийте панель.

The panel checks this site's news.json once an hour and shows an Update banner when a newer release exists (Settings → Check for updates checks right away). Do not remove the extension to update — and if you do, your chats come back: the host keeps a backup in ~/.tabhelm/state.json.Панель раз на годину перевіряє news.json цього сайту й показує банер Update, коли є новіший реліз (Settings → Check for updates перевіряє одразу). Видаляти розширення для оновлення не потрібно — а якщо видалите, чати повернуться: хост тримає резервну копію в ~/.tabhelm/state.json.

7. Around the panel7. Що є в панелі

What it doesЩо робить
HistorySaved chats with search; open one to continue it (its page opens too), export (⬇ Markdown, { } JSON), delete (🗑, Clear all).Збережені чати з пошуком; відкрийте, щоб продовжити (сторінка теж відкриється), експорт (⬇ Markdown, { } JSON), видалення (🗑, Clear all).
SettingsSkills from links or whole repositories, model options, page options (highlight finds), remote host, experimental flags (all off by default), version and updates.Скіли за посиланнями чи цілими репозиторіями, опції моделі, налаштування сторінки (підсвічування знахідок), віддалений хост, експериментальні прапорці (усі вимкнені), версія й оновлення.
＋Attach files, add the page selection, voice (flag), record video, make a skill from this chat, share tabs (tab group), working folder.Вкладення, виділене на сторінці, голос (прапорець), запис відео, скіл із цього чату, спільні вкладки (група), робоча папка.
%Context meter: how full the agent's context window is; click for tokens and cost.Індикатор контексту: наскільки заповнене вікно агента; клік — токени й вартість.
Guide modeAsk “guide me through …” and the agent shows every step on the page and waits for your click (Next / Back / Skip); ▶ Auto lets it click through the steps itself with pauses.Попросіть «проведи мене через …» — агент показує всі кроки на сторінці й чекає вашого кліку (Next / Back / Skip); ▶ Auto — агент сам проходить кроки з паузами.
＋ → Pick element / Select areaClick one element or drag a rectangle; the elements (ref, selector, text, HTML) go into your message.Клікніть елемент або протягніть прямокутник — елементи (ref, селектор, текст, HTML) підуть у ваше повідомлення.
Page scripts & stylesExperimental flag: a library of CSS / JS presets with URL patterns, run from ＋ or automatically on matching pages.Експериментальний прапорець: бібліотека CSS/JS-пресетів із шаблонами URL, запуск із ＋ або автоматично на відповідних сторінках.
Enter while workingпід час роботиQueues a message; the agent gets it with its next step.Ставить повідомлення в чергу; агент отримає його з наступним кроком.
Alt+Shift+TSend the selected text (or right-click an image) to the chat as context.Надіслати виділений текст (або картинку через правий клік) у чат як контекст.

The full reference, with diagrams, is in the README (українською).Повний опис із діаграмами — у README українською (English).

8. Remote host (relay)8. Віддалений хост (relay)

Run the agents on a VPS or another computer while the panel stays in your Chrome. Both sides connect out to a tiny relay you host, so no SSH or open ports are needed.Агенти працюють на VPS чи іншому комп'ютері, а панель лишається у вашому Chrome. Обидві сторони підключаються назовні до маленького relay на вашому сервері, тож SSH чи відкриті порти не потрібні.

Deploy the relay (Dokploy or any Docker host)Розгорніть relay (Dokploy або будь-який Docker)

  1. Application from the repository, build path relay (Dockerfile).Application з репозиторію, build path relay (Dockerfile).
  2. Environment: RELAY_KEY = a long random string (openssl rand -base64 24).Змінна середовища RELAY_KEY — довгий випадковий рядок (openssl rand -base64 24).
  3. Domain relay.yourdomain.com → port 8080, HTTPS on. Check: curl https://relay.yourdomain.com/ → TabHelm relay: 0 host(s).Домен relay.ваш.домен → порт 8080, HTTPS увімкнено. Перевірка: curl https://relay.ваш.домен/ → TabHelm relay: 0 host(s).

Start the host on the remote machineЗапустіть хост на віддаленій машині

Install TabHelm there with the same command as in step 2 (registering it with a browser is not needed), sign the agents in once, then:Встановіть там TabHelm тією самою командою, що в кроці 2 (реєструвати в браузері не треба), один раз залогіньте агентів, а потім:

cd ~/.tabhelm/app/host
npm run relay -- wss://relay.yourdomain.com --key <RELAY_KEY> --name my-vps

The host prints a pairing code such as K7PM-3QWX (10 minutes, single use) and keeps running; keep it alive with tmux, systemd or run the agents in a container built from host/Dockerfile.agent (the code appears in the container log).Хост друкує код парування на кшталт K7PM-3QWX (10 хвилин, одноразовий) і працює далі; тримайте його живим через tmux, systemd або запустіть агентів у контейнері з host/Dockerfile.agent (код буде в логах контейнера).

Pair the panelСпаруйте панель

Settings → Remote host: relay URL + the code → Connect. The remote agents appear in the list. Use local host switches back (the pairing is kept), Forget pairing drops it.Settings → Remote host: URL relay + код → Connect. Віддалені агенти з'являться в списку. Use local host повертає до локального (парування зберігається), Forget pairing видаляє його.

The relay forwards page snapshots and screenshots in clear text inside TLS. Keep RELAY_KEY private and use only a relay you run yourself.Relay пересилає знімки сторінок і скриншоти у відкритому вигляді всередині TLS. Тримайте RELAY_KEY у секреті й користуйтеся лише власним relay.

9. Windows notes9. Нюанси Windows

  • Use the PowerShell command, or the cmd variant from a Command Prompt; curl … | bash does not work there.Використовуйте команду для PowerShell або варіант для cmd; curl … | bash там не працює.
  • The host is registered in the registry (HKCU\Software\Google\Chrome\NativeMessagingHosts\com.tabhelm.host, same for Edge, Chromium, Brave) and started through tabhelm-host.cmd.Хост реєструється в реєстрі (HKCU\Software\Google\Chrome\NativeMessagingHosts\com.tabhelm.host, так само для Edge, Chromium, Brave) і запускається через tabhelm-host.cmd.
  • Agents installed by npm (agent.cmd, Kilo, Cline…) are launched through cmd.exe — needed since Node 20.12.Агенти, встановлені через npm (agent.cmd, Kilo, Cline…), запускаються через cmd.exe — так вимагає Node від 20.12.
  • The folder picker is a PowerShell dialog; 1Password hand-off needs op.exe on PATH; tab-audio transcription needs ffmpeg + whisper-cli or a transcription API.Вибір папки — діалог PowerShell; передача з 1Password потребує op.exe у PATH; транскрипція звуку вкладки — ffmpeg + whisper-cli або API транскрипції.

10. Troubleshooting10. Якщо щось не так

SymptomСимптомWhat to doЩо робити
Host offline / “Specified native messaging host not found”Host offline / «Specified native messaging host not found»Run the installer again (it re-registers the host), restart the browser, reopen the panel. Chrome loaded from a different profile needs the manifest in that profile's config dir.Запустіть інсталятор ще раз (він перереєструє хост), перезапустіть браузер, знову відкрийте панель. Для іншого профілю Chrome маніфест має лежати в конфігу того профілю.
The agent is greyed out in the listАгент сірий у спискуIts CLI is not on the PATH the host saw. Install it, then run the installer again. npm run install-agent -- <name> works for registry agents.Його CLI немає в PATH, який бачив хост. Встановіть, потім ще раз запустіть інсталятор. Для агентів із реєстру — npm run install-agent -- <name>.
spawn EINVAL (Windows)Fixed in 0.19.1 — update.Виправлено в 0.19.1 — оновіться.
“Cannot remove item … app\host” while updating«Cannot remove item … app\host» під час оновленняThe installer now stops the running host; if it still fails, close the TabHelm panel and run it again.Інсталятор тепер зупиняє запущений хост; якщо не допомогло — закрийте панель TabHelm і запустіть ще раз.
Version mismatch warningПопередження про різні версіїExtension and host differ: press ↻ on chrome://extensions after updating. Make sure Chrome loads ~/.tabhelm/app/extension, not an old copy.Розширення й хост різних версій: натисніть ↻ на chrome://extensions після оновлення. Переконайтеся, що Chrome завантажує ~/.tabhelm/app/extension, а не стару копію.
Nothing happens on a chrome:// page or the Web StoreНічого не відбувається на сторінці chrome:// чи у Web StoreChrome does not let extensions act there. Open a normal web page.Chrome не дозволяє розширенням діяти там. Відкрийте звичайну веб-сторінку.
Where are the logs?Де логи?~/.tabhelm/host.log; the extension's service worker console is on chrome://extensions → TabHelm → “service worker”.консоль service worker розширення — chrome://extensions → TabHelm → «service worker».

Still stuck? Open an issue with the panel version, OS and the tail of host.log.Не допомогло? Відкрийте issue з версією панелі, ОС і кінцем host.log.