Skip to content

About

Portable lifecycle hooks for coding-agent harnesses

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

533 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Hooknostic logo

Hooknostic

Portable hooks, skills, and MCP servers for coding agents. Build native plugins for Claude Code, Codex, and GitHub Copilot CLI, or maintain integrations directly in your repository.

Keep one portable source and let Hooknostic translate it for Claude Code, OpenAI Codex CLI, GitHub Copilot CLI, OpenCode, and Pi. Adapters handle native packaging, component configuration, project discovery, and lifecycle behavior. Before writing output, Hooknostic checks what each target can deliver and reports every compatibility shortfall.

Standards in, native integrations out

Agent Plugins 1.0 defines portable packages: a manifest, Agent Skills, MCP servers, and namespaced client extensions. Hooknostic validates that format and projects it into native harness artifacts. The source package stays unchanged. Portable TypeScript hooks can accompany it, or be used on their own; hooks are outside the standard's v1 portable component set.

Agent Plugins 1.0 package ─┐                 ┌─ Claude Code plugin → marketplace
TypeScript hooks ──────────┼─ check / build ─├─ Codex plugin       → marketplace
Direct skills / MCP ───────┘                 ├─ Copilot plugin     → marketplace or --plugin-dir
                                             ├─ OpenCode package or project artifact
                                             └─ Pi package or project artifact
                                  sync ──────── native repository wiring

The same source can contain hooks, skills, and MCP together, or only the components you need. Native outputs are ready for their harness's installation workflow. Authors still register their marketplace and list the built plugins; Hooknostic does not submit listings.

Choose your starting point

Requires Node.js ^22.22.2 || ^24.15.0 || >=26.0.0. Install the CLI and configuration/hook authoring SDK:

npm install --save-dev hooknostic @hooknostic/sdk

Authoring hooks and configuration needs no Zod. Only code that imports the runtime schemas from @hooknostic/sdk/schemas also needs zod@^4.6.7.

Your goal Workflow Start here
Distribute a plugin Author an Agent Plugins package, check, build, then install native output through a marketplace or package manager Combined package and marketplace tutorial
Maintain a repository Keep portable hooks, skills, and MCP; init --local, sync --dry-run, sync, then verify Repository integration
Write portable hooks Author one TypeScript entry and choose package or project delivery First hook walkthrough

build writes distributable artifacts. sync additionally maintains project discovery files and ownership records. Trust prompts, dependency installation, and activation remain explicit harness/user steps. Scope and contribution contract.

One package, multiple targets

portable/
├── plugin.json
├── skills/greet/SKILL.md
└── mcp.json
src/hooks.ts                 # optional
hooknostic.config.ts
import { defineConfig } from "@hooknostic/sdk";

export default defineConfig({
  entry: "./src/hooks.ts",
  components: { root: "./portable" },
  targets: {
    claude: { version: ">=2.1 <3", delivery: "package", output: "./dist/claude" },
    codex: { version: ">=0.153 <1", delivery: "package", output: "./dist/codex" },
    copilot: { version: ">=1.0.101 <2", delivery: "package", output: "./dist/copilot" },
    opencode: { version: ">=2.0.17 <3", delivery: "package", output: "./dist/opencode" },
    pi: { version: ">=1 <2", delivery: "package", output: "./dist/pi" },
  },
});

Omit entry for a hookless package. For direct repository sources, use components.skills / components.mcp and project delivery instead of a package root.

Pi 1.x receives the hooks, skills, and stdio and streamable-HTTP MCP servers, which a generated extension registers with pi's native MCP client. pi rejects the legacy SSE transport, so a package with an SSE server must accept pi:mcp-sse-omitted. A >=0.84 <1 target has no native MCP channel at all: there pi:mcp-stdio-omitted and pi:mcp-streamable-http-omitted accept the omissions, support remains unsupported, and the report records the skipped servers. Other unsupported components still fail. See component policies.

Skills may declare metadata: { hooknostic/allow-implicit-invocation: "false" } to require explicit user invocation across supported harness versions. Author them in skills/ and let Hooknostic own the native copies; missing gates fail unless the skill is omitted or the specific shortfall is explicitly accepted. See invocation policy for authoring and support checks. The existing combined example includes a bundled MCP server, so its generated packages run without workspace dependencies. OpenCode v1 remains available through an explicit version range; see version families.

Portable hooks

Coding agents expose different lifecycle events and different actions at those events. Hooknostic lets you express the hook once and declare which capabilities it needs:

// src/hooks.ts
import { definePlugin, hook, block, updateShell } from "@hooknostic/sdk";

export default definePlugin({
  name: "portable-repo-hooks",
  hooks: [
    hook("tool.before", {
      id: "protect-shell",
      match: { kind: "shell" },
      capabilities: { block: "required", "input.replace": "optional" },
      run({ tool }, ctx) {
        // Normalized across harnesses; undefined where the tool's shape is
        // uncaptured or the input does not match it -- and a guard refuses what
        // it cannot read.
        const command = tool.shell?.command;
        if (command === undefined) return block(`Unrecognized ${tool.nativeName} input`);
        if (command.includes("rm -rf /")) return block("Refusing destructive root deletion");
        if (ctx.capabilities.has("input.replace") && command.startsWith("npm ")) {
          // Lands under whichever key this harness uses, siblings preserved.
          return updateShell({ command: command.replace(/^npm /, "pnpm ") });
        }
      },
    }),
  ],
});

That one file blocks a destructive command on every supported harness, and rewrites npm to pnpm on the ones that support input rewriting — falling back gracefully (and visibly) where they don't. Capability keys are relative to the hook's event (block means tool.before.block), and a hook can return several effects at once ([notify(message), preventStop(reason)]). File tools get the same treatment as shell tools: tool.file?.paths lists every file a call targets, whatever each harness names the argument.

Commands at a glance

hooknostic init --local         # scaffold a repository integration
hooknostic check                # compile and validate without writing target artifacts
hooknostic build                # emit native artifacts and a build report
hooknostic sync --dry-run       # preview repository changes
hooknostic sync                 # reconcile owned project wiring
hooknostic verify               # detect integration drift
hooknostic doctor               # diagnose installed versions and activation
hooknostic --version            # print the CLI's version
hooknostic inspect codex --delivery package --component agent-plugin.mcp.stdio --config hooknostic.config.ts
hooknostic dispatch --target claude --events events.jsonl

build and sync are alternatives, not consecutive steps. In a repository integration, sync writes the same artifacts as build and also records their ownership, so use sync there. It refuses files that an earlier build left without an ownership record; move them aside first (project integration).

See the command reference. Trusted materializers may run during compilation, including check; review their network/cache behavior like other build code.

The idea in one paragraph

The central design rule: being told about an event and being allowed to act on it are two different things. A harness may fire a "before tool" event but differ in whether your code can block the call, ask the user for approval, rewrite the tool's input, or add context the model can see. Hooknostic models each of those actions as a named capability, and every adapter ships a versioned table of what its harness really supports — so differences are explicit and inspectable, never silently papered over by an optimistic translation layer.

Documentation

New here? Start with the documentation wiki — it has a plain-language tour of the concepts, two delivery workflows, and step-by-step tutorials built on the examples.

Repository

Node.js ^22.22.2 || ^24.15.0 || >=26.0.0 / pnpm 12 + TypeScript monorepo. Use the pnpm version pinned in package.json; compiler versions and compatibility constraints are documented in Dependencies:

Package Purpose
@hooknostic/sdk Public authoring API and canonical types; Zod runtime schemas at @hooknostic/sdk/schemas
@hooknostic/agent-plugin Public Agent Plugins 1.0 loader, schemas, and projection contracts
@hooknostic/core Compiler: config loading, plugin model, capability analysis, diagnostics
@hooknostic/runtime Dispatcher: decode events → run your handlers → apply effects
hooknostic CLI: compile, reconcile projects, inspect support, and test hooks
@hooknostic/adapter-{claude,codex,copilot,opencode,pi} Per-harness adapters (internal)
@hooknostic/testkit Fixtures, fake adapters, and the adapter contract suite
pnpm install
pnpm build      # typecheck + bundle runtime/CLI output
pnpm test       # vitest
pnpm lint

Support and status

Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode (v1 and v2 families), and Pi are each supported for package and project delivery. The generated support table is the authority: version ranges, the support level of every component, and the captured evidence behind each claim. This section flags only what is most likely to change a decision.

A weekly harness-watch workflow detects new harness releases on npm, runs the model-free playback suite against them, and records each pass in that table, so support tracks upstream releases rather than a one-time snapshot. A failure opens an issue instead.

macOS has unit and fixture coverage, but no real-harness playback evidence. Shell-interpreter captures exist there for every harness except Pi; end-to-end harness behavior is established on Windows and Linux.

Known limits worth reading before you rely on a harness:

  • Codex CLI: installed-plugin (package) hooks need a newer Codex than repository hooks, so package support has a narrower version range.
  • GitHub Copilot CLI: repository hooks load only in a trusted folder and from the directory the session starts in. Copilot also reads Claude Code's .claude/settings.json hooks and root .mcp.json, so Hooknostic keeps each harness on its own generated output when a project targets both (ADR-0033, installation).
  • OpenCode v2: context injection and stop behavior are approximate, and Code Mode MCP calls are not normalized to kind: "mcp". Read OpenCode families before relying on those capabilities.
  • Pi: has no permission event, so permission hooks are unsupported. Pi 1.x runs stdio and streamable-HTTP MCP servers through its native client and rejects SSE (details above, installation).

Release notes: release highlights.

The default compatibility minimum is emulated. Unsupported components and degraded items fail by default; known standard deviations warn and remain visible in the report. Use component policies to require exact behavior or accept a specific documented exception.

A note on trust: Hooknostic hook execution is not a sandbox or security boundary. Generated integrations preserve each harness's own trust and review mechanisms — Codex in particular requires project trust plus per-hook trust for repo-level hooks — and Hooknostic never modifies that trust state on your behalf.

And on scope: Hooknostic reports differences between harnesses rather than hiding them. Where a harness cannot do something, the answer is unsupported with a reason — never an emulation that quietly behaves differently. CONTRIBUTING.md states that boundary in full.

Contributing

Contributions are welcome, and the scope statement in CONTRIBUTING.md is written so you can tell whether an idea fits before writing any code. The short version: every claim about a harness needs captured evidence, docs and bug fixes can arrive as pull requests directly, and anything touching a harness claim or the portable vocabulary should start as an issue.

Adapter changes can be verified against the real harness binaries with no model credentials and no spend — see docs/testing.md.

Everyone participating is expected to follow the Code of Conduct.

Security

Hooknostic generates code that runs inside your agent's trust boundary. Please report vulnerabilities privately rather than in a public issue — SECURITY.md explains the reporting route and what is in scope.

License

Apache License 2.0.

About

Portable lifecycle hooks for coding-agent harnesses

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages