Creating Plugins

A Cyberstrike plugin is a module that exports a function returning a set of hooks. This guide covers writing, registering, and publishing one.

Write a Plugin

A plugin is (input: PluginInput) => Promise<Hooks>. Import the types from @cyberstrike-io/plugin:

import type { Plugin } from "@cyberstrike-io/plugin"

export const GuardPlugin: Plugin = async ({ project, directory, $ }) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "bash" && /rm\s+-rf/.test(output.args.command)) {
        throw new Error("blocked: rm -rf")
      }
    },
    "permission.ask": async (input, output) => {
      if (input.type === "read") output.status = "allow"
    },
  }
}

The function’s input gives you context — client, project, directory, worktree, serverUrl, and $ (a Bun shell). Return an object whose keys are hook names; see the hook reference for every hook and its signature.

Register a Plugin

There are two ways to load a plugin.

1. Local file (no publishing)

Drop a .ts/.js file into a plugin/ (or plugins/) directory inside any .cyberstrike/ folder — project or ~/.cyberstrike/:

.cyberstrike/
└── plugin/
    └── guard.ts

Cyberstrike discovers it automatically and installs @cyberstrike-io/plugin for you so local plugins can import the types.

2. The plugin config array

Reference an npm package or a path in the plugin array (values are union-merged across config sources):

{
  "plugin": [
    "@myorg/cyberstrike-guard",
    "./local/guard.ts"
  ]
}

Test & Debug

Run Cyberstrike with debug logging to see plugins load and hooks fire:

cyberstrike --log-level DEBUG --print-logs

(Or set "logLevel": "DEBUG" in your config.)

Since hooks mutate output (or throw), you can unit-test them by calling the hook with a fake input/output and asserting on the mutated output.

Publish

Package your plugin like any npm module and publish it, then have users add it to their plugin array:

{
  "name": "@myorg/cyberstrike-guard",
  "type": "module",
  "main": "./index.ts",
  "peerDependencies": { "@cyberstrike-io/plugin": "*" }
}

npm publish --access public

Related Documentation

• Hooks Overview - Concepts and examples
• Plugin Hooks - Full hook reference
• Configuration - The plugin config key