📝ai-tools-universal-engine.md

Building ai-tools: Universal Configuration for AI Coding Tools

The Problem

Every team working with AI coding assistants hits the same wall:

No unified policy layer. Each tool — Claude Code, Cursor, Codex — has its own format for hooks, MCP servers, rules, and agents. Your configuration gets duplicated, drifts, and breaks silently.
No external control plane. If you need to programmatically steer the AI client a developer is using — set boundaries, collect signals, enforce workflow rules — there's no standard way to do it.
Fragmented audit trails. Shell commands, file writes, and tool calls are logged in different formats per tool.
Inconsistent enforcement. Some tools can block dangerous actions before they happen; others can only observe after the fact.

I built ai-tools to solve this. It's a universal configuration engine with 5 sub-engines that work across every major AI coding tool.

What ai-tools Does

ai-tools gives you a single configuration layer for 5 surfaces:

Loading diagram...

Write your configuration once. Adapters translate it into the native format for each tool you use.

Five Engines

Package	CLI	What it does
`@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	Yes	Yes	Yes	Yes	Yes
Codex CLI	Yes	Yes	Yes	-	-
Gemini CLI	Yes	Yes	Yes	Yes	Yes
Cursor	Yes	Yes	Yes	Yes	Yes
Kiro	Yes	Yes	Yes	Yes	Yes
OpenCode	Yes	Yes	Yes	Yes	Yes
Cline	Yes	Yes	Yes	Yes	-
Amp	Yes	Yes	Yes	-	-
Factory Droid	Yes	Yes	Yes	Yes	Yes
VS Code / Copilot	*	Yes	Yes	Yes	Yes
Continue	Yes	Yes	-	-	-
Roo Code	Yes	Yes	Yes	Yes	-
Windsurf	Yes	Yes	Yes	-	-

*VS Code 1.109+ agent hooks use the Claude Code format.

Quick Start

# 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

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

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

Config Example

// 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",
  },
});

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}`);
}

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"],
    },
  ],
});

What's Next

More adapters for emerging tools
Event replay and auditing
Integration with more platforms

Links:

GitHub: https://github.com/PremierStudio/ai-tools
npm: @premierstudio/ai-tools