@genzai/claude

Claude Code integration for Genzai - protects generated files with slot-based editing.

Overview

This package provides a generator that creates Claude Code integration files:

1. Hook - Protects files with @regenerationStrategy overwrite, allowing edits only within slot boundaries
2. Configuration - Sets up .claude/settings.json and custom instructions

Installation

npm install @genzai/claude
# or
pnpm add @genzai/claude

Usage

Use the claudeIntegration generator in your code generation:

import { generate, file, folder, defaultMiddleware } from "@genzai/core";
import { slot, slotMiddleware } from "@genzai/slots";
import { claudeIntegration } from "@genzai/claude";

const appGenerator = () => [
  folder("src", [
    file("config.ts", () => `
export const config = {
  ${slot.begin("custom-config")}
  // Add your custom configuration here
  ${slot.end}
};
`),
  ]),
];

// Compose with Claude Code integration
const generator = () => [
  ...appGenerator(),
  ...claudeIntegration({
    instructions: "Generated files are in src/. Run `npm run generate` to regenerate.",
  }),
];

await generate(generator, "./output", {}, {
  middlewares: [...defaultMiddleware, slotMiddleware],
});

This generates:

output/
  src/
    config.ts           # Your generated file with slots
  .claude/
    hooks/
      genzai-hook.ts    # Pre-tool hook script
    settings.json       # Claude Code configuration
    genzai.json         # Custom instructions (if provided)

How It Works

File Protection

Files generated by Genzai (with defaultMiddleware) include metadata markers:

/**
 * @generated genzai
 * @regenerationStrategy overwrite
 * @slots custom-config
 */

When Claude Code tries to edit a file:

• preserve-edits: Edit allowed normally
• overwrite:
  • Edit allowed if within slot content (between @slot and @end-slot markers)
  • Edit blocked if outside slot boundaries or touching markers
• No marker: Edit allowed (not a generated file)

Slot Editing

Claude can directly edit content within slots using the standard Edit tool:

// This file has @regenerationStrategy overwrite
export const config = {
  /** @slot custom-config */
  timeout: 5000,        // <-- Claude can edit this line
  retryCount: 3,        // <-- Claude can edit this line
  /** @end-slot */

  generatedField: true, // <-- Claude CANNOT edit this line
};

API

claudeIntegration(options?)

Returns a generator that creates the Claude Code integration files.

Options:

• instructions (string, optional): Custom instructions shown when edits are blocked

Returns: Node[] - Array of nodes to be composed with other generators

Generated Files

.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsx .claude/hooks/genzai-hook.ts"
          }
        ]
      }
    ]
  }
}

.claude/genzai.json (if instructions provided)

{
  "instructions": "Generated files are in src/. Run `npm run generate` to regenerate."
}

Testing

After generating, test the integration:

1. Open Claude Code in the generated project
2. Try to edit content within a slot - should work
3. Try to edit generated code outside a slot - should be blocked
4. Try to edit the slot markers themselves - should be blocked

Related Packages

• @genzai/core - Core framework with regeneration strategy support
• @genzai/slots - Slot-based content preservation
• @genzai/templates - Template-based generation

License

MIT