Package Exports

vericify
vericify/api
vericify/package.json

Readme

Vericify

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

Vericify is a local-first operations hub for agent work.

It gives a workspace a durable run model 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 people building with agents who want to answer 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 for run inspection
a structured run model built from handoffs, posts, todos, events, and checkpoints
a compare engine that explains divergence and recovery
publishable run artifacts under .vericify/published/
a local-first sync outbox under .vericify/sync-outbox/
partner compatibility with ACE / ace-swarm

Install

npm install -g vericify

Node 18+ is required.

Five-Minute Start

1) Start in any repo

cd /path/to/repo
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 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.

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 or Claude Code 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 hub

Best when you want durable workspace metadata now, even before vendor-specific live capture bridges are added.

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 report includes:

composite similarity
latest checkpoint similarity
actor overlap
node overlap
layer-level divergence cues
recovery explanations
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: structural, semantic, or operational change between checkpoints

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 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 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

Keys:

q quit
j / k move between runs
Enter inspect selected run
c compare selected run
y history view
h back to hub
r refresh
/ command palette
Ctrl+R command history search

Programmatic API

The package also exports:

loadWorkspaceState
projectWorkspaceState
detectAdapters
attachAdapter
buildRunComparison
publishRunArtifact
enqueueSyncOutboxItem

Honest Status

Vericify is intentionally honest about what is implemented now.

peer client adapters are not full live capture bridges yet
hosted sync is an outbox contract today, not a running SaaS backend
git-backed diffing exists as optional provenance, not the whole product

That is deliberate: the package is meant to be useful now, without pretending unfinished infrastructure already exists.

vericify