Skip to content
TokenArch 2026.4.23
For OpenClaw · 2026.4.23

NightClaw

A file-based operating protocol for OpenClaw workspaces. NightClaw supplies the prompts, schema, command surface, mutation bundles, audit logs, integrity gates, tests, and optional monitor components used by long-running worker and manager sessions.

Apache 2.0 · Technical users · at your own risk · github.com/tokenarch/nightclaw
Open guided demo View repository
What Makes It Work

A protocol surface an agent can query before acting.

NightClaw is not just a prompt pack. The current repo exposes a schema-backed operating model, a Python command surface, mutation bundles, integrity checks, and a packaged smoke test so technical users can inspect the system before running it.

R1 / R2
Objects and field contracts

The schema names the state objects NightClaw knows about and the fields that make those objects valid. It gives worker, manager, and maintainer sessions a shared reference for what exists and what valid state looks like.

Current package: 25 R1 objects and 87 R2 field contracts loaded by the schema model.
R3 / R4
Routes and dependency edges

Before touching a file, a session can ask how that path is routed. Before changing operational state, it can inspect related edges. This is the difference between reading README prose and querying the repo's live protocol model.

Use registry-route for route tier questions and cascade-read for dependency awareness.
R5
Named mutation bundles

State changes are represented as named transactions, not one-off edits. Bundles describe the allowed arguments, guards, and write targets for common transitions such as longrunner updates, phase transitions, escalations, manifest verification, and session close.

Current package validates 8 bundle definitions with validate-bundles.
R6 / SCR
Self-consistency rules

SCR predicates check that the schema, rendered registry, protected path list, bundle definitions, and code-surface assumptions remain internally consistent. This is not a formal proof system; it is a practical guardrail suite for a file-based protocol.

Current package runs SCR-01 through SCR-11 plus CL5 protected-path checks.
WORKER / MANAGER
Two scheduled OpenClaw sessions

NightClaw assumes a worker session for project execution and a manager session for review, direction, anomaly detection, and pruning. There is no separate orchestrator cron; ORCHESTRATOR.md documents the distributed dispatch and phase-transition model.

The shared lock, audit files, memory logs, and project LONGRUNNER files carry state across sessions.
ENGINE + OPTIONAL UI
Core commands, optional monitor

The core engine lives in nightclaw_engine and is reached through scripts/nightclaw-ops.py. Bridge and monitor packages are optional runtime-view components; tests assert the core engine does not import them.

Validated package shape: 377 tests passed, 1 skipped; packaged smoke test 18 passed, 0 failed.
Runtime Shape

OpenClaw runs sessions. NightClaw gives them a workspace protocol.

The current repo is cleanly split between the platform runtime, NightClaw's operational protocol files, and optional visibility components. The site can be more narrative than the README, but the division below reflects the actual pushed package.

Platform Layer
OpenClaw
The external runtime NightClaw installs into
  • Starts LLM sessions
  • Schedules worker and manager crons
  • Manages model/provider settings
  • Provides shell and filesystem access
  • Hosts the workspace where NightClaw lives
Protocol Layer
NightClaw
Files, schema, gates, bundles, and prompts
  • R1-R6 schema model
  • Worker and manager prompts
  • Protected-file integrity manifest
  • Audit, memory, and session registries
  • Mutation bundles and route checks
Visibility Layer
Bridge + Monitor
Optional runtime views and owner-facing screens
  • Local bridge process
  • Monitor-side selectors and handlers
  • Browser monitor HTML assets
  • Snapshot and replay contracts
  • Not required by the core engine

NightClaw is OpenClaw-specific · Bridge and monitor are optional · The core engine was proven before these additions and remains separately tested

Architecture

Schema-backed files, Python gates, and scheduled agent sessions.

NightClaw keeps operational state in the workspace, but the latest repo is more than Markdown. The schema YAML is loaded by a Python engine, rendered into the registry, queried through nightclaw-ops.py, and checked by SCR, integrity, bundle, unit, and smoke-test gates.

nightclaw-architecture — current repo shape
OpenClaw runtime

OpenClaw starts sessions, schedules crons, configures models/providers, and provides the shell, filesystem, and tool context that NightClaw sessions operate within.

Worker session

orchestration-os/CRON-WORKER-PROMPT.md guides bounded project passes, LONGRUNNER updates, lock discipline, and handoff output.

Manager session

orchestration-os/CRON-MANAGER-PROMPT.md guides review, direction, pruning, anomalies, notifications, and owner-facing decisions.

Protocol files

SOUL.md, USER.md, MEMORY.md, LOCK.md, NOTIFICATIONS.md, ACTIVE-PROJECTS.md, PROJECTS/*/LONGRUNNER.md, and audit/*.md carry the operational workspace state.

Schema and engine

orchestration-os/schema/*.yaml defines the R1-R6 and CL5 model. nightclaw_engine/ loads that model and implements gates, bundles, SCR checks, rendering, and longrunner helpers. scripts/nightclaw-ops.py exposes the query and mutation surface.

Optional visibility

nightclaw_bridge/, nightclaw_monitor/, and apps/monitor/ provide optional runtime views and owner-facing screens. The core engine is tested separately from these packages.

Recovery Model

Diagnose before retrying. Surface what needs judgment.

NightClaw gives worker and manager sessions a documented recovery path: check known failure modes, apply safe documented fixes, use pre-approval only when authorized, complete partial work when appropriate, or surface a notification for human review.

BLOCKER ENCOUNTERED
Known failure mode?
YES Apply documented fix from OPS-FAILURE-MODES.md
Resolved?
YES Continue execution
NO Pre-approval covers this?
YES Execute pre-approved action, continue
NO Partial completion possible?
YES Complete what's safe, log partial result
NO Can objective be reformulated?
YES Reframe next_pass, continue if safe
NO Surface to NOTIFICATIONS.md — Log as new failure mode — Re-route when safe — human review required
Async Workflow

The worker runs. The manager reviews. You stay in control.

NightClaw is designed for asynchronous operation. Proposals, blockers, and decisions surface into workspace files such as NOTIFICATIONS.md and audit logs. You review at your own cadence, and the next appropriate pass acts on the recorded decision.

Worker executes a bounded pass

The worker reads project state, checks tools and protocol surfaces, performs the next pass, then updates longrunner, memory, audit, and session state.

Escalation or proposal surfaces

When the next step requires judgment, the session records the issue and expected decision path instead of silently inventing permission.

Manager and owner review

The manager reviews state, direction, and quality. The owner can approve, redirect, pause, or modify the next step before work continues.

NOTIFICATIONS.md — Proposed Enhancement 
[2026-04-06 02:14] | Priority: PROPOSAL | Project: etl-pipeline | Status: PENDING-REVIEW

Proposal: [data-source] changed column header
  "Net Summer Capacity (MW)" → "Capacity_Net_Summer_MW"
  in April 2026 vintage

Proposed path: Update field map in OPS-KNOWLEDGE-EXECUTION.md,
  re-run diff script against corrected header

Estimated cost:  STANDARD
Blocking current work: NO

If approved:  Update field map on next pass, re-run validation
If declined:  Continue with last known-good vintage until manual review
Contents

Protocol files plus a tested command engine.

The latest repo includes Markdown state and prompt files, YAML schema sources, shell installers, a Python command engine, optional bridge/monitor packages, and a test suite. Minimum runtime is Python 3.10+, PyYAML, and OpenClaw.

Root/
  • SOUL.md · AGENTS.md
  • AGENTS-CORE.md
  • AGENTS-LESSONS.md
  • IDENTITY.md · USER.md
  • MEMORY.md · HEARTBEAT.md
  • WORKING.md · LOCK.md
  • ACTIVE-PROJECTS.md
  • NOTIFICATIONS.md · TOOLS.md
  • VERSION · .gitignore
  • INSTALL.md · DEPLOY.md
  • README.md · LICENSE
  • SECURITY.md
  • CONTRIBUTING.md · CODE_OF_CONDUCT.md
  • PROTOCOL-PROOF.md
  • REGISTRY.generated.md
audit/
  • AUDIT-LOG.md
  • INTEGRITY-MANIFEST.md
  • APPROVAL-CHAIN.md
  • SESSION-REGISTRY.md
  • CHANGE-LOG.md
orchestration-os/
  • CRON-WORKER-PROMPT.md
  • CRON-MANAGER-PROMPT.md
  • CRON-HARDLINES.md
  • REGISTRY.md
  • OPS-FAILURE-MODES.md
  • OPS-QUALITY-STANDARD.md
  • OPS-AUTONOMOUS-SAFETY.md
  • OPS-PREAPPROVAL.md
  • OPS-CRON-SETUP.md
  • OPS-KNOWLEDGE-EXECUTION.md
  • LONGRUNNER-TEMPLATE.md
  • ORCHESTRATOR.md · START-HERE.md
  • OPS-IDLE-CYCLE.md · OPS-TOOL-REGISTRY.md
  • OPS-PASS-LOG-FORMAT.md · TOOL-STATUS.md
  • PROJECT-SCHEMA-TEMPLATE.md
  • schema/*.yaml
scripts/
  • install.sh
  • validate.sh
  • verify-integrity.sh
  • new-project.sh
  • resign.sh
  • smoke-test.sh
  • check-lock.py
  • nightclaw-ops.py
  • nightclaw-admin.sh
  • start-monitor.sh
validate.sh — all checks passing
verify-integrity.sh — 11/11 hash verified
engine + monitor
  • nightclaw_engine/
  • nightclaw_ops/
  • nightclaw_bridge/
  • nightclaw_monitor/
  • apps/monitor/
  • tests/
Core engine is tested separately from optional bridge and monitor components.
Quick Start

Install, query the protocol, then run the gates.

NightClaw is intended for technical users. Initial setup and configuration are expected. The repo should be approached the way it is designed to be used: bootstrap first, query the schema-backed protocol, then run the validation suite.

terminal 
# Clone the public repository
git clone https://github.com/tokenarch/nightclaw
cd nightclaw

# Run the install script (substitutes placeholders, generates hashes)
bash scripts/install.sh

# Query and validate the protocol
python3 scripts/nightclaw-ops.py bootstrap --track=general
python3 scripts/nightclaw-ops.py schema-lint
python3 scripts/nightclaw-ops.py schema-sync
python3 scripts/nightclaw-ops.py scr-verify
python3 scripts/nightclaw-ops.py validate-bundles
python3 scripts/nightclaw-ops.py integrity-check
bash scripts/validate.sh
pytest tests/ -q
# current package: 377 passed, 1 skipped

# Smoke test a packaged copy: scripts/smoke-test.sh → 18 passed, 0 failed

# Then configure SOUL.md, USER.md, model tiers, and crons per DEPLOY.md.
  • Apache License 2.0 — provided on an "AS IS" basis without warranties or conditions of any kind
  • Intended for technical users comfortable reviewing local automation, prompts, scripts, schema, and agent behavior
  • Initial setup and configuration are expected; results vary by local environment, model setup, workspace configuration, and operator judgment
  • Personally tested by the maintainer and revised for public open source release with available time and resources
  • Core workflow was proven effective under the core engine before bridge and monitor additions; nothing is guaranteed
  • Behavioral prompts and hardlines are not OS-level or cryptographic enforcement
  • SHA-256 integrity checks detect protected-file drift; they do not prevent out-of-band filesystem changes
  • Review configuration, protect credentials, monitor automated runs, and validate outputs before relying on them