vericify

Vericify

__     _______ ____  ___ ____ ___ _______   __
\ \   / / ____|  _ \|_ _/ ___|_ _|  ___\ \ / /
 \ \ / /|  _| | |_) || | |    | || |_   \ V /
  \ V / | |___|  _ < | | |___ | ||  _|   | |
   \_/  |_____|_| \_\___\____|___|_|     |_|

Vericify is a local-first run intelligence hub for multi-agent workflows and AI agent state.

It gives a workspace durable run records, checkpointed handoffs, and a four-layer compare engine instead of making you reconstruct intent from chat scrollback, shell history, and raw logs.

It works on its own, and it also plugs neatly into ACE / ace-swarm workspaces that already emit agent-state/*.

Product Summary

Vericify is for engineers building with AI agents who want run-level observability and clear answers to questions like:

• What is moving right now?
• What is blocked?
• Which run diverged?
• Which earlier run looks like a recovery path?
• What should I publish or hand off?

The package installs one CLI:

vericify

Default behavior is simple:

• run it inside the repo you want to observe
• store native state in .vericify/
• read partner state from agent-state/* when present
• open the terminal hub with vericify or vericify hub

What Vericify Does

Vericify gives you:

• a terminal cockpit with four views — Hub, Inspect, Compare, History — for run inspection and agent observability
• a structured run model built from handoffs, posts, todos, events, and checkpoints
• a compare engine that measures divergence and recovery across four layers: exact diff, structural delta, semantic similarity (MinHash), and operational timing
• publishable run artifacts under .vericify/published/
• a local-first sync outbox under .vericify/sync-outbox/
• adapter contracts for Claude Code, Codex, Cursor, VS Code Copilot, Antigravity, and ACE / ace-swarm workspaces

Install

npm install -g vericify

Node 18+ is required.

Five-Minute Start

1) Start in any repo

cd /path/to/repo
vericify context
vericify adapters
vericify hub

If Vericify already sees .vericify/ or agent-state/*, the hub can immediately project runs from that workspace.

2) If you already use ACE / ace-swarm

This is the easiest path.

If your workspace already contains agent-state/*, Vericify reads it automatically:

cd /path/to/ace-workspace
vericify context
vericify adapters
vericify hub

No extra conversion step is required.

3) If you are using another agent client and want to label it explicitly

Attach the adapter to the current workspace:

vericify attach --adapter codex --label "Primary Codex session"
vericify adapters

That creates or updates .vericify/adapters.json for the current repo and marks the adapter as attached.

For Claude Code, vericify attach --adapter claude-code also writes compact-bootstrap guidance into CLAUDE.md and, when .claude/ exists, installs the Vericify hook block into .claude/settings.json.

Compact Bootstrap And Resume

Use the compact packet when you want session bootstrap or resume without rereading the full projected state. This is the primary path for workflow continuity across context resets:

vericify context
vericify delta --since vcx_...
vericify snapshot --format compact

vericify context returns one minified JSON packet with:

• the selected run
• status
• current focus
• blockers
• a strict live_signal subset
• the last meaningful events
• a fresh opaque continuity id

Use --pretty if you want the compact packet formatted for humans.

Do I Need --session-id?

No. --session-id is optional.

Use no session ID when:

• one active session per tool is enough
• you only want to label the workspace relationship
• you want the lightest setup

Add a session ID when:

• you run multiple sessions from the same tool
• you want stable names in artifacts and dashboards
• you want to distinguish roles like claude-main and claude-review

Good session IDs look like:

• claude-main
• codex-bugfix
• cursor-review-01

What Attachment Looks Like

A) Attach without a session ID

This is valid:

vericify attach --adapter codex --label "Primary Codex session"

Simplified output:

{
  "path": ".vericify/adapters.json",
  "attachment": {
    "adapter_id": "codex",
    "capture_mode": "manual",
    "label": "Primary Codex session"
  }
}

Notes:

• capture_mode defaults to manual if you do not set one
• this is enough to tell Vericify "track this tool in this workspace"

B) Attach with a session ID

Use this when you want a named session:

vericify attach --adapter claude-code --session-id claude-main --capture-mode attachment --label "Claude main"

Simplified output:

{
  "path": ".vericify/adapters.json",
  "attachment": {
    "adapter_id": "claude-code",
    "capture_mode": "attachment",
    "session_id": "claude-main",
    "label": "Claude main"
  }
}

After that, verify status:

vericify adapters

Look for:

• detection_status: "attached"
• session_id when you supplied one
• label_override with your human-friendly name

Easy Use Cases

Use case 1: Observe an existing ACE / ace-swarm workspace

cd /path/to/ace-workspace
vericify adapters
vericify hub

Best when you already have agent-state/* and want a cockpit, history, and compare surface.

Use case 2: Tag a Codex, Claude Code, Cursor, VS Code Copilot, or Antigravity workspace before richer capture exists

vericify attach --adapter codex --label "Primary Codex"
vericify attach --adapter claude-code --session-id claude-main --capture-mode attachment
vericify context
vericify hub

Best when you want durable workspace metadata now. Claude Code attach also writes the startup guidance for vericify context, the vericify delta --since=<id> resume path, and the PreCompact reinjection hook when .claude/ is available.

Use case 3: Create a native run trail manually

vericify handoff --id h1 --from capability-ops --to capability-build --title "Implement compare engine" --status open
vericify post --run-id handoff:h1 --agent-id capability-build --kind progress --summary "Builder started compare engine"
vericify snapshot
vericify hub

Best when you want to model agent work directly in Vericify.

Use case 4: Compare two runs

vericify compare --run-id handoff:run-a --compare-run-id workspace:current

The comparison runs four layers simultaneously — exact diff, structural graph delta, semantic MinHash similarity, and operational timing analysis — and returns:

• composite similarity score
• latest checkpoint similarity
• actor and node overlap
• layer-level divergence cues
• recovery paths from prior runs
• recommended next actions

Use case 5: Publish or queue a run artifact

vericify publish --run-id handoff:run-a --compare-run-id workspace:current --title "Run A artifact"
vericify sync --run-id handoff:run-a --compare-run-id workspace:current --endpoint https://sync.example.test

This writes:

• .vericify/published/<artifact-id>/run-artifact.json
• .vericify/published/<artifact-id>/SUMMARY.md
• .vericify/sync-outbox/<item>.json

Product Spec

Core Objects

• Run: one coordinated attempt to complete an objective
• Branch: an alternate path inside a run
• Lane: one concurrent execution stream
• Handoff: transfer of responsibility
• Checkpoint: durable snapshot at a meaningful transition
• Delta: change between checkpoints, measured across four layers: exact diff, structural graph, semantic MinHash, and operational timing

Storage Contract

Vericify writes native state here:

.vericify/
|-- adapters.json
|-- handoffs.json
|-- todo-state.json
|-- run-ledger.json
|-- status-events.ndjson
|-- process-posts.json
|-- published/
`-- sync-outbox/

Vericify also reads partner state here when available:

agent-state/
`-- ...

This is why it works naturally with ACE / ace-swarm workspaces.

Adapter Contract

Current adapter registry:

• local-state
• ace
• codex
• claude-code
• cursor
• vscode-copilot-chat
• antigravity

Current truth:

• local-state is fully implemented
• ace is the partner path for ACE / ace-swarm style workspaces
• peer adapters are currently attachment and detection contracts
• auto-detection is heuristic for several tools, so explicit attachment is the reliable path

Checkpoint Policy

Checkpoint triggers currently include:

• handoff
• status_transition
• process_milestone
• ledger_update
• operator_save
• branch_fork

Capture modes currently include:

• semantic
• git
• hybrid

Today the package is semantic-first. Git-backed provenance can be attached when available.

CLI Reference

High-signal commands

vericify help
vericify context
vericify delta --since vcx_...
vericify adapters
vericify attach --adapter codex --label "Primary Codex session"
vericify attach --adapter claude-code --session-id claude-main --capture-mode attachment --label "Claude main"
vericify hub
vericify snapshot
vericify snapshot --format compact
vericify compare --run-id handoff:run-a --compare-run-id workspace:current
vericify publish --run-id handoff:run-a
vericify sync --run-id handoff:run-a --endpoint https://sync.example.test

Native writer commands

vericify handoff --id h1 --from capability-ops --to capability-build --title "Review" --status open
vericify todo --id todo-1 --title "Write store" --status in_progress
vericify ledger --tool vericify --category major_update --message "Writer landed"
vericify event --source-module capability-build --event-type STORE_WRITE --status started --payload-json '{"summary":"native write"}'
vericify post --run-id handoff:h1 --agent-id capability-build --kind progress --summary "Checkpoint emitted"

Helpful defaults

• current working directory is the workspace unless you pass --workspace-root
• vericify with no command opens hub
• --session-id is optional
• --compare-run-id is optional for publish and sync

Terminal Hub Controls

Start the cockpit:

vericify hub

The cockpit has four views. Each answers a different operational question.

Keys:

• q quit
• j / k move between runs
• Enter inspect selected run — lane activity, blockers, checkpoint timeline
• c compare selected run — four-layer diff across exact, structural, semantic, and operational dimensions
• y history view — prior runs indexed, recovery patterns ranked by similarity to the current state
• a adapters view — attached tools and detection status
• h back to hub — all active runs, what is moving, what is blocked
• r refresh
• / command palette
• Ctrl+R command history search

Programmatic API

The package exports functions for workspace state projection, run comparison, and artifact publishing:

• loadWorkspaceState
• projectWorkspaceState
• buildCompactPacket
• buildCompactPacketDetails
• buildCompactDelta
• detectAdapters
• listAvailableAdapters
• listDefaultWorkspacePaths
• attachAdapter
• buildRunComparison
• publishRunArtifact
• enqueueSyncOutboxItem