Agents and extensions

Voktty integrates external coding agents through terminal sessions and supports lightweight user extensions through a bounded extension API.

Terminal coding agents

The launcher can start configured commands for Claude Code, Codex, Gemini CLI, Pi, OpenCode and Grok. It can create one to four balanced panes and persists the start command per agent.

Agent state is detected from OSC sequences rather than arbitrary output. Hook-backed agents converge on the Voktty OSC 777 marker and can report started, working, attention, finished and exited transitions.

The notification router chooses a delivery path based on focus:

  • focused and visible: suppress redundant notifications;
  • focused but hidden: show an in-app toast;
  • unfocused: request an operating-system notification;
  • persistent attention: expose the notification bell and focus shortcut.

Claude, Codex, Gemini and Pi use their respective hook or extension mechanisms. Hook installation preserves foreign configuration and is idempotent. OpenCode and Grok currently rely on process-lifecycle detection rather than attention hooks.

Extension layout

User extensions live under:

~/.voktty/extensions/<extension-folder>/

Each extension needs a valid package.json with at least name, publisher and main. Its id is publisher.name.

The extension store persists enabled ids in the application data file:

%APPDATA%/dev.voktty.app/voktty-extensions.json

The exact platform data directory varies by operating system.

Extension lifecycle

  1. The extension store marks itself initialized immediately to prevent duplicate startup.
  2. Scanning and activation are deferred until after the first React render.
  3. Enabled extensions activate one at a time.
  4. activate() has a five-second timeout.
  5. A timed-out or thrown extension is marked as failed while the rest of the app continues.

voktty API

The current API exposes:

Area Capability
voktty.commands Register and execute commands.
voktty.ai Register an AI tool with a name, description and executor.
voktty.window Show information, warning and error messages.
voktty.terminal Execute a bounded one-shot terminal command.
voktty.workspace Read the active workspace root.

voktty.terminal.execute() is a one-shot shell command with a bounded timeout. Extensions must not use it for servers or other continuous processes. New native capabilities require matching Rust commands and Tauri capability entries.

Extension safety

Treat extensions as trusted local code. They can add commands and AI tools, and the terminal executor can run commands as the current user. Keep extension folders reviewable and disable unknown extensions before troubleshooting a startup failure.