The big idea

i answer this: explain how the plugin system is built. i can see devs can create plugins using any programming laguage . be detailed

i got this: Wiki pages you might want to explore: https://deepwiki.com/ogulcancelik/herdr/6-socket-api-and-cli

explain is simple terms in details

In simple terms, Herdr’s plugin system is built around external programs, not around libraries or code that runs inside Herdr itself. This is why developers can write plugins in any programming language (Python, Go, Rust, Node.js, Bash, C#, etc.). (Herdr)

Here’s how it works.

The big idea

Instead of saying:

“Write your plugin using our JavaScript API.”

Herdr says:

“Write any executable program. We’ll launch it when needed.”

Think of Herdr as a manager.

It doesn’t care how your program was written.

It only cares that it can run the executable.

For example:

Herdr
   │
   ├── Python plugin
   ├── Rust plugin
   ├── Go plugin
   ├── Bash script
   └── Node.js app

Every plugin is simply a program Herdr knows how to start.

What tells Herdr about the plugin?

Every plugin contains a file called

herdr-plugin.toml

This is the manifest.

Think of it like an app’s information sheet.

It tells Herdr things such as:

• plugin name
• plugin ID
• minimum Herdr version
• supported operating systems
• what commands to run
• available actions
• event hooks
• terminal panes

Herdr reads this file instead of reading your source code. (Herdr)

What happens when you install a plugin?

Suppose you run:

herdr plugin install my/plugin

Herdr does roughly this:

Download plugin

↓

Find herdr-plugin.toml

↓

Read plugin information

↓

Save plugin in plugin registry

↓

Plugin is ready

Notice something important:

Herdr does not compile your code or load it into its own process.

It only records:

“This plugin exists, and here’s how to run it.”

When the plugin runs

Suppose the plugin has an action called:

Format Project

When the user clicks it:

User

↓

Herdr

↓

Reads manifest

↓

Launches executable

↓

Waits for result

If the executable is

python formatter.py

Herdr simply launches Python.

If it is

cargo run

Herdr launches Rust.

If it is

./plugin

Herdr runs that executable.

That’s why any language works.

How does the plugin communicate with Herdr?

This is the clever part.

Herdr starts the plugin and provides it with several environment variables, such as:

HERDR_SOCKET_PATH

HERDR_PLUGIN_ID

HERDR_WORKSPACE_ID

HERDR_TAB_ID

HERDR_PANE_ID

HERDR_PLUGIN_STATE_DIR

HERDR_PLUGIN_CONFIG_DIR

These tell the plugin things like:

• which workspace is active
• which pane launched it
• where to store configuration
• how to talk back to Herdr

The plugin reads these environment variables just like any normal program. (Herdr)

The Socket API

The most important environment variable is

HERDR_SOCKET_PATH

This points to a local socket.

Think of a socket as a private communication channel between two programs running on the same computer.

Plugin
    │
    │ JSON messages
    │
Socket
    │
    │
Herdr

Instead of calling library functions, the plugin sends JSON requests over this socket. (Herdr)

Example

Suppose the plugin wants to create a new tab.

It sends something like:

{
  "id": "1",
  "method": "tab.create",
  "params": {
    "label": "Tests"
  }
}

Herdr receives it.

Creates the tab.

Replies:

{
  "id": "1",
  "result": {
    "type": "tab"
  }
}

This is standard request/response communication.

Why use sockets?

If Herdr exposed only a Rust API:

• Rust plugins would work.
• Python wouldn’t.
• Go wouldn’t.
• Bash wouldn’t.

With sockets:

Python
    │

Go
    │

Rust
    │

Node
    │

Anything

↓

JSON

↓

Socket

↓

Herdr

Everyone speaks the same language: JSON messages. (Herdr)

Event hooks

Plugins can also react to events.

Example:

Workspace created

↓

Herdr

↓

Plugin runs

or

Agent finished

↓

Herdr

↓

Plugin runs

The manifest lists which events the plugin wants to receive.

When an event occurs, Herdr launches the corresponding command and passes event information (such as the event name and JSON payload) through environment variables. (Herdr)

Plugin actions

A plugin can expose actions like:

Build project

Run tests

Deploy

Open logs

When the user selects an action:

Click action

↓

Herdr

↓

Starts executable

↓

Executable does work

↓

Uses socket if needed

The actions are defined in the manifest, not registered dynamically while the plugin is running. (Herdr)

Plugin storage

Herdr does not manage a plugin’s data.

Instead, it tells the plugin:

Store your files here:

HERDR_PLUGIN_CONFIG_DIR

HERDR_PLUGIN_STATE_DIR

The plugin decides:

• file names
• JSON format
• databases
• migrations
• cleanup

This gives plugin authors complete control over their own data. (Herdr)

Why this design is good

This architecture has several advantages:

• Language-independent: Developers can use Python, Go, Rust, JavaScript, Bash, or any language that can run as an executable.
• Isolation: Plugins run as separate processes, so a crash in a plugin is less likely to crash Herdr itself.
• Simple integration: Communication uses standard JSON over a local socket, making it easy to implement in any language.
• Flexible: Plugins can define actions, respond to events, open managed terminal panes, and store their own state without needing language-specific SDKs. (Herdr)

Overall architecture

               User
                 │
                 ▼
              Herdr
                 │
        Reads herdr-plugin.toml
                 │
     Starts plugin executable
                 │
     Passes environment variables
                 │
      (HERDR_SOCKET_PATH, etc.)
                 │
                 ▼
   Python / Rust / Go / Bash Plugin
                 │
      Sends JSON requests
                 │
            Local Socket
                 │
                 ▼
              Herdr API
                 │
      Create panes, tabs, workspaces,
      react to events, run actions, etc.

In one sentence: Herdr’s plugin system is essentially a manifest-driven process launcher. The manifest tells Herdr what executable to run, Herdr launches that program with useful environment variables, and the program communicates back using JSON over a local socket API. Because the communication happens through this language-neutral protocol rather than an in-process SDK, developers are free to build plugins in virtually any programming language.