Voktty Extension Examples

Small, practical examples for learning how to extend Voktty.

Website · Documentation · Voktty source code

---

This repository contains experimental and reference extensions for the Voktty terminal workspace. The examples are intentionally small: use them to learn how to create commands, expose AI tools, work with the active workspace, and apply Voktty's approval model.

These are learning examples, not a polished plugin marketplace or a collection of production-ready integrations. Fork one, change its manifest, and use it as a starting point for your own extension.

The examples target Voktty's extension API. They are not VS Code extensions and are not compatible with the VS Code extension API.

Examples in this repository

Example	What it demonstrates	Main command
voktty-project-doctor	Read-only checks for common development tools in the active workspace.	Voktty: Check project environment
voktty-dev-tasks	Discovering project scripts and exposing approved development tasks.	Voktty: Show project tasks
voktty-git-flow	Reading the active Git repository without changing it.	Voktty: Git repository summary
voktty-docker-toolkit	Inspecting Docker and Compose status through a read-only tool.	Voktty: Check Docker status
voktty-php-toolkit	Inspecting PHP, Composer, extensions, and project dependencies.	Voktty: Diagnose PHP and Composer
voktty-security-baseline	Detecting potentially sensitive untracked filenames without reading file contents.	Voktty: Check sensitive filenames
sample-mcp-client	A minimal example of an extension that connects to an external MCP server.	MCP: Connect server
terax-web-gateway	A larger web-access example with configuration and start/stop commands.	Web Gateway: Start web server

The terax-web-gateway folder is kept as a compatibility/reference example; some of its existing identifiers still use the older Terax name.

What to look at first

Start with one of the small read-only examples:

• voktty-project-doctor shows a command plus a read-only AI tool.
• voktty-git-flow shows how to expose a focused repository summary.
• voktty-security-baseline shows how to make a narrow security check without reading file contents.
• voktty-dev-tasks shows the difference between inspection and an approved action.

Every example contains a package.json manifest. The manifest declares the extension entry point and the contributions made to Voktty:

• contributes.commands adds commands to the command palette.
• contributes.aiTools makes tools available to the Voktty agent.
• main points to the compiled extension entry point, usually dist/extension.js.

Install the examples locally

Clone or copy this repository into Voktty's extensions directory:

• macOS and Linux: ~/.voktty/extensions/
• Windows: %USERPROFILE%\.voktty\extensions\

For example, in PowerShell:

git clone https://github.com/voktty/extensions.git "$env:USERPROFILE\.voktty\extensions"

Reload extensions from Settings in Voktty. Each subdirectory is loaded independently and can be enabled or disabled without restarting the app.

Create your own extension

Create a new directory and add a manifest like this:

{
  "name": "my-voktty-extension",
  "displayName": "My Voktty Extension",
  "version": "0.1.0",
  "description": "A short description of what this example does",
  "publisher": "voktty",
  "main": "dist/extension.js"
}

Then add command and AI-tool contributions as needed. The examples in this repository are deliberately different so you can compare read-only tools, approval-gated actions, workspace inspection, and external integrations.

Safety model

Read-only examples inspect the active workspace and do not modify project files, Git, Docker, or package metadata. Examples that can execute commands or control a service must go through Voktty's normal tool-approval flow.

Review an example's README.md and package.json before adapting it. Treat the code and configuration as sample material and adjust permissions for your own use case.

License

This repository is distributed under the Apache-2.0 license.