Plugins - Clatter Labs Docs

A plugin is a folder with a plugin.json. It can add tools the agent calls, slash commands, hooks that run around tool calls, and skills. Anyone can write one; nothing is compiled into Line.

Text

~/.line/plugins/<name>/          yours, every project
<project>/.line/plugins/<name>/  shipped with a repo

Trust model

Plugins run programs with your permissions. Line keeps them off until you say otherwise.

A plugin never runs until you enable it (line plugin enable <name> or /plugins enable <name>). Enabling shows every program it can run.
Enabling records a fingerprint of all the plugin's files. If any file changes, the plugin is disabled until you review and enable it again. A cloned repo can't run code just by shipping .line/plugins.
Plugin tools ask for approval like shell commands, unless the manifest marks them "read_only": true.
Programs run in the project folder, without a shell (argv), with Line's credentials removed from the environment.

Manifest

plugin.json

{
  "name": "guard",
  "version": "0.1.0",
  "description": "What it does",
  "tools": [{
    "name": "deps",
    "description": "Shown to the model",
    "parameters": { "type": "object", "properties": { "path": { "type": "string" } } },
    "read_only": true,
    "timeout_secs": 30,
    "command_unix": ["sh", "${PLUGIN_DIR}/tools/deps.sh"],
    "command_windows": ["powershell", "-NoProfile", "-File", "${PLUGIN_DIR}/tools/deps.ps1"]
  }],
  "commands": [
    { "name": "audit", "description": "…", "prompt": "Review the dependencies. {{args}}" },
    { "name": "status", "description": "…", "run": ["git", "log", "--oneline", "-5"] }
  ],
  "hooks": {
    "session_start": [["sh", "${PLUGIN_DIR}/hooks/context.sh"]],
    "pre_tool": [["sh", "${PLUGIN_DIR}/hooks/block.sh"]],
    "post_tool": [],
    "turn_end": []
  },
  "skills": "skills"
}

toolsobject[]

Exposed to the model as <plugin>__<tool>. Arguments arrive as JSON on stdin; stdout is the result; a non-zero exit is reported as a failure. Environment: LINE_PROJECT_DIR, LINE_PLUGIN_DIR, LINE_TOOL. Use command (all systems) or command_unix / command_windows: an argv array, or a string run by sh -c / PowerShell.

commandsobject[]

Run as /<plugin>:<command> [args] (or /<command> when no other plugin uses the name). prompt sends a prompt to the agent ({{args}} is what you typed after it); run executes a program and shows its output.

hooksobject

Each hook gets a JSON payload on stdin. pre_tool ({"tool", "arguments"}): exit code 2 blocks the call and stdout is the reason given to the model. post_tool ({"tool", "arguments", "ok", "summary"}) and turn_end observe. session_start runs at the start of each turn; its stdout (up to 4 KB) is added to the agent's context. Hooks time out after 15 seconds.

skillsstring

A folder of skills that are available while the plugin is enabled.

Commands

Terminal

line plugin new <name> [--project]                 # scaffold (enabled: you wrote it)
line plugin install <folder | owner/repo[/path]>   # copy into ~/.line/plugins (disabled)
line plugin info <name>
line plugin enable|disable <name>
line plugin remove <name>
line plugin list

In the TUI: /plugins, /plugins enable|disable <name>, /plugins reload.