kite.json Manifest Reference

Configure subscriptions, sinks, filters, enrichment, scoring, and queue settings for kite run --manifest kite.json.

The kite.json manifest drives kite run --manifest kite.json. It defines what events to receive, how to route them, and optional filtering, enrichment, and scoring settings.

// 01Minimal example

{
  "name": "my-agent",
  "sink": { "type": "proxy", "target": "http://localhost:3000/webhooks" }
}

// 02Full example

{
  "name": "my-agent",
  "subscriptions": [
    { "source": "github" },
    { "type": "com.stripe.payment_intent.succeeded" }
  ],
  "sink": {
    "type": "exec",
    "command": "./handle-event.sh",
    "importance": "high"
  },
  "filters": {
    "drop": [
      { "source": "github", "type": "com.github.ping" }
    ],
    "keep_only": [
      { "source": "github", "type": "com.github.push" },
      { "source": "github", "type": "com.github.pull_request.*" }
    ]
  },
  "enrichment": [
    {
      "match": { "source": "github", "type": "com.github.pull_request.*" },
      "run": "scripts/enrich-pr.sh",
      "timeout": "30s"
    }
  ],
  "scoring": {
    "rules": [
      {
        "match": { "source": "github", "type": "com.github.push" },
        "importance": "high",
        "paths": ["src/auth/*"],
        "reason": "auth-path push"
      }
    ],
    "default_importance": "normal"
  }
}

// 03Top-level fields

// 04Subscription

Narrows the WebSocket subscription request and the local manifest delivery filter. Multiple entries are OR'd.

// 05Sink types

The sink.type field selects the delivery mode.

stdout

Print events to standard output.

{ "type": "stdout", "json": true }

proxy

Forward events as HTTP POST to a local server.

{ "type": "proxy", "target": "http://localhost:3000/webhooks" }

socket

Write events to a Unix domain socket.

{ "type": "socket", "path": "/tmp/kite.sock" }

exec

Execute a shell command for each event. Event JSON is passed on stdin.

{ "type": "exec", "command": "./handle.sh", "importance": "high" }

mcp_server

Expose events as an MCP (Model Context Protocol) server.

{ "type": "mcp_server", "buffer_size": 100 }

paperclip

Trigger Paperclip agent heartbeats on matching events.

{
  "type": "paperclip",
  "api_url": "https://api.paperclip.ing",
  "company_id": "your-company-id",
  "agent_id": "optional-agent-id"
}

// 06FilterConfig

Applied before delivery. Drop rules run first; if any match, the event is dropped. keep_only rules run next — if any are defined and none match, the event is also dropped.

{
  "filters": {
    "drop": [
      { "source": "github", "type": "com.github.ping" }
    ],
    "keep_only": [
      { "source": "github", "type": "com.github.push" }
    ]
  }
}

FilterRule fields

All fields are optional and AND'd together. Glob patterns (*, **) are supported in source and type.

// 07EnrichmentHook

Run a shell script before delivery. The script receives the CloudEvent JSON on stdin. If it emits JSON to stdout, that JSON is stored as enrichment metadata and can influence later scoring fields such as changed_files; the delivered event body remains the original CloudEvent for sink compatibility.

// 08ScoringConfig

Assign importance levels to events.

ScoringRule

DedupConfig

kite run applies deduplication after queue insertion and before filters, enrichment, scoring, and sink delivery. Duplicate events are marked filtered in the local queue and acknowledged to the server.

// 09QueueConfig

Local queue retention settings. kite run applies these after inserting each event into the local SQLite queue.