Чому я написав власне автодоповнення для терміналу

Більшість часу в терміналі я проводжу всередині PhpStorm. Роками один інструмент робив цей термінал помітно зручнішим: спливне вікно біля курсора, яке під час набору показувало підкоманди, прапорці, гілки й файли, кожне з коротким описом. Я перестав шукати опції docker compose і прапорці git, бо вони вже були на екрані.

Цей інструмент двічі змінив власника й назву, а потім перестав працювати саме там, де був мені потрібен.

Fig

Про Fig я дізнався з допису в Twitter, як тоді ще називався X. Спробував — і скоро вже не уявляв роботи без нього. Набираєш git ch — і маленьке вікно під курсором пропонує checkout і cherry-pick, а далі назви гілок. Підказки бралися зі специфікацій автодоповнення: по одному файлу на інструмент з описом підкоманд, опцій і аргументів, плюс генератори, які запускають команди на кшталт git branch, щоб підставити актуальні значення. Fig відкрив ці специфікації як withfig/autocomplete, і спільнота написала їх для сотень інструментів.

Я користувався ним рік чи два — у Terminal, iTerm і терміналах JetBrains однаково. У 2023-му AWS купила Fig, а у 2024-му окремий застосунок закрили.

Amazon Q, потім Kiro CLI

Автодоповнення переїхало в Amazon Q Developer CLI, і мені це не сподобалося. Спливне вікно лишилося майже тим самим, але тепер вимагало акаунт Amazon і час від часу розлогінювало, тож доводилося входити знову посеред роботи. До того ж з'явився AI-чат, яким я так і не користувався.

Згодом Amazon Q CLI перейменували на Kiro CLI, і для мене майже нічого не змінилося. Я, як і раніше, користувався лише автодоповненням, акаунт Amazon і періодичний повторний вхід нікуди не ділися, а іноді застосунок доводилося перезапускати, щоб вікно повернулося.

Я з усім цим мирився, бо саме вікно працювало. А потім одного дня воно перестало з'являтися в терміналі PhpStorm, і перезапуск уже не допоміг.

Чому з терміналами JetBrains складно

Щоб відкрити вікно біля курсора, застосунок має знати, де курсор на екрані. У Terminal та iTerm позицію текстового курсора повідомляє macOS Accessibility API. Термінал JetBrains малює власний Java-інтерфейс IDE, і свій курсор через Accessibility він не віддає.

Fig і Kiro CLI обходили це через прихований метод введення: macOS повідомляє активному методу введення, куди вводиться текст, тож позиція курсора діставалася задарма. macOS 27 більше не дозволяє застосунку так вмикати прихований метод введення, і вікно зникло з терміналів JetBrains.

Figxit і Cue

Я спробував альтернативи. І Figxit, і Cue намагаються повернути вікно в стилі Fig. У їхній документації є список підтримуваних терміналів, і JetBrains немає в жодному, але я все одно спробував їх у PhpStorm — раптом запрацює неофіційно. Жоден нічого не показав.

Можна було спробувати додати підтримку JetBrains поверх одного з них, але ідея будувати на чужому застосунку заради однієї потрібної мені речі мені не сподобалася.

Як з'явився TermGuru

Коли в Claude Code з'явилася Fable 5.2, я вирішив написати власний, з однією вимогою, якої інші не виконували: термінал JetBrains — на першому місці.

Я точно знав, що має робити застосунок, тож описав це в одному детальному промпті, а потім доводив до ладу ще в кількох сесіях Claude Code. Жодного місця, де я б застряг, не було.

Бракувало позиції курсора, а IDE її вже знає. TermGuru постачається з невеликим плагіном для JetBrains, який робить одне: коли застосунок питає, він відповідає прямокутником курсора в активному терміналі через локальний unix-сокет. Вміст терміналу він ніколи не читає. Це звичайна Java, скомпільована з рантаймом уже встановленої IDE, тож для збірки не потрібні ні Gradle, ні завантаження JDK. Terminal та iTerm і далі працюють через Accessibility API.

Решта застосунку:

• Хуки оболонки для zsh і bash надсилають застосунку буфер редагування при кожному перемальовуванні й перехоплюють Tab, Return, стрілки та Esc. Поки вікно відкрите, ці клавіші спершу йдуть у застосунок. Коли закрите — працюють власні прив'язки оболонки, тож Tab без вікна лишається звичайним доповненням.
• Рушій розбиває на токени рядок ліворуч від курсора й проходить тими самими специфікаціями Fig, виконаними в JavaScriptCore, тож сотні наявних специфікацій працюють без змін. До них додаються аліаси, історія, команди з PATH і файли.
• Вікно підказок — нативний Swift-застосунок у рядку меню з вікном Liquid Glass на macOS 26.
• CLI tgr встановлює хуки й плагін, перевіряє налаштування через tgr doctor і ставить оновлення.

Усе працює лише на вашому Mac: без акаунта, без телеметрії, без чату. Мережа потрібна, щоб під час збірки завантажити специфікації та іконки, і щоб перевіряти репозиторій на нові теги релізів.

Що є зараз

Я користуюсь ним щодня. Більшість роботи відбувається в IDE поруч із Claude Code, і команди в терміналі я запускаю там постійно.

Останні релізи додали іконки інструментів, файлів і тек з Material Icon Theme, більше можливостей формату специфікацій Fig (exclusiveOn, dependsOn, кешування генераторів), підказки файлів після перенаправлень на кшталт > і 2> та режим vi в обох оболонках.

Готових збірок для завантаження немає. Клонуєте репозиторій і запускаєте make install: він збирає застосунок на вашому Mac, додає один рядок у ~/.zshrc і ~/.bashrc та встановлює плагін у кожну знайдену JetBrains IDE. Якщо раніше ви користувалися Figxit чи Kiro CLI, make install.replace ще й закоментує їхні рядки хуків. Оновлення перемотує копію репозиторію на найновіший тег релізу й перезбирає застосунок.

Потрібні macOS 26 або новіша, Xcode чи його Command Line Tools, Node.js для завантаження специфікацій і zsh або bash 4+. Warp не підтримується, бо він замінює редактор рядка оболонки.

TermGuru — відкритий код і безкоштовний для всіх. Код — на GitHub.