Agent Workflow

Every agent — human-operated, LLM-driven, or automated — interacts with hence through the same set of CLI commands. The workflow is intentionally simple: read the plan, find your tasks, claim them, do the work, assert what you learned, and mark them done. The hence reasoner handles all the logic about what is ready, who should work on what, and what the current state of the project is.

This guide walks through the full lifecycle, from setting your identity to coordinating across multiple machines with hence.run hosted plans.

The Standard Agent Loop

Every agent session follows the same repeating cycle. Whether you are an LLM processing tasks autonomously or a human checking in on a project, these are the steps:

1. Establish your identity — run hence agent whoami to confirm which agent identity is active. This prints your agent name and, if you have a cryptographic keypair, your public key. It is a fast sanity check before you start claiming tasks.

   $ hence agent whoami
   supervisor:ed25519:a3f9b2c1
   agent:alice
   evaluator:ed25519:b4e8f3d2
   PeerId: 12D3KooW...

2. Read plan metadata — run hence plan info plan.spl to see high-level information about the plan: its title, description, declared agents, and the total number of tasks.

   $ hence plan info plan.spl
   title:    Backend Refactor Sprint
   tasks:    12 declared
   agents:   alice, bob, claude
   source:   plan.spl (local)

3. View the full task board — run hence plan board plan.spl to see all tasks and their current status across every kanban column. This gives you the complete picture before narrowing down to your own work.

   $ hence plan board plan.spl
   +--------------+--------------+--------------+--------------+--------------+
   |  BACKLOG     |   READY      | IN PROGRESS  |  BLOCKED     |    DONE      |
   +--------------+--------------+--------------+--------------+--------------+
   |loadtest      |write-tests ..|api @alice    |deploy        |setup         |
   |tests         |update-docs ..|api-review @b.|              |add-ci        |
   +--------------+--------------+--------------+--------------+--------------+
   
   Tasks: 2 backlog, 2 ready, 2 in-progress, 1 blocked, 2 done

4. Find your assigned tasks — run hence task next plan.spl to see which tasks the plan's rules assign to you specifically. This filters the READY column to only show tasks where the derived fact assign-to-TASK-AGENT matches your identity. The output includes ready-to-paste claim commands.

   $ hence task next plan.spl
   Next actions for alice:
     1. write-tests @alice — hence task claim write-tests plan.spl --agent alice
     2. update-docs @alice — hence task claim update-docs plan.spl --agent alice

5. Claim a task — run hence task claim TASK plan.spl to take ownership of a task. This appends a (claims ...) block to the plan file and moves the task to IN PROGRESS on the board.

   $ hence task claim write-tests plan.spl
   Added: (claims agent:alice :at "2026-02-24T09:00:00Z" ...)
     (given claim-v1-write-tests)
     ...
   
   Next actions for alice:
     (no actions available)

6. Do the work — execute whatever the task requires: write code, run a command, call an API, review a document. hence does not prescribe what "the work" looks like — it only tracks the task lifecycle around it.
7. Assert findings — as you work, use hence task assert to record facts or rules that other agents and the plan's logic can build on. This is how agents communicate discoveries to each other without out-of-band channels.

   $ hence task assert '(given tests-passing)' plan.spl
   $ hence task assert '(given coverage-above-80)' plan.spl --task write-tests

8. Complete the task — run hence task complete TASK plan.spl to mark the task done. This appends a (completed ...) block to the plan, moves the task to DONE, and may unlock downstream tasks that were waiting on this one.

   $ hence task complete write-tests plan.spl
   completed: write-tests (alice)

9. Back to step 4 — run hence task next plan.spl again to find your next assignment. Newly unlocked tasks will now appear in the list.

The HENCE_AGENT Environment Variable

All hence commands that act on behalf of an agent — claiming, completing, asserting — need to know which agent is performing the action. The cleanest way to provide this is via the HENCE_AGENT environment variable, set once at the top of your session.

# Set once for the session — all commands inherit it
export HENCE_AGENT=alice

# Now claim, complete, and assert all tag actions as "alice"
hence task claim refactor-auth plan.spl
hence task assert '(given auth-refactor-done)' plan.spl
hence task complete refactor-auth plan.spl

If you need to override the environment variable for a single command, use the --agent flag:

# Override for a single command
hence task claim deploy-staging plan.spl --agent devops-bot

Why agent identity matters

Agent identity is how the plan's assignment logic targets the right agents. When a plan rule says:

normally assign-to-write-tests-alice
  given task-write-tests
  given agent-alice

The reasoner fires this rule when agent-alice is a known fact. That fact comes from the HENCE_AGENT value you export. Without it, hence task next would not know which assignments to show you.

Agent identity also appears in the audit trail recorded in the plan file. Every (claims ...), (completed ...), and (asserted-by ...) block references the agent name so the board can accurately show who has claimed what.

Agent name formats

Understanding hence task next Output

hence task next is your primary entry point into the work queue. It evaluates the plan's rules against the current set of facts and returns only the tasks that are both READY and assigned to the active agent.

What "assigned" means

A task is considered assigned to you when the reasoner derives the fact assign-to-TASK-AGENT — for example, assign-to-write-tests-alice. Plan authors write rules that produce these conclusions. A typical rule looks like this:

normally assign-to-write-tests-alice
  given task-write-tests
  given agent-alice
  given tests-not-yet-written

The reasoner fires this rule when all three conditions hold. If a more specific rule defeats it — for example, a rule saying a senior reviewer must do the tests first — the assignment may shift. Defeasibility means you always see the current best conclusion, not just static assignment.

Reading the output

$ hence task next plan.spl

Tasks assigned to alice (2 ready):

  write-tests     [READY]   → hence task claim write-tests plan.spl
  update-docs     [READY]   → hence task claim update-docs plan.spl

Other ready tasks (not assigned to you):

  api-review      [READY]   assigned to bob

Each line in the "assigned to you" section includes a copy-pasteable claim command. You can pipe this into your shell or an LLM's tool loop directly.

Machine-readable output

For programmatic use, pass --json to get structured output:

$ hence task next plan.spl --json
{
  "agent": "alice",
  "assigned": [
    {
      "task": "write-tests",
      "status": "ready",
      "claim_cmd": "hence task claim write-tests plan.spl"
    },
    {
      "task": "update-docs",
      "status": "ready",
      "claim_cmd": "hence task claim update-docs plan.spl"
    }
  ],
  "other_ready": [
    { "task": "api-review", "assigned_to": "bob" }
  ]
}

Claiming a Task

Claiming signals to other agents and the board that you are actively working on a task. It moves the task from READY to IN PROGRESS and records your agent identity in the plan file.

# Claim a task
hence task claim write-tests plan.spl

# Claim as a specific agent (overrides HENCE_AGENT)
hence task claim write-tests plan.spl --agent alice

What claiming does to the plan file

The plan file is the single source of truth — there is no separate database or server tracking state. When you claim a task, hence appends a (claims ...) block directly to plan.spl:

;; appended by: hence task claim write-tests plan.spl
(claims write-tests alice "2026-02-24T14:32:00Z")

The reasoner reads this fact on every subsequent evaluation. The derived conclusion in-progress-write-tests causes the task to appear in the IN PROGRESS column and suppresses it from hence task next output for other agents.

Releasing a claim

If you claimed a task but cannot finish it — the requirements changed, you are handing it off, or you simply picked the wrong task — use unclaim to release it back to READY:

# Release the claim, putting the task back to READY
hence task unclaim write-tests plan.spl

Unclaiming appends an (unclaims ...) fact that defeats the earlier (claims ...) block. The plan file grows but never loses history — you can always see who claimed and unclaimed tasks over time.

Asserting Facts While Working

Assertions are how agents communicate discoveries, intermediate results, and verdicts to each other — and to downstream plan logic. Instead of Slack messages or external ticket comments, agents write facts directly into the plan file where the reasoner can act on them.

Adding a simple fact

# Assert that a condition is now true
hence task assert '(given tests-passing)' plan.spl

# Tag the assertion with the task you're working on
hence task assert '(given coverage-above-80)' plan.spl --task write-tests

# Multiple facts in one session
hence task assert '(given security-review-approved)' plan.spl
hence task assert '(given no-critical-vulnerabilities)' plan.spl

Each assertion appends a (given ...) fact to the plan file. The reasoner picks it up immediately on the next evaluation. If a downstream task had a readiness rule waiting on tests-passing, it will now appear as READY on the board.

Adding a rule

Agents can also assert new rules, not just facts. This is useful when you discover a condition that should change the plan's logic going forward:

# Assert a new defeasible rule
hence task assert '(normally skip-load-testing given staging-unavailable)' plan.spl

# Assert a rule with multiple conditions
hence task assert \
  '(normally assign-to-hotfix-devops given task-hotfix given production-incident)' \
  plan.spl

Rule assertions let agents dynamically reshape the plan as the project evolves. The plan is not a static document — it is a living knowledge base that agents contribute to.

Common assertion patterns

Blocking a Task

Sometimes a task cannot proceed due to external factors: a dependency on a third party, a production incident, or an unanswered design question. Rather than leaving it in READY or abandoning the claim, mark it explicitly blocked with a human-readable reason.

# Mark a task as blocked with an explanation
hence task block deploy-staging "waiting on infra team to provision the environment" plan.spl

# Unblock when the impediment is resolved
hence task unblock deploy-staging plan.spl

A blocked task appears in the BLOCKED column of the board with its reason displayed. Other agents can see at a glance what is impeding progress without having to ask. The reason is stored in the plan file as a string alongside the (blocked ...) fact.

$ hence plan board plan.spl
+--------------+--------------+--------------+--------------+--------------+
|  BACKLOG     |   READY      | IN PROGRESS  |  BLOCKED     |    DONE      |
+--------------+--------------+--------------+--------------+--------------+
|loadtest      |              |api @alice    |deploy        |setup         |
|tests         |              |docs @bob     |              |              |
+--------------+--------------+--------------+--------------+--------------+

Tasks: 2 backlog, 0 ready, 2 in-progress, 1 blocked, 1 done

When you unblock a task, hence appends an (unblocked ...) fact that defeats the earlier (blocked ...) conclusion. The task returns to whatever status the other rules conclude — typically READY if all its dependencies are satisfied.

Multi-Agent Coordination

hence is designed from the ground up for multiple agents working on the same plan simultaneously. There is no locking, no contention, and no need to serialize agent actions through a central coordinator. The plan file is append-only: agents only ever add new facts, never modify or delete existing ones.

How concurrent writes are handled

Because the plan file is append-only and facts are monotone (adding a fact never invalidates prior reasoning except through explicit defeat), two agents writing simultaneously produce no logical conflict. Even if a raw file merge produces a file with interleaved lines, the reasoner parses each fact independently and re-derives all conclusions from scratch.

In practice, concurrent appends on a local filesystem are safe. When using hence.run hosted plans, the remote applies a sequenced log so concurrent writes are ordered without data loss.

Viewing all agent assignments

# See every task's current assignment across all agents
hence task assign plan.spl

refactor-auth    → alice       (in progress)
api-review       → bob         (in progress)
write-tests      → claude      (in progress)
update-docs      → alice       (ready, unassigned)
deploy-staging   → (unassigned) (blocked)

hence task assign shows the full derived assignment picture: who is working on what, what is ready but unclaimed, and what is blocked. Use this as your coordination dashboard when running a team of agents.

Board-level visibility

The board always shows current claim ownership. Agents do not need to communicate out-of-band to know what others are doing — the plan file is the single source of truth, and the board reflects it in real time.

$ hence plan board plan.spl
+--------------+--------------+--------------+--------------+--------------+
|  BACKLOG     |   READY      | IN PROGRESS  |  BLOCKED     |    DONE      |
+--------------+--------------+--------------+--------------+--------------+
|deploy        |              |api @alice    |              |setup         |
|              |              |api-review @b.|              |              |
|              |              |write-test @c.|              |              |
+--------------+--------------+--------------+--------------+--------------+

Tasks: 1 backlog, 0 ready, 3 in-progress, 0 blocked, 1 done

Reading the Board

The kanban board produced by hence plan board has five columns. Understanding what each column means helps you diagnose stuck projects and understand task dependencies at a glance.

Board view options

The board command supports several output formats for different use cases:

# Default kanban-style view
hence plan board plan.spl

# Dependency tree view — shows parent/child relationships
hence plan board plan.spl --tree

# DAG view — shows full directed acyclic graph of dependencies
hence plan board plan.spl --dag

# Machine-readable JSON
hence plan board plan.spl --json

The --tree flag renders a hierarchy useful for seeing at a glance which tasks unlock which:

$ hence plan board plan.spl --tree

setup-repo         [DONE]
└── add-ci         [DONE]
    └── refactor-auth  [IN PROGRESS]
        └── write-tests    [READY]
            └── deploy-staging  [BLOCKED]
                └── load-testing    [BACKLOG]

Viewing Plan Status

Beyond the board, hence provides several commands for inspecting the current state of a plan in different levels of detail.

hence plan status

Dumps all derived conclusions from the reasoner. This is the raw logical output — every fact the reasoner has concluded given the current plan contents. Useful for debugging why a task is or is not in a particular state.

$ hence plan status plan.spl

Derived conclusions:

  task-setup-repo
  task-add-ci
  task-refactor-auth
  task-write-tests
  task-deploy-staging
  task-load-testing
  completed-setup-repo
  completed-add-ci
  in-progress-refactor-auth
  claims-refactor-auth-alice
  ready-write-tests
  assign-to-write-tests-alice
  blocked-deploy-staging
  ... (and so on)

hence plan summary

A high-level progress overview: counts of tasks in each state, completion percentage, and which agents are currently active.

$ hence plan summary plan.spl

Plan: Backend Refactor Sprint
Progress: 2/6 tasks done (33%)

  Done:         2  (setup-repo, add-ci)
  In Progress:  3  (refactor-auth, api-review, write-tests)
  Ready:        0
  Blocked:      1  (deploy-staging)
  Backlog:      1  (load-testing)

Active agents: alice, bob, claude

hence plan board --dag

The DAG view renders the full dependency graph as a directed acyclic graph. Each node is a task and each edge represents a dependency. Useful for understanding the critical path.

$ hence plan board plan.spl --dag

setup-repo ──→ add-ci ──→ refactor-auth ──→ write-tests ──→ deploy-staging ──→ load-testing
                    ╲                     ╱
                     ──→ api-review ─────

hence.run Hosted Plans

When agents are running on different machines — different developer laptops, cloud VMs, CI runners — you need a way to share the plan file without manual copying. hence.run provides hosted plan storage so any agent anywhere can participate in the same plan.

Publishing a plan

# Publish your local plan to hence.run
hence remote new plan.spl

Published: https://hence.run/p/abc123
Share this URL with other agents.

The returned URL is the canonical identifier for the plan. All commands that accept a local .spl path also accept a https://hence.run/p/TOKEN URL:

# Another agent on a different machine — same commands, remote URL
export HENCE_AGENT=bob
hence task next https://hence.run/p/abc123
hence task claim api-review https://hence.run/p/abc123
hence task assert '(given api-schema-approved)' https://hence.run/p/abc123
hence task complete api-review https://hence.run/p/abc123

Copying a remote plan locally

If you want to work with a remote plan as a local file — to edit rules, run the REPL, or work offline — copy it down with hence remote cp:

# Download the remote plan to a local file
hence remote cp https://hence.run/p/abc123 local.spl

# Work locally
hence plan board local.spl
hence repl local.spl

# Copy local changes back to the remote
hence remote cp local.spl https://hence.run/p/TOKEN

Listing known remote plans

# List all remote plans you've interacted with
hence remote ls

  https://hence.run/p/abc123   Backend Refactor Sprint    (last synced: 2 min ago)
  https://hence.run/p/def456   Frontend Migration          (last synced: 1 hour ago)

P2P Plans

hence supports a second sharing mode alongside hence.run: fully decentralized peer-to-peer plans. Instead of a server-issued token, a P2P plan is identified by a four-word BIP-39 passphrase. Anyone who knows the passphrase can join the plan; no account or network service is required.

Creating a P2P plan

Pass --p2p to hence remote cp when copying a local plan. hence generates a random passphrase and creates a local encrypted replica:

# Publish a local plan as a P2P plan
hence remote cp sprint.spl --p2p

abandon-ability-able-about

Share this passphrase with other agents.
Use it anywhere you would use a local .spl file.

The passphrase is the plan's permanent identifier. Share it with collaborators by any channel. All plan data is end-to-end encrypted — the passphrase is both the address and the key.

Using a P2P plan

Pass the passphrase (bare or as a hence:// URI) wherever you would normally pass a .spl file:

# Every hence command accepts a passphrase as the plan argument
export HENCE_AGENT=alice

hence plan board abandon-ability-able-about
hence task next abandon-ability-able-about
hence task claim setup abandon-ability-able-about
hence task complete setup abandon-ability-able-about

# Or using the hence:// URI scheme (equivalent)
hence task next hence://abandon-ability-able-about

On each read command, hence pre-syncs with any available peers (up to 2 s) to fetch the latest state. On each write command, hence post-syncs (up to 5 s) to push your changes out. Commands work offline using the local cached replica when no peers are reachable.

Exporting to a local file

# Download the current state of a P2P plan to a local file
hence remote cp abandon-ability-able-about local.spl

# Upload a local file's forms into a P2P plan (syncs first, then appends)
hence remote cp local.spl abandon-ability-able-about

Persistent sync daemon

For long-running deployments — a fleet of agents on separate hosts, or a plan that needs to stay current between commands — start the persistent daemon:

# Start the P2P sync daemon for all registered plans (runs in foreground)
hence remote serve

Listening on /ip4/0.0.0.0/tcp/4001
Syncing 2 plans...

The daemon maintains a live libp2p swarm. Peers discover each other via mDNS on the local network and via the Kademlia DHT for cross-network discovery. When a peer announces new forms, the daemon syncs immediately via an encrypted request-response exchange.

Stopping management of a P2P plan

# Remove a P2P plan from this machine (pass passphrase, or pipe it from stdin)
hence remote forget abandon-ability-able-about

Removed local replica. Other peers still retain their copies.

hence remote forget deletes the local encrypted replica and clears cached credentials. Other peers are unaffected and continue syncing.

hence.run vs P2P: choosing a mode

The REPL for Interactive Exploration

The hence REPL provides an interactive query session against a plan's logic. It is the fastest way to debug why a task is or is not ready, understand how rules interact, and explore the consequences of hypothetical facts.

# Start an interactive session against a plan
hence repl plan.spl

hence repl — type :help for commands, :quit to exit

> query ready-write-tests
  true  (derived via assign-to-write-tests-alice, task-write-tests, agent-alice)

> query in-progress-refactor-auth
  true  (derived via claims-refactor-auth-alice, task-refactor-auth)

> why blocked-deploy-staging
  true
  rule: normally blocked-deploy-staging given staging-unavailable
  support: (given staging-unavailable) — asserted by alice at 2026-02-24T10:15:00Z

> assume staging-available
  Hypothetically assuming: staging-available
  Now querying with this extra fact...

> query blocked-deploy-staging
  false  (staging-available defeats staging-unavailable block rule)

> :quit

REPL commands

Putting It All Together

Here is a complete agent session — from identity setup through multiple task completions — showing how the commands compose in practice:

# 1. Set identity once for the session
export HENCE_AGENT=claude

# 2. Orient: what plan are we working on?
hence plan info plan.spl
hence plan summary plan.spl

# 3. See the full picture
hence plan board plan.spl

# 4. Find MY tasks
hence task next plan.spl
#   → write-tests   [READY]   hence task claim write-tests plan.spl
#   → update-docs   [READY]   hence task claim update-docs plan.spl

# 5. Claim the first task
hence task claim write-tests plan.spl

# 6. Do the work (run test suite, verify coverage, etc.)
npm test
#   ... all tests pass, coverage at 87% ...

# 7. Record findings
hence task assert '(given tests-passing)' plan.spl --task write-tests
hence task assert '(given coverage-above-80)' plan.spl --task write-tests

# 8. Mark the task done
hence task complete write-tests plan.spl

# 9. Loop — find the next task (update-docs may still be there, or
#    new tasks may have unlocked due to tests-passing)
hence task next plan.spl

# 10. Claim the next task
hence task claim update-docs plan.spl

# ... and so on until no tasks remain assigned to us ...

hence task next plan.spl
#   → No tasks currently assigned to claude. All done or waiting on others.

# Check overall plan progress
hence plan summary plan.spl

Remote workflow (multi-machine)

# Machine A — plan author publishes the plan
hence remote new sprint.spl
#   → https://hence.run/p/abc123

# Machine B — first agent joins
export HENCE_AGENT=alice
hence task next https://hence.run/p/abc123
hence task claim setup https://hence.run/p/abc123
# ... work ...
hence task complete setup https://hence.run/p/abc123

# Machine C — second agent joins (independently)
export HENCE_AGENT=claude
hence task next https://hence.run/p/abc123
#   → setup is now DONE; write-tests is now READY (unlocked)
hence task claim write-tests https://hence.run/p/abc123

Quick Reference

Continue reading: Supervision covers how to set up agent supervisors that monitor task health and enforce liveness guarantees. LLM Integration covers embedding hence commands into LLM agent prompts and tool loops. See the CLI Reference for every flag and option.