- name
- openclaw-harness
- description
- Cross-session context manager for AI agents with checkpoint/snapshot, Build-Verify-Fix closure, and entropy management (GC). Use when: (1) creating a task checkpoint before risky work, (2) verifying task completion via harness verify, (3) cleaning up stale checkpoints with harness gc, (4) restoring a previous checkpoint, (5) tracking cross-session progress, or (6) linting agent configuration files (SOUL.md/IDENTITY.md/AGENTS.md).
openclaw-harness
Cross-session context tracking, entropy management, and verification closure for AI agents.
Quick Reference
| Command | Description | |||
|---|---|---|---|---|
harness init [--force] | Initialize Harness in current workspace | |||
| `harness status [-v\ | -j\ | -s]` | Show Harness status | |
harness checkpoint create <label> [--tag <tag>] | Create a checkpoint snapshot | |||
harness checkpoint list | List all checkpoints | |||
harness checkpoint restore <cp-id> [--force] | Restore to a checkpoint | |||
harness checkpoint delete <cp-id> | Delete a checkpoint | |||
harness verify [--rule '<json>'] [--exit-code] | Run verification checks | |||
harness gc [--dry-run] [--max-cp N] [--max-age N] [--aggressive] | Entropy cleanup | |||
harness progress show | Show cross-session progress | |||
harness linter [--fix] [--strict] | Lint SOUL/IDENTITY/AGENTS files | |||
| `harness fix [placeholders\ | whitespace\ | trailing\ | all]` | Auto-fix linter issues |
Core Workflow
# 1. Initialize (once per workspace)
harness init
# 2. Create checkpoint before risky work
harness checkpoint create "before-refactor"
# 3. Do work, verify
harness verify
# 4. Create another checkpoint when milestone reached
harness checkpoint create "feature-done" --tag "feature"
# 5. Preview cleanup
harness gc --dry-run
# 6. Restore if needed
harness checkpoint restore <cp-id> --forceSafety Rules
- Never deleted: SOUL.md, IDENTITY.md, USER.md, MEMORY.md, AGENTS.md, TOOLS.md, TASKS.md, .harness/
- All deletions logged to
.harness/gc.log - Deleted files archived to
.harness/.trash/before removal
Directory Structure
.harness/ # Harness state root (created by init)
├── .initialized # Init marker (version + timestamp)
├── config.json # Config: max_checkpoints, max_age_days, etc.
├── gc.log # Deletion audit log
├── checkpoints/<cp-id>/ # Checkpoint snapshots
│ ├── manifest.json # Snapshot manifest
│ └── files/ # Snapshot copies
├── reports/ # Verification reports
├── tasks/ # Task metadata
├── tmp/ # Temp files (GC target)
└── .agent-progress.json # Cross-session progress stateAdvanced Usage
Custom verification rules:
harness verify --rule '[{"name":"Build OK","type":"command","path":"npm run build"}]'Checkpoint management:
harness checkpoint create "label" --tag "v1" --tag "stable"
harness checkpoint show <cp-id>GC with limits:
harness gc --max-cp 5 # Max 5 checkpoints per task
harness gc --max-age 7 # Delete checkpoints older than 7 days
harness gc --aggressive # Also clean tmp/ directoryProgress tracking:
harness progress show
harness progress set-phase "Phase 2"
harness progress add-blocker "Waiting for API key"Linter and fix:
harness linter --strict # Fail on warnings too
harness linter --fix # Auto-fix issues (creates .orig backups)
harness fix all --dry-run # Preview all auto-fixesDetailed Reference
For complete documentation, load the relevant reference:
- Architecture & design: See references/architecture.md
- Requirements & acceptance criteria: See references/requirement.md
- Technical knowledge package: See references/knowledge-package.md
- Maintenance guide: See references/maintenance.md
Scripts
This skill includes helper scripts for skill developers:
scripts/init_skill.py— Initialize a new skill from templatescripts/package_skill.py— Package and validate a skill into .skill file
# Create a new skill
python scripts/init_skill.py my-new-skill --path /path/to/output
# Package a skill
python scripts/package_skill.py /path/to/skill-folder