Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shobcoder/shob/llms.txt

Use this file to discover all available pages before exploring further.

Shob plugins are npm packages that extend the capabilities of the Shob AI agent at runtime. A plugin can register custom tools the agent can call, add authentication flows for new AI providers, override LLM parameters, intercept and modify chat messages, and respond to any event the server emits. Plugins run server-side, inside the Shob process, giving them full access to the session state and project filesystem.

​
Installation

npm install @shob-ai/plugin
The @shob-ai/plugin package ships TypeScript source ("type": "module") and re-exports everything you need to author a plugin. It also exports a tool helper for defining type-safe custom tools.

​
Plugin module structure

A plugin is an ES module with a named export called server. The export must conform to the PluginModule interface: 
export type PluginModule = {
  id?: string        // Optional identifier for the plugin
  server: Plugin     // Required: the server-side plugin function
}

export type Plugin = (input: PluginInput, options?: PluginOptions) => Promise<Hooks>
FieldTypeDescription
idstring (optional)A stable identifier for this plugin. If omitted, Shob uses the package name.
serverPluginThe main plugin function called once per project when the server starts. It receives a PluginInput context and returns a Hooks object.

​
PluginInput

The input argument your plugin function receives:
​
client
OpencodeClient
A typed REST client already pointed at the running Shob server. Use it to inspect sessions, files, and configuration.
​
project
Project
The current project object from the Shob API.
​
directory
string
The absolute path to the project’s working directory.
​
worktree
string
The root of the project’s Git worktree. Useful for computing stable relative paths.
​
serverUrl
URL
The base URL of the running Shob server.
​
$
BunShell
A Bun shell instance scoped to the project directory. Use it to run commands as part of tool execution or hooks.
​
experimental_workspace
object
Experimental API for registering custom workspace adapters. Call register(type, adapter) to add a new workspace backend.

​
Registering a plugin in shob.json

Plugins are listed in your project’s shob.json under the "plugin" key. Each entry is either a package name or a two-element tuple [packageName, optionsObject]: 
{
  "plugin": [
    "my-shob-plugin",
    ["another-plugin", { "apiKey": "env:MY_API_KEY" }]
  ]
}
When Shob starts, it import()s each plugin module, calls the server function with the current project’s PluginInput and any options you provided, and merges the returned Hooks into the running server.

​
Minimal plugin example

// my-shob-plugin/src/index.ts
import type { PluginModule } from "@shob-ai/plugin"

export const server: PluginModule["server"] = async (input, options) => {
  console.log("Plugin loaded for project:", input.directory)

  return {
    // Add hooks here — see /plugins/hooks
    // Add custom tools here — see /plugins/tools
  }
}
After publishing (or npm link-ing) the package, register it: 
{
  "plugin": ["my-shob-plugin"]
}

​
What plugins can add

CapabilityHow
Custom toolsReturn a tool map from the Hooks object. The AI agent can call these like any built-in tool.
Authentication methodsReturn an auth hook with provider and methods to add API-key or OAuth flows.
Provider overridesReturn a provider hook to add or modify models for an existing provider.
Event handlersReturn an event hook to react to any server-emitted event.
LLM parameter tuningReturn a chat.params hook to adjust temperature, topP, maxTokens, etc.
Header injectionReturn a chat.headers hook to add headers to LLM API calls.
Permission decisionsReturn a permission.ask hook to auto-allow, auto-deny, or customise permissions.
Shell environmentReturn a shell.env hook to inject environment variables.
Tool interceptionReturn tool.execute.before / tool.execute.after hooks to modify inputs or outputs.
System prompt controlReturn experimental.chat.system.transform to append or replace the system prompt.

​
Next steps

Hooks Reference

Full reference for every hook in the Hooks interface, with input/output types and examples.

Custom Tools

How to define custom tools with ToolDefinition and make them available to the AI agent.

Build docs developers (and LLMs) love

Get started for freeTalk to us