write-terva-extension

Writing a terva extension

Use this skill when the user asks for help building a terva extension — a new slash command, a new tool the LLM can call, an audit hook, or a permission gate. Skim this whole skill first, then collaborate with the user on the specific extension they want.

What an extension is

A terva extension is an external executable that terva launches as a subprocess and talks to over its stdin/stdout in newline-delimited JSON. It can be written in any language that can read/write JSON lines from stdio: Go, TypeScript (via tsx), Python, Rust, shell with jq, anything. Crash isolation is automatic; one bad extension never takes down terva.

Three things an extension can do (any combination):

1. Slash commands — register /foo so the user can run it from the input. The handler returns a "prompt" (submitted to the agent), an "insert" (text dropped into the editor), a "display" (one-shot styled note in the chat), or a "noop".

2. Tools — register tools the LLM itself calls. Schema is JSON Schema; terva routes the model's tool_call to the extension's tool_result. Same lifecycle as built-in tools (read/write/edit/bash/skill).

3. Lifecycle hooks — subscribe to events (session_start, turn_start, tool_call, turn_end, assistant_message) for telemetry / audit / custom UI, or intercept tool calls before execution to refuse dangerous patterns.

4. Model context & tool visibility — fold standing guidance into the system prompt (register_context / refresh_context) and hide tools that can't do anything useful in the current workspace (set_withdrawn_tools). These touch the model's cached prefix, so they carry a discipline — see "Being responsible with context & tools" below before reaching for them.

On-disk layout

Each extension lives in its own directory:

~/Library/Application Support/terva/extensions/<name>/
├── extension.json    # manifest (required)
└── <executable>      # whatever exec points at