Modules

A module is a small middleware that participates in one or more lifecycle hooks. Modules ship as npm packages that implement a tiny interface — six fields, four of them optional.

The interface


import type { Module } from '@prxy/module-sdk';
 
export const myModule: Module = {
  name: 'my-module',
  version: '1.0.0',
 
  async init(storage) {
    // optional: one-shot setup at server boot
  },
 
  async pre(ctx) {
    // optional: pre-request hook (mutate or short-circuit)
    return { continue: true };
  },
 
  async stream(chunk, ctx) {
    // optional: per-chunk hook for streaming responses
    return chunk;
  },
 
  async post(ctx) {
    // optional: post-response hook (side effects)
  },
};

Full SDK reference at /sdk/interface.

Module categories

Each built-in module fits one of seven categories. Knowing the category tells you roughly where it should sit in the pipeline:

Category	Purpose	Where in pipeline	Examples
`cache`	Skip the provider call	First	`exact-cache`, `semantic-cache`, `tool-cache`
`safety`	Block bad requests early	Early	`cost-guard`, `guardrails`, `airgap`
`optimization`	Reduce tokens sent	Mid	`mcp-optimizer`, `prompt-optimizer`
`context`	Manage messages array	Mid	`ipc`, `rehydrator`, `compaction-bridge`
`injection`	Add to prompt	Late	`patterns`
`routing`	Choose model/provider	Last pre hook	`router`
`tracking`	Log + bill + learn	Post hooks	`usage-tracker`

Built-in modules (v1)

These are implemented and ready today:

mcp-optimizer — embed tool descriptions, drop the irrelevant ones.
exact-cache — hash the canonical request, return identical responses.
semantic-cache — embed and search; return when similar enough.
patterns — inject learned patterns; forge new ones from outcomes.
cost-guard — per-request, per-day, per-month USD caps.
ipc — infinite context — compress old turns instead of dropping them.

Coming in v1.1

These are planned and have full reference pages, but aren’t shipping yet. Reading them now tells you what’s coming and how to plan for it:

router — smart model selection.
rehydrator — pull archived context back when relevant.
compaction-bridge — survive Claude Code auto-compaction.
prompt-optimizer — restructure prompts for max provider cache.
tool-cache — cache MCP tool result calls.
guardrails — PII redaction, profanity blocks, custom regex.

Cloud-only / local-only

Most modules work in both environments. A few have asymmetric capabilities:

Module	Cloud	Local	Notes
`cost-guard`	✅	⚠️	Local has no billing — module loads but caps fall back to `0` (always allow).
`usage-tracker`	✅ (auto-appended)	❌	No billing in local mode.
`airgap`	❌	✅ (v1.1)	Enforces no-network-out — incompatible with cloud sync.
`pattern-sync`	✅ (v1.1)	❌	Needs the cloud sync server.