Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bitwikiorg/continuity/llms.txt

Use this file to discover all available pages before exploring further.

Continuity hooks are an optional extension layer that lets you react to state file changes without modifying the core templates. When a state file changes, a hook can fire a webhook, append an event to a log, move completed tasks to an archive directory, or call a notification endpoint — all without the agent itself needing to orchestrate it. The hook layer sits outside the agent’s reasoning loop and supplements it with automation.

​
What hooks can do

Hooks watch specific state files and execute configured actions when those files change:
  • Watch state files — monitor STATE.md, TODO.md, SNAPSHOT.md, or any file in your workspace
  • Trigger webhooks — send a JSON event payload to an HTTP endpoint when a file updates
  • Move completed tasks — automatically relocate finished TODO.md entries to completed/ without agent involvement
  • Append to event logs — maintain a logs/events.jsonl audit trail of every state transition

​
Setup

1

Copy and customize the example config

Copy hooks.example.yaml into your workspace and edit it to match your environment. The file uses environment variables for sensitive endpoints — set CONTINUITY_STATE_WEBHOOK and CONTINUITY_NOTIFY_ENDPOINT in your shell before running the watcher.
cp hooks/hooks.example.yaml /your/workspace/hooks.yaml
2

Run a file watcher

Hooks require an external file watcher to detect changes. Three common options:
# watchexec — watches STATE.md and runs the script on each change
watchexec -w STATE.md -- python3 hooks/webhook-on-state-change.py

# entr — pipe a file list, re-run on any change
ls STATE.md TODO.md SNAPSHOT.md | entr python3 hooks/webhook-on-state-change.py

# inotifywait — Linux inotify, useful in CI and server environments
inotifywait -m -e close_write STATE.md TODO.md SNAPSHOT.md \
  --format '%w' | while read file; do
    python3 hooks/webhook-on-state-change.py
  done
3

Or use the example webhook script directly

The repository ships a self-contained Python script that reads CONTINUITY_STATE_WEBHOOK from the environment, appends an event to logs/events.jsonl, and POSTs a JSON payload to the webhook URL. No dependencies beyond the Python standard library.

​
hooks.example.yaml

# Continuity hooks configuration
# Copy to your workspace and customize. Use with a file watcher (entr, watchexec, inotifywait).

watch:
  - file: STATE.md
    on_change:
      - append: logs/events.jsonl
      - webhook: ${CONTINUITY_STATE_WEBHOOK}

  - file: TODO.md
    on_done:
      - move_to: completed/
      - append: logs/events.jsonl

  - file: SNAPSHOT.md
    on_change:
      - append: logs/events.jsonl
      - notify: ${CONTINUITY_NOTIFY_ENDPOINT}

# Rules
rules:
  - do_not_write_secrets_to_markdown
  - require_checkpoint_before_irreversible_actions
  - safety_inheritance: child_must_not_weaken_parent
The rules block is informational — it documents the safety constraints in force for this workspace and can be read by the agent alongside WARNING.md. Rules are not enforced by the hook runner itself; they are declarations the agent loads and self-applies.

​
webhook-on-state-change.py

#!/usr/bin/env python3
"""Send a webhook when a Continuity state file changes.

Usage:
  watchexec -w STATE.md -- python3 webhook-on-state-change.py
  # or
  ls STATE.md | entr python3 webhook-on-state-change.py
"""

import os
import sys
import json
import urllib.request
from datetime import datetime, timezone
from pathlib import Path

WEBHOOK_URL = os.environ.get("CONTINUITY_STATE_WEBHOOK", "")
EVENT_LOG = Path("logs/events.jsonl")


def main():
    if not WEBHOOK_URL:
        print("CONTINUITY_STATE_WEBHOOK not set - skipping webhook")
        return

    event = {
        "ts": datetime.now(timezone.utc).isoformat(),
        "event": "state_file_changed",
        "file": "STATE.md",
        "level": "info",
    }

    # Append to event log
    EVENT_LOG.parent.mkdir(parents=True, exist_ok=True)
    with EVENT_LOG.open("a") as f:
        f.write(json.dumps(event) + "\n")

    # Send webhook
    payload = json.dumps(event).encode()
    req = urllib.request.Request(
        WEBHOOK_URL,
        data=payload,
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=10) as resp:
            print(f"Webhook sent: {resp.status}")
    except Exception as e:
        print(f"Webhook failed: {e}", file=sys.stderr)


if __name__ == "__main__":
    main()
The script builds a minimal event object with a UTC timestamp, event type, affected file, and severity level. It writes to logs/events.jsonl first — so the local log is always updated even if the HTTP call fails — then POSTs to the configured URL. Failures are printed to stderr and do not terminate the watcher process.

​
Common hook triggers

File watchedTrigger conditionExample action
STATE.mdAny changePOST event to webhook, append to logs/events.jsonl
TODO.mdTask marked doneMove entry to completed/, append to event log
SNAPSHOT.mdAny changeNotify endpoint, append to event log

​
Use cases

CI-like validation

Run check-placeholders.sh or state-file-audit.sh automatically when state files change — the same validation you’d run in a CI pipeline, triggered locally by the file watcher.

Auto-embed for vector stores

Hook into STATE.md and SNAPSHOT.md changes to trigger re-embedding. Keeps your vector store in sync with the agent’s current cognitive state without manual reruns.

Notification on state change

POST to a Slack webhook, PagerDuty endpoint, or any HTTP target when the agent updates its state. Useful for monitoring long-running autonomous sessions.

Completed task archival

Automatically move finished tasks out of TODO.md and into completed/ using on_done — prevents accumulation of done items in the active task list.
Hooks are optional. Most agents do not need them. The core feedback loop — agent reads state, acts, writes state — works without any hook configuration. Hooks add automation for teams that want CI-like validation, notification pipelines, or automatic archival of completed work.

Build docs developers (and LLMs) love

Get started for freeTalk to us