npm package: @genzai/claude
Description: Claude Code integration for Genzai - hooks for protecting generated files with slot-based editing
Latest version: 0.3.1

# @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

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

## Usage

Use the `claudeIntegration` generator in your code generation:

```typescript
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:

```typescript
/**
 * @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:

```typescript
// 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`

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

### `.claude/genzai.json` (if instructions provided)

```json
{
  "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