ai-tools

Universal configuration and runtime engine for AI coding tools. Define once — works everywhere.

ai-tools is a monorepo of engines that manage hooks, MCP servers, agents, skills, and rules across 13 AI coding tools. Write your configuration once and adapters translate it into the native format each tool expects.

Why

Every AI coding tool has its own format for hooks, MCP servers, agents, skills, and rules. If you use more than one tool — or your team does — you're maintaining the same configuration in multiple places.

ai-tools lets you define each configuration surface once. Adapters translate it into the native format for every tool you use: Claude Code, Cursor, Copilot, Gemini CLI, and 9 others.

Five engines — one for each configuration surface — plus a unified CLI that orchestrates them all.

On top of those engines, ai-tools can now act as a portable plugin authoring layer. Instead of hand-authoring separate Cursor plugins, Codex plugins, OpenCode prompts, and Claude-specific MCP config, you can define one capability bundle and let ai-tools map it onto the hosts you actually have installed.

graph TD
    CLI["<b>ai-tools</b><br/>unified CLI"]

    CLI --> Hooks["<b>ai-hooks</b><br/>guardrails &amp; audit"]
    CLI --> MCP["<b>ai-mcp</b><br/>MCP servers"]
    CLI --> Agents["<b>ai-agents</b><br/>agent personas"]
    CLI --> Skills["<b>ai-skills</b><br/>slash commands"]
    CLI --> Rules["<b>ai-rules</b><br/>project rules"]

    subgraph tools ["13 AI coding tools"]
        CC["Claude Code"]
        Codex["Codex CLI"]
        Gemini["Gemini CLI"]
        Cursor["Cursor"]
        Kiro["Kiro"]
        OC["OpenCode"]
        Cline["Cline"]
        Amp["Amp"]
        Droid["Factory Droid"]
        Copilot["VS Code / Copilot"]
        Continue["Continue"]
        Roo["Roo Code"]
        Windsurf["Windsurf"]
    end

    Hooks --> tools
    MCP --> tools
    Agents --> tools
    Skills --> tools
    Rules --> tools

    style CLI fill:#7c3aed,color:#fff,stroke:none
    style Hooks fill:#2563eb,color:#fff,stroke:none
    style MCP fill:#2563eb,color:#fff,stroke:none
    style Agents fill:#2563eb,color:#fff,stroke:none
    style Skills fill:#2563eb,color:#fff,stroke:none
    style Rules fill:#2563eb,color:#fff,stroke:none
    style tools fill:#f0fdf4,stroke:#16a34a

Packages

Package	CLI	Description
`agentful`	`agentful`	Zero-friction wrapper for `npx agentful`
`@premierstudio/ai-tools`	`ai-tools`	Unified CLI — routes to all engines
`@premierstudio/ai-hooks`	`ai-hooks`	Hook engine — guardrails, audit trails, runtime control
`@premierstudio/ai-mcp`	`ai-mcp`	MCP server configuration management
`@premierstudio/ai-agents`	`ai-agents`	Agent persona definitions
`@premierstudio/ai-skills`	`ai-skills`	Slash commands and prompt templates
`@premierstudio/ai-rules`	`ai-rules`	Project rules with scoping and priority

Supported tools

Tool	Hooks	MCP	Agents	Skills	Rules
Claude Code	✓	✓	✓	✓	✓
Codex CLI	✓	✓		✓	✓
Gemini CLI	✓	✓	✓	✓	✓
Cursor	✓	✓	✓	✓	✓
Kiro	✓	✓	✓	✓	✓
OpenCode	✓	✓	✓	✓	✓
Cline	✓	✓	✓	✓	✓
Amp		✓		✓	✓
Factory Droid	✓	✓	✓	✓	✓
VS Code / Copilot	*	✓	✓	✓	✓
Continue				✓	✓
Roo Code		✓	✓	✓	✓
Windsurf		✓		✓	✓

_{* VS Code 1.109+ agent hooks use the Claude Code format — the Claude Code adapter output works directly.}

Quick start

Unified CLI

# Run instantly (recommended)
npx agentful@latest detect

# Install everything
npm i -D @premierstudio/ai-tools

# Detect installed tools, generate configs, install them
ai-tools detect
ai-tools hooks generate && ai-tools hooks install
ai-tools mcp generate && ai-tools mcp install
ai-tools skills generate && ai-tools skills install
ai-tools agents generate && ai-tools agents install
ai-tools rules generate && ai-tools rules install

# Portable plugin bundles
ai-tools plugins init
ai-tools plugins detect
ai-tools plugins plan --tools=cursor,codex,opencode,claude-desktop
ai-tools plugins install --tools=cursor,codex,opencode

Portable plugin bundles

ai-tools now supports a plugin-style authoring model for cross-tool distribution.

Use definePlugin() from @premierstudio/ai-tools to describe a capability bundle once:

MCP servers
skills
rules
agents
hooks

Then use ai-tools plugins plan to see what each target host can actually consume, and ai-tools plugins install to deploy supported surfaces into the detected tools on the current machine.

Example:

// ai-plugin.config.ts
import { definePlugin } from "@premierstudio/ai-tools";

export default definePlugin({
  id: "cert-coach",
  name: "Certification Coach",
  version: "0.1.0",
  targets: {
    include: ["cursor", "codex", "opencode", "claude-code", "claude-desktop"],
  },
  mcpServers: [
    {
      id: "cert-coach",
      name: "Certification Coach",
      transport: {
        type: "stdio",
        command: "npx",
        args: ["cert-coach-mcp"],
      },
    },
  ],
  skills: [
    {
      id: "study-start",
      name: "Study Start",
      description: "Kick off a study session using the certification coach MCP.",
      content: "Start or resume a study session before answering study requests.",
    },
  ],
});

This is intentionally capability-aware rather than pretending every host has the same extension surface.

Cursor can consume a broad plugin bundle and supports interactive MCP Apps.
Codex can bundle skills, MCP, hooks, and app integrations.
OpenCode supports MCP plus a native plugin system across terminal, desktop, and IDE surfaces.
Claude Desktop is currently MCP-first in ai-tools; rich interactive experiences there come through desktop extensions and remote interactive connectors rather than rules or skills.

Optional convenience installers via agentful.sh:

# macOS / Linux
curl -fsSL https://agentful.sh/install | sh

# Windows PowerShell
irm https://agentful.sh/install.ps1 | iex

Or install individual engines

# Just hooks
npm i -D @premierstudio/ai-hooks
npx ai-hooks init
npx ai-hooks detect --verbose
npx ai-hooks generate
npx ai-hooks install

# Just MCP servers
npm i -D @premierstudio/ai-mcp
npx ai-mcp init
npx ai-mcp generate
npx ai-mcp install

# Just rules
npm i -D @premierstudio/ai-rules
npx ai-rules init
npx ai-rules generate
npx ai-rules install

Each engine follows the same CLI pattern: init → detect → generate → install. Use import or sync to pull existing tool-specific configs back into the universal format.

Config examples

Hooks

// ai-hooks.config.ts
import { defineConfig, hook, builtinHooks } from "@premierstudio/ai-hooks";

export default defineConfig({
  extends: [{ hooks: builtinHooks }],
  hooks: [
    hook("before", ["shell:before"], async (ctx, next) => {
      if (ctx.event.command.includes("npm publish")) {
        ctx.results.push({ blocked: true, reason: "Publishing is restricted" });
        return;
      }
      await next();
    })
      .id("org:block-publish")
      .name("Block npm publish")
      .priority(10)
      .build(),
  ],
  settings: {
    hookTimeout: 5000,
    failMode: "open",
    logLevel: "warn",
  },
});

MCP servers

// ai-mcp.config.ts
import { defineConfig } from "@premierstudio/ai-mcp";

export default defineConfig({
  servers: [
    {
      name: "filesystem",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "./src"],
      transport: "stdio",
    },
  ],
});

Rules

// ai-rules.config.ts
import { defineRulesConfig } from "@premierstudio/ai-rules";

export default defineRulesConfig({
  rules: [
    {
      name: "typescript-strict",
      content: "Always use strict TypeScript. No `any` types.",
      scope: "always",
      priority: 1,
    },
    {
      name: "test-conventions",
      content: "Co-locate tests as *.test.ts next to source files.",
      scope: "glob",
      globs: ["**/*.test.ts"],
    },
  ],
});

Hooks engine

The hooks engine is the most powerful package — an Express.js-style middleware chain for AI tool actions.

Universal event model

15 event types across the full AI tool lifecycle:

Category	Before (blockable)	After (observe-only)
Session	`session:start`	`session:end`
Prompt	`prompt:submit`	`prompt:response`
Tool	`tool:before`	`tool:after`
File	`file:read`, `file:write`, `file:edit`, `file:delete`
Shell	`shell:before`	`shell:after`
MCP	`mcp:before`	`mcp:after`
System		`notification`

Built-in safety hooks

Hook	Phase	What it does
`block-dangerous-commands`	before	Blocks `rm -rf /`, `DROP DATABASE`, fork bombs
`scan-secrets`	before	Detects API keys, tokens, private keys in file writes
`protect-sensitive-files`	before	Prevents writes to `.env`, `credentials.json`, SSH keys
`audit-shell`	after	Records command, exit code, duration, tool name

Using as a library

Import the engine directly for building platforms that orchestrate AI agents:

import { HookEngine, builtinHooks } from "@premierstudio/ai-hooks";

const engine = new HookEngine({
  hooks: builtinHooks,
  settings: { failMode: "closed" },
});

const result = await engine.isBlocked(event, { name: "my-platform", version: "1.0" });
if (result.blocked) {
  console.log(`Blocked: ${result.reason}`);
}

Development

git clone https://github.com/PremierStudio/ai-hooks.git
cd ai-tools
npm install
npm run check   # lint + format + typecheck + test

Command	What it does
`npm run check`	Full verification: lint + format + typecheck + test
`npm run build`	Build all packages via Turborepo
`npm test`	Run all tests (vitest)
`npx vitest run packages/hooks`	Test a single package
`npm run lint`	oxlint
`npm run fmt`	oxfmt (auto-format)
`npm run typecheck`	tsc across all packages

See CONTRIBUTING.md for adding adapters and submitting PRs.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.claude		.claude
.cline/prompts		.cline/prompts
.clinerules		.clinerules
.codex		.codex
.cursor		.cursor
.factory		.factory
.gemini		.gemini
.github/workflows		.github/workflows
.opencode		.opencode
packages		packages
scripts		scripts
.gitignore		.gitignore
.oxfmtrc.json		.oxfmtrc.json
.oxlintrc.json		.oxlintrc.json
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
ai-hooks.config.ts		ai-hooks.config.ts
ai-rules.config.ts		ai-rules.config.ts
ai-skills.config.ts		ai-skills.config.ts
package-lock.json		package-lock.json
package.json		package.json
tsconfig.base.json		tsconfig.base.json
turbo.json		turbo.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ai-tools

Why

Packages

Supported tools

Quick start

Unified CLI

Portable plugin bundles

Or install individual engines

Config examples

Hooks

MCP servers

Rules

Hooks engine

Universal event model

Built-in safety hooks

Using as a library

Development

License

About

Uh oh!

Releases 7

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

ai-tools

Why

Packages

Supported tools

Quick start

Unified CLI

Portable plugin bundles

Or install individual engines

Config examples

Hooks

MCP servers

Rules

Hooks engine

Universal event model

Built-in safety hooks

Using as a library

Development

License

About

Topics

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages