Fabriczero Openclaw

Name: Fabriczero Openclaw
Rating: 3.5 (1 reviews)
Author: richjorme

By richjorme 👁 33 views ▲ 0 votes

FabricZero governance plugin for Claude Code / OpenClaw

GitHub

Install

npm install fabriczero-openclaw-plugin

README

# FabricZero OpenClaw Plugin

[![CI](https://github.com/richjorme/fabriczero-openclaw-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/richjorme/fabriczero-openclaw-plugin/actions/workflows/ci.yml)
[![npm version](https://badge.fury.io/js/fabriczero-openclaw-plugin.svg)](https://www.npmjs.com/package/fabriczero-openclaw-plugin)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Constitutional AI governance for Claude Code and OpenClaw agents.

## Features

- **Local Mode**: Run governance checks locally with embedded gateway binary
- **Cloud Mode**: Connect to FabricZero cloud for advanced governance
- **Hybrid Mode**: Local fast-path with cloud dialectic escalation
- **PreToolUse Hooks**: Governance check before tool execution
- **PostToolUse Hooks**: Audit logging after execution
- **Zero Config**: Works out of the box with sensible defaults

## Installation

```bash
npm install fabriczero-openclaw-plugin
```

## Quick Start

Add FabricZero hooks to your Claude Code configuration:

```typescript
// .claude/hooks.ts
import { fabriczeroPreToolUse, fabriczeroPostToolUse } from 'fabriczero-openclaw-plugin';

export default {
  preToolUse: [fabriczeroPreToolUse],
  postToolUse: [fabriczeroPostToolUse],
};
```

That's it! The plugin will automatically:
1. Download and cache the gateway binary on first use
2. Start a local gateway for governance evaluation
3. Check each tool invocation against governance policies
4. Log all actions for audit

## Configuration

### Basic Configuration

Create `fabriczero.config.ts` in your project root:

```typescript
import type { FabricZeroConfig } from 'fabriczero-openclaw-plugin';

const config: FabricZeroConfig = {
  // Operating mode: 'local' | 'cloud' | 'hybrid'
  mode: 'local',

  // Agent identifier
  agentId: 'my-claude-code-agent',

  // Request timeout in milliseconds
  timeout: 30000,

  // Behavior when governance is unavailable: 'open' | 'closed'
  failBehavior: 'closed',
};

export default config;
```

### Local Mode Configuration

```typescript
const config: FabricZeroConfig = {
  mode: 'local',
  local: {
    port: 8766,
    host: '127.0.0.1',
    policyPath: './policies/my-policy.yaml',
    autoStart: true,
    binaryVersion: 'v0.1.0',
  },
};
```

### Cloud Mode Configuration

```typescript
const config: FabricZeroConfig = {
  mode: 'cloud',
  cloud: {
    apiUrl: 'https://api.fabriczero.ai',
    // API key from environment variable
    apiKeyEnv: 'FABRICZERO_API_KEY',
    organizationId: 'org-123',
  },
};
```

### Hybrid Mode Configuration

```typescript
const config: FabricZeroConfig = {
  mode: 'hybrid',
  local: {
    port: 8766,
  },
  cloud: {
    apiUrl: 'https://api.fabriczero.ai',
  },
  // Tool-specific overrides
  toolOverrides: [
    // Send Bash commands to cloud for dialectic review
    { pattern: 'Bash', mode: 'cloud', tier: 'dialectic' },
    // Fast path for read operations
    { pattern: 'Read', tier: 'fast_path' },
  ],
};
```

## API Reference

### Hooks

#### `fabriczeroPreToolUse(context: PreToolUseContext): Promise<PreToolUseResult>`

Evaluates a tool invocation before execution.

```typescript
interface PreToolUseContext {
  toolName: string;
  toolInput: Record<string, unknown>;
  agentId?: string;
}

interface PreToolUseResult {
  proceed: boolean;
  reason?: string;
  decision?: EvaluateResponse;
  modifiedInput?: Record<string, unknown>;
  token?: string;
}
```

#### `fabriczeroPostToolUse(context: PostToolUseContext): Promise<PostToolUseResult>`

Logs tool execution for audit.

```typescript
interface PostToolUseContext {
  toolName: string;
  toolInput: Record<string, unknown>;
  toolOutput: unknown;
  agentId?: string;
}

interface PostToolUseResult {
  logged: boolean;
  error?: string;
}
```

### Client

#### `FabricZeroClient`

Direct client for governance evaluation.

```typescript
import { FabricZeroClient } from 'fabriczero-openclaw-plugin';

const client = new FabricZeroClient({
  localMode: true,
});

const decision = await client.evaluate({
  agentId: 'my-agent',
  agentType: 'claude-code',
  toolName: 'Bash',
  toolInput: { command: 'ls -la' },
});

if (decision.decision === 'approve') {
  // Execute tool
  await client.confirmExecution(decision.token!, 'success');
}

await client.close();
```

### Types

#### `Decision`

Governance decision outcome.

```typescript
type Decision = 'approve' | 'approve_with_constraints' | 'deny' | 'escalate';
```

#### `EvaluateResponse`

Full governance evaluation response.

```typescript
interface EvaluateResponse {
  requestId: string;
  decision: Decision;
  tier: string;
  reasoning?: string;
  constraints: Constraint[];
  token?: string;
  confidence?: number;
}
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `FABRICZERO_API_KEY` | API key for cloud mode | - |
| `FABRICZERO_DEBUG` | Enable debug logging | `0` |
| `FABRICZERO_FAIL_OPEN` | Allow actions when governance unavailable | `0` |

## Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type check
npm run typecheck

# Lint
npm run lint

# Build
npm run build
```

## Requirements

- Node.js >= 18.0.0
- macOS (arm64, x64), Linux (x64, arm64), or Windows (x64)

## License

MIT - See [LICENSE](LICENSE) for details.

tools