What Hefty Can Do

Instruments are how Hefty interacts with your computer and the world around it. When Hefty decides it needs to run a command, open a website, or manage a file, it reaches for an instrument. You don't need to tell Hefty which one to use - it picks the right one based on what you asked for.

Why instruments and not tools? A tool acts on something - it changes it, moves it, breaks it apart. An instrument is more nuanced: it measures, translates, and channels intent with precision. A wrench turns a bolt; a caliper reads a dimension. Hefty's capabilities work the same way - they don't just execute, they observe, interpret, and adapt. That's the difference between brute-force automation and something that actually understands what it's doing.

Instrument Origins

Instruments come from four different sources, each with distinct characteristics in how they're provided, managed, and made available to Hefty.

📦
Internal
Core built-in instruments that ship with Hefty — file operations, shell execution, web requests, and more. Always available.
🧩
Plugin
Instruments provided by installed third-party plugins. Added and removed without restarting Hefty.
⚡
Dynamic
User-created custom instruments defined through the Instruments Dialog. Persist across restarts.
☁️
Platform Service
Cloud-backed services provided by the platform. Available based on your deployment configuration.

Every instrument — regardless of origin — integrates identically into Hefty's cognition pipeline and follows the same security model.

Built-in Capabilities

⚡
Run Commands
Execute shell commands just like you would in a terminal. Install packages, run build scripts, check git status, or use any CLI tool on your system.
🌐
Web & APIs
Make HTTP requests to interact with APIs, download data, or check services. Open pages in your browser to show you results directly.
📱
Applications
Launch, list, and close applications on your system. Hefty can open your editor, check what's running, or stop a process.
📸
Screen & Clipboard
Take screenshots to see what's on your display. Copy text to the clipboard. Hefty can "see" your screen and work with visual information.
🧠
Analysis
Summarize long documents, extract structured data from text, and search through your conversation history for past context.
💬
Ask You
When Hefty needs clarification, it asks. Request your input, ask for confirmation before sensitive actions, or let you choose between options.
📚
Knowledge
Learn new skills from structured text, recall data about known entities, and manage secrets securely for use in API calls.
🔧
System
Read environment variables and access system configuration. Hefty can check your setup and adapt its approach accordingly.

How Hefty Picks the Right Instrument

You don't need to know instrument names. When you send a message, Hefty's cognition pipeline figures out which instruments are needed, then the reasoning phase decides exactly what to call and with what parameters. If something fails, Hefty sees the error and tries a different approach.

Over time, Hefty learns from how it uses its instruments - which approaches work well for specific situations and which to avoid - so it gets better the more you use it.

Safety

Every instrument has a risk level so Hefty understands the impact of what it's about to do:

  • Read-only — just looking, no changes made to anything
  • Local write — modifies files or data on your machine
  • System execute — runs commands in your terminal
  • Network — makes external network requests
  • Critical — high-impact, destructive, or irreversible operations

Hefty factors risk into its planning and shows the risk level alongside each action in the UI, so you always know what's happening.

Extending Hefty

Hefty ships with a full set of built-in instruments, but you can add more:

🔌
MCP Connections
Connect to external MCP servers and their capabilities become available as instruments instantly. This is how you integrate Hefty with other AI ecosystems.
✨
Custom Prompts
Define specialized AI tasks as reusable instruments - like a code reviewer that applies your team's checklist to any code snippet.
🔗
API Endpoints
Point Hefty at any HTTP API and it becomes a callable instrument. Define the URL, method, and parameters - Hefty handles the rest.
📦
Plugins
Install third-party instrument packages. Plugins can be added, enabled, or removed without restarting Hefty.

All extensions persist across restarts and can be managed from the Hefty UI.

The Instruments Dialog

The Instruments Dialog is the central management interface for all instruments. Access it via the User Menu → Instruments option. This feature is available to admin users only.

The dialog is organized into four tabs:

  • All Instruments — every available instrument grouped by origin type
  • Dynamic — user-created custom instruments with a creation button
  • Browse — plugin marketplace catalog for discovering and installing plugins
  • Installed — currently installed plugins with management controls

All Instruments

Instruments are grouped by their origin type in collapsible sections — Internal, Plugin, Dynamic, and Platform Service. Each instrument in the list displays:

  • Display name (humanized from the internal identifier)
  • Category badge
  • Risk level badge (color-coded as described in the Safety section)
  • Origin label (shown for plugin and dynamic instruments)
  • External service indicator (when a plugin requires an external service)

Clicking any instrument opens a detail panel showing the instrument's full description, capabilities and keywords, origin information, risk level details, and — for Custom Prompt instruments — the prompt template, model hint, and max tokens setting.

Creating Dynamic Instruments

Dynamic instruments are user-created tools you define through the Dynamic tab in the Instruments Dialog. Click "New Dynamic Instrument" to start. Choose from four types, each with its own configuration. Once created, dynamic instruments are available to Hefty immediately and persist across restarts.

Custom Prompt

An LLM-powered prompt template that becomes a reusable instrument. Define a template with parameter placeholders and Hefty fills them in at invocation time.

Template
The prompt text. Use {{param}} syntax for parameters that Hefty fills in at runtime. Example: "Summarize the following article: {{article_text}}"
Max Tokens
Maximum number of tokens the LLM response should contain.
Model Hint
Optional hint for which model to prefer for this prompt.
Parse as JSON
Toggle that tells Hefty to parse the LLM output as a JSON structure instead of plain text.

API Endpoint

Wrap any HTTP endpoint as an instrument. Hefty calls the endpoint with the parameters you define and passes the response back to the cognition pipeline.

Method
HTTP method: GET, POST, PUT, DELETE, PATCH.
URL
The endpoint URL template. Can contain parameter placeholders.
Headers
JSON object of HTTP headers to include in the request.
Body
Request body template (for POST/PUT/PATCH). Supports parameter placeholders.
Response Mapping
Rules for extracting data from the API response before passing it to the cognition pipeline.
Timeout
Request timeout in milliseconds.

MCP Client

Connect to an MCP (Model Context Protocol) server. The server's capabilities become available as instruments instantly.

Transport
Connection transport type: HTTP, WebSocket, or Stdio.
Endpoint URL
Server URL (for HTTP and WebSocket transports).
Command
Executable command to launch the MCP server (for Stdio transport).
Args
Command-line arguments passed to the executable (for Stdio transport).

RSS Feed

Monitor an RSS or Atom feed. Hefty periodically fetches new items and makes them available as instrument output.

Feed URL
The URL of the RSS or Atom feed to monitor.
Max Items
Maximum number of items to keep from the feed.
Refresh Interval
How often (in minutes) to fetch new items from the feed.

Dynamic instruments can be deleted from the detail panel when no longer needed.

Plugin Marketplace

The Browse tab in the Instruments Dialog is Hefty's plugin marketplace — a catalog of third-party instrument packages you can install to extend Hefty's capabilities. Plugins add new instruments without restarting the application.

The marketplace provides a search bar with debounced search. Type keywords to filter the catalog, and results update as you type without needing to press Enter or submit a query.

Each plugin card in the catalog displays the following information:

  • Name — the plugin's display name
  • Description — a short summary of what the plugin does
  • Author — who created the plugin
  • Category — the plugin's assigned category
  • Instruments — the list of instruments the plugin provides
  • Install count — how many times the plugin has been installed

To install a plugin, click the Install button on its card. The button enters a loading state while the plugin is being downloaded. Once installation completes, the plugin is marked with an Installed badge and its instruments become available immediately in the All Instruments tab. Download sizes may be shown before installing.

Plugins already installed on your instance show an Installed badge on their card, so you can tell at a glance what you already have.

Managing Installed Plugins

The Installed tab in the Instruments Dialog shows all plugins currently installed on your Hefty instance. From here you can manage plugin lifecycle — enable or disable individual plugins, check versions, apply updates, and uninstall.

Each installed plugin entry displays the following details:

  • Enable / Disable — toggle a plugin on or off. Disabled plugins remain installed but their instruments are unavailable until re-enabled.
  • Version info — the currently installed version number.
  • Instrument count — how many instruments this plugin provides.
  • Update badge — a visual indicator when a newer version is available in the marketplace. Click to update.
  • Uninstall — remove the plugin and all its instruments entirely.

When an update badge appears, clicking it downloads and applies the newest version. The plugin's instruments are temporarily unavailable during the update and return once complete.

The Installed tab also includes a Browse More link that navigates to the Browse tab for discovering additional plugins.

Plugin Configuration

Some plugins define configuration options using a JSON Schema. When a plugin has a config schema, a configuration form becomes available. This form is accessed from the Installed tab (via a configure action on the plugin) or from an instrument's detail panel.

The form is automatically generated from the plugin's JSON Schema definition — fields, types, labels, and validation rules are all driven by the schema with no manual form definition required. The schema defines what settings are available, their types (string, number, boolean, etc.), default values, and any constraints.

Configuration changes are saved immediately and take effect without restarting Hefty.

Instrument Timeouts

Every instrument has an execution timeout — the maximum time Hefty will wait for an instrument to complete before canceling it. Administrators can view and override these timeouts through the instrument detail panel.

Three timeout values are shown:

  • Default timeout — the hardcoded default value defined by the instrument's implementation.
  • Effective timeout — the actual timeout in use after any overrides are applied. This is what Hefty enforces.
  • Override — an editable field where admin users can set a custom timeout value, overriding the default for this specific instrument.

To change a timeout, open the instrument's detail panel, locate the timeout table, and edit the override value. Clear the override to revert to the default.