Skip to content
FilerFiler Developers

Hooks and events

A hook is a handler your plugin runs when something happens in the app — a session starting, a file being indexed, an agent turn finishing. Unlike a tool, nothing calls a hook on purpose; the app fires it as a side effect of something else happening.

Declaring a hook

Section titled “Declaring a hook”
"hooks": {
  "onAgentComplete": "./hooks/on-complete.js",
  "onFileMemorized": {
    "handler": "./hooks/on-memorized.js",
    "filter": { "extensions": [".md"] }
  }
}

A hook value is either a plain handler path, or an object with handler plus a filter that narrows which occurrences of the event actually invoke it — onFileMemorized above only fires for Markdown files. The only filter is extensions, and it applies to events whose payload carries a path (onFileMemorized); on an event without path the filter matches everything.

Every handler has the same signature: (event, ctx). The event object is passed through unmodified — whatever shape is documented below is exactly what your handler receives.

Hooks are not available under runtime: "process" — see Process runtime.

Events

Section titled “Events”
  • onRuntimeReady {} — the plugin runtime has loaded your plugin and its settings are readable; start polling loops and listeners here. It fires in the background service, with or without the app window.
  • onAppReady {} — the app window has finished starting up. Only for a hook that needs the window.
  • onSessionStart { sessionId, channelId } — a chat session began.
  • onAgentComplete { sessionId, channelId, result: string | null, duration, outcome, reason } — a chat turn or a folder’s run finished. outcome is completed, unfulfilled (it ended without doing everything asked) or failed; reason is Filer’s sentence for why when it is not completed.
  • onToolCall { toolId, params, result, success } — a tool call completed during a turn.
  • onFileMemorized { path } — a file was indexed into the folder’s knowledge base; supports the extensions filter shown above.
  • onPluginSettingsChanged { key, oldValue, newValue } — a plugin setting was saved from the app’s settings UI. Delivered to every plugin’s handler, whichever plugin’s setting changed, so check that key starts with your own prefix. oldValue is always null; newValue is the saved value, or null for a secret setting (read it with ctx.settings.get). A handler’s own ctx.settings.set does not fire it. A listener you started in onRuntimeReady from settings — a polling switch, a token, an account — restarts here when one of those keys changes; otherwise the change waits for the next start of Filer.
  • onFileChangeNotify { agentId, channelId, folderPath, folderDisplayName, changes, summary, isDigest } — a summarized notification of file activity, potentially batched into a digest.
  • onSessionMessage { sessionId, channelId, result } — the reply to a conversation that came in on your plugin’s channel, raised to your plugin alone, with the reply’s text in result.
  • onChannelChanged { channelId, path, action: 'registered' | 'unregistered' } — an inbound channel was bound to or released from a folder.
  • onAgentHitlRequest { agentId, executionId, requestId, action, target, description, channelId } — the agent is asking for human-in-the-loop approval before proceeding.
  • onSessionEnd, onFileChange and onActionCreated are declared in the manifest schema but are never emitted. A handler registered for any of these validates cleanly and simply never runs. For file activity, use onFileMemorized (per indexed file) or onFileChangeNotify (the agent’s summarized digest).

The result trap in onAgentComplete / onSessionMessage

Section titled “The result trap in onAgentComplete / onSessionMessage”

result on both onAgentComplete and onSessionMessage is a plain string or null — never an object. If you write event.result?.summary expecting a structured result, you get undefined silently; there is no summary field, or any other field, to read off of it.

What it holds depends on where the turn came from:

  • A chat in the app’s own panel raises onAgentComplete with the reply’s text — its first 500 characters, followed by … when it is longer — and never onSessionMessage: a conversation at the person’s desk is not copied to a messenger unasked.
  • A folder’s run (a file change, a schedule, a manual start, a hand-off) raises onAgentComplete with what the run did, or null, and no onSessionMessage.
  • A conversation that came in on your plugin’s channel raises onSessionMessage to your plugin alone, always with the reply’s text in result — that is the hook a messaging plugin answers from.

A plugin that offers “send me every result” does it from onAgentComplete, and says what outcome says — never “done” for a turn that failed. There is no call that reads a whole conversation’s transcript.

Next

Section titled “Next”