ClaudeFlare

Why ClaudeFlare?

DuraClaw is a robust agent runtime. ClaudeFlare takes that foundation and bets hard on two things DuraClaw doesn't prioritize: Workers as disposable primitives and documentation as a first-class artifact.

Every task in ClaudeFlare is a Worker that exists only long enough to complete its job. No persistent processes. No cleanup. No lingering state. When it's done, it's gone. Simultaneously, every time a project layer ships, a corresponding CF Pages doc site auto-generates — architecture guides, deploy runbooks, API references — all living at predictable URLs under *.organizedai.vip.

               CLAUDEFLARE — THE TWO BETS

  ┌───────────────────────────────────────────────────────────┐
  │  BET 1: EPHEMERAL WORKERS                                 │
  │                                                           │
  │  task arrives → Worker spins up → executes → self-deletes │
  │                                                           │
  │  No warm processes. No idle billing. No cleanup debt.     │
  │  Each Worker is a single-use function, not a service.     │
  │                                                           │
  ├───────────────────────────────────────────────────────────┤
  │  BET 2: AUTO-DOCS ON CF PAGES                             │
  │                                                           │
  │  code ships → doc-engine reads layer config → generates   │
  │               HTML guide → deploys to CF Pages            │
  │                                                           │
  │  Every layer has a live URL. Docs never go stale.         │
  │  Architecture is always readable.                         │
  └───────────────────────────────────────────────────────────┘

One-Time-Use Workers

In ClaudeFlare, a Worker is not a service — it's a task envelope. It receives one job, runs it to completion, emits its outputs to a CF Queue or KV, and exits. CF's native scale-to-zero handles the rest. The Worker never waits for another job.

  EPHEMERAL WORKER LIFECYCLE

  ┌─────────────────────────────────────────────────────────────────┐
  │                                                                 │
  │  trigger (Queue / Cron / HTTP)                                  │
  │        │                                                        │
  │        ▼                                                        │
  │  ┌──────────────────────────────────────────────────┐          │
  │  │  flair-worker-[name]-[ulid]                      │          │
  │  │                                                  │          │
  │  │  1. hydrate context from KV / D1                 │          │
  │  │  2. execute single task                          │          │
  │  │  3. emit outputs → Queue | KV | R2               │          │
  │  │  4. log outcome → flair:outcomes:[session]       │          │
  │  │  5. return · CF scales to zero                   │          │
  │  │                                                  │          │
  │  └──────────────────────────────────────────────────┘          │
  │        │                                                        │
  │        ▼                                                        │
  │  next Worker in chain picks up from Queue                       │
  │                                                                 │
  └─────────────────────────────────────────────────────────────────┘

  NEVER:  a Worker that polls, loops, or waits
  ALWAYS: input → transform → output → exit

Dynamic Worker Dispatch

The flair-dispatcher Worker reads a task manifest from KV, spins up the right Worker via CF Queues, and wires up the output chain. No central process manages execution — each Worker is self-contained and independently deployable.

// packages/dispatcher/src/index.ts

export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const { task, payload } = await req.json();

    // Route task → queue → correct ephemeral Worker
    const queue = TASK_QUEUE_MAP[task];
    if (!queue) return new Response('unknown task', { status: 400 });

    await env[queue].send({
      task_id: ulid(),
      task,
      payload,
      dispatched_at: Date.now(),
    });

    return Response.json({ queued: true });
  }
};

// Every task maps to a dedicated CF Queue
const TASK_QUEUE_MAP = {
  'doc:generate':    'FLAIR_DOC_QUEUE',
  'layer:audit':     'FLAIR_AUDIT_QUEUE',
  'deploy:preview':  'FLAIR_DEPLOY_QUEUE',
  'worker:spawn':    'FLAIR_SPAWN_QUEUE',
};

Worker Conventions

Auto-Docs on CF Pages

Every ClaudeFlare project layer ships with a flair.layer.json manifest. The worker-doc-gen ephemeral Worker reads this manifest, calls Claude Sonnet to render an HTML architecture guide, and deploys it to Cloudflare Pages — automatically, on every layer change.

  AUTO-DOC PIPELINE

  flair.layer.json  ──▶  worker-doc-gen  ──▶  Claude Sonnet
  (layer manifest)        (ephemeral)          (HTML render)
                                                    │
                                                    ▼
                                           CF Pages deploy
                                           {project}-arch.pages.dev
                                           {project}-guide.pages.dev
                                           {project}-api.pages.dev

  TRIGGERS
  ─────────────────────────────────────────────────────
  • wrangler deploy of any layer   → doc-gen queue fires
  • manual: flair docs build       → all layers regenerate
  • git push to main               → CI triggers doc deploy

Layer Manifest

// flair.layer.json — every layer ships one of these
{
  "layer": "worker-analyzer",
  "project": "claudeflare",
  "version": "0.3.1",
  "description": "Pain point extraction via Claude + Gemma",
  "inputs": ["analyze-queue"],
  "outputs": ["score-queue"],
  "kv_keys": ["flair:weights:current", "flair:prompts:analyze"],
  "docs": {
    "arch_url": "https://flair-worker-analyzer-arch.pages.dev",
    "last_generated": "2026-04-14T03:00:00Z",
    "sections": ["overview", "queue-contract", "kv-schema", "deploy"]
  }
}

Doc Generation Worker

// apps/worker-doc-gen/src/index.ts

export default {
  async queue(batch: MessageBatch<DocGenTask>, env: Env) {
    for (const msg of batch.messages) {
      const { layer_manifest, project } = msg.body;

      // 1. Call Claude Sonnet to render HTML guide
      const html = await generateLayerDoc(env, layer_manifest);

      // 2. Write to R2 (source for CF Pages deploy)
      const key = `docs/${project}/${layer_manifest.layer}/index.html`;
      await env.FLAIR_DOCS_BUCKET.put(key, html, {
        httpMetadata: { contentType: 'text/html' }
      });

      // 3. Trigger CF Pages deploy via Workers API
      await deployToPages(env, project, layer_manifest.layer);

      msg.ack();
    }
  }
};

async function generateLayerDoc(env: Env, manifest: LayerManifest): Promise<string> {
  const res = await fetch(`${env.OPENCLAW_URL}/v1/messages`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-Codex-Token': env.OPENCLAW_CODEX_TOKEN },
    body: JSON.stringify({
      model: 'claude-sonnet-4-6',
      max_tokens: 4096,
      system: FLAIR_DOC_SYSTEM_PROMPT,  // loaded from KV
      messages: [{
        role: 'user',
        content: `Generate a complete architecture doc HTML page for this layer:\n${JSON.stringify(manifest, null, 2)}`
      }]
    })
  });
  const data = await res.json();
  return data.content[0].text;  // returns full HTML string
}

Doc URL Convention

Full System Diagram

                    CLAUDEFLARE — SYSTEM DIAGRAM

┌──────────────────────────────────────────────────────────────────────┐
│  OPERATOR / CI                                                       │
│  wrangler deploy · flair docs build · git push                      │
└──────────────────────────────┬───────────────────────────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │  flair-dispatcher   │  CF Worker (gateway)
                    │  reads task from    │  routes to Queue
                    │  HTTP / Cron / KV   │
                    └──────┬──────────────┘
                           │  CF Queues
         ┌─────────────────┼──────────────────────┐
         ▼                 ▼                      ▼
  ┌─────────────┐  ┌──────────────┐   ┌──────────────────┐
  │ worker-     │  │ worker-      │   │ worker-doc-gen   │
  │ task-[ulid] │  │ audit-[ulid] │   │ reads layer.json │
  │             │  │              │   │ calls Claude     │
  │  one task   │  │  one audit   │   │ deploys to Pages │
  │  then exit  │  │  then exit   │   │ then exit        │
  └──────┬──────┘  └──────┬───────┘   └────────┬─────────┘
         │                │                    │
         ▼                ▼                    ▼
  ┌──────────────────────────────────────────────────────┐
  │  CLOUDFLARE PLATFORM                                 │
  │                                                      │
  │  KV: flair:{project}:{key}    (config, weights)      │
  │  D1: flair-state              (task history, logs)   │
  │  R2: flair-artifacts          (JSONL, doc HTML)      │
  │  Queues: per-task-type        (ephemeral dispatch)   │
  │  Pages:  per-layer docs       (auto-generated)       │
  └──────────────────────────────────────────────────────┘
         │
         ▼
  claws-mac-mini (Tailscale 100.82.244.127)
  OpenClaw :18789  ←  ExoClaw CF Worker (bridge)
  NoClaw   :11434  ←  Gemma 3 27B (free inference)
  Hermes   :7700   ←  memory + context

ExoClaw Bridge

CF Workers can't reach Tailscale directly. ExoClaw is a single CF Worker that acts as a public-to-Tailscale bridge — it authenticates the request, proxies it over Tailscale to OpenClaw on claws-mac-mini, and returns the response. All ClaudeFlare Workers call Claude via this path. No ANTHROPIC_API_KEY anywhere.

  CF Worker  →  ExoClaw (CF Worker)  →  Tailscale  →  OpenClaw :18789
                  validates token           mesh        claude CLI OAuth
                  OPENCLAW_CODEX_TOKEN               no API key needed

ClaudeFlare VS DuraClaw

ClaudeFlare is a fork, not a replacement. DuraClaw is a mature agent runtime with broader scope. ClaudeFlare bets deep on two specific patterns that DuraClaw doesn't prioritize.

Built-In Layer Catalog

Stack & Conventions

TypeScript-first, pnpm monorepo. Each Worker is an independent package under apps/. Shared primitives in packages/. Same structure as Organized AI codebase standard.

Monorepo Layout

apps/
  flair-dispatcher/        # CF Worker — task routing gateway
  worker-doc-gen/          # CF Worker — Claude doc generation
  worker-task-template/    # CF Worker — extend for custom tasks
  worker-audit/            # CF Worker — state audit
  exoclaw-bridge/          # CF Worker — Tailscale bridge
  flair-dashboard/         # CF Pages — task + doc index
packages/
  flair-workers/           # ephemeral worker base class + lifecycle
  doc-engine/              # layer manifest reader + Claude doc prompt
  types/                   # shared TypeScript types
  kv/                      # KV namespace helpers
  queue/                   # Queue send/receive helpers
scripts/
  deploy-all.sh            # deploy all Workers + dashboard
  docs-build.sh            # trigger doc-gen for all layers
  bootstrap.sh             # first-time CF infra provisioning
.claude/
  CLAUDE.md                # agent conventions for Claude Code
  skills/                  # Organized Codebase skills
  commands/                # custom slash commands
CLAUDE.md                  # root agent entry
flair.project.json         # project-level manifest

Key Dependencies

Deploy & Run

Three scripts do everything. bootstrap.sh provisions CF infra. deploy-all.sh deploys Workers. docs-build.sh triggers doc generation for all layers.

1. Bootstrap (once)

# scripts/bootstrap.sh — run once per new project
CLOUDFLARE_ACCOUNT_ID=691fe25d377abac03627d6a88d3eeac9 \
  bash scripts/bootstrap.sh

# Creates:
#   • KV namespace: FLAIR_KV
#   • D1 database:  flair-state
#   • R2 bucket:    flair-artifacts
#   • Queues:       flair-doc-queue, flair-task-queue, flair-audit-queue
#   • CF Pages projects per layer (from flair.project.json)

2. Configure Secrets

cp .env.example .env
# Fill in:
OPENCLAW_URL=https://exoclaw.your-account.workers.dev
OPENCLAW_CODEX_TOKEN=codex_...
CLOUDFLARE_ACCOUNT_ID=691fe25d377abac03627d6a88d3eeac9

# Push to Workers:
echo $OPENCLAW_URL         | wrangler secret put OPENCLAW_URL         --name flair-dispatcher
echo $OPENCLAW_CODEX_TOKEN | wrangler secret put OPENCLAW_CODEX_TOKEN --name worker-doc-gen
echo $OPENCLAW_CODEX_TOKEN | wrangler secret put OPENCLAW_CODEX_TOKEN --name worker-task-template

3. Deploy All Workers

CLOUDFLARE_ACCOUNT_ID=691fe25d377abac03627d6a88d3eeac9 \
  bash scripts/deploy-all.sh --commit-dirty=true

# Individual Worker:
CLOUDFLARE_ACCOUNT_ID=691fe25d377abac03627d6a88d3eeac9 \
  wrangler deploy --name flair-dispatcher \
  --config apps/flair-dispatcher/wrangler.toml \
  --commit-dirty=true

4. Generate All Docs

# Trigger doc-gen for every layer in flair.project.json
bash scripts/docs-build.sh

# Or trigger a single layer:
curl -X POST https://flair-dispatcher.your-account.workers.dev/dispatch \
  -H "Content-Type: application/json" \
  -d '{"task": "doc:generate", "payload": {"layer": "worker-analyzer"}}'

# Deploy this doc site pattern (how this page was deployed):
wrangler pages project create claudeflare-arch --production-branch=main
wrangler pages deploy ./docs \
  --project-name=claudeflare-arch \
  --branch=main \
  --commit-dirty=true

Operational Checklist