Getting Started

This guide walks you from a fresh machine to a working two-agent task cycle. By the end you will have installed hence, written a minimal plan, claimed a task, asserted findings, and seen the reasoner explain its conclusions.

The full cycle takes about ten minutes. You do not need any external services — everything runs locally against a plain .spl file.

1. Installation

One-line installer

The recommended method fetches and runs the official install script, which detects your platform, downloads the correct archive, and installs the binary.

curl -fsSL https://files.anuna.io/hence/latest/install.sh | bash

By default the script installs to:

• ~/.local/bin/hence — the executable

Make sure ~/.local/bin is on your PATH. If it is not already, add it to your shell profile:

# bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Custom install location

Pass INSTALL_DIR to override the default install location.

INSTALL_DIR=/usr/local/bin \
  curl -fsSL https://files.anuna.io/hence/latest/install.sh | bash

From source

Requires Rust (stable toolchain).

git clone https://codeberg.org/anuna/hence.git
cd hence
make install

This builds a release binary and installs it to ~/.local/bin. Override with make install PREFIX=/usr/local.

Verify the installation

hence --version

You should see output like:

hence 0.6.7

If the command is not found, confirm that the install directory is on your PATH and that you have opened a new shell session or sourced your profile.

2. Your first plan

A plan is a plain-text .spl file containing defeasible rules that describe your project's tasks, when they are ready, and who should perform them. The hence reasoner evaluates these rules on demand — there is no running daemon, no database, and no sync step. Every query reads the file fresh.

Initialize a template

hence plan init project.spl

This writes a starter template to project.spl. Open it in any editor — it looks like this:

; =============================================================================
; Project
; =============================================================================

(meta plan
  (title "Project")
  (status "active")
  (created "2026-02-24"))

; --- AGENTS ---
; Set HENCE_AGENT env var or use --agent flag with lifecycle commands
(given agent-dev-available)

; --- TASKS ---
(given task-design)
(given task-implement)
(given task-test)

; --- TASK METADATA ---
(meta task-design
  (description "Design phase — define architecture and approach")
  (acceptance "Design document reviewed and approved"))
(meta task-implement
  (description "Implement the design")
  (acceptance "Code complete, builds cleanly, unit tests pass"))
(meta task-test
  (description "Integration and end-to-end testing")
  (acceptance "All tests pass, no critical issues"))

; --- DEPENDENCIES ---
; design has no dependencies
(given no-deps-design)

; --- READINESS RULES ---
; design is ready immediately
(normally r-ready-design
  (and task-design no-deps-design)
  ready-design)

; implement is ready after design is completed
(normally r-ready-implement
  completed-design
  ready-implement)

; test is ready after implement is completed
(normally r-ready-test
  completed-implement
  ready-test)

; --- ASSIGNMENT RULES ---
(normally r-assign-design
  (and ready-design agent-dev-available)
  assign-to-design-dev)

(normally r-assign-implement
  (and ready-implement agent-dev-available)
  assign-to-implement-dev)

(normally r-assign-test
  (and ready-test agent-dev-available)
  assign-to-test-dev)

What the template contains

View the task board

The board command renders a kanban-style view of all tasks and their current states:

hence plan board project.spl

With a fresh plan (no facts asserted yet) it looks like this:

+--------------+--------------+--------------+--------------+--------------+
|  BACKLOG     |   READY      | IN PROGRESS  |  BLOCKED     |    DONE      |
+--------------+--------------+--------------+--------------+--------------+
|              |design @dev   |              |              |              |
+--------------+--------------+--------------+--------------+--------------+

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

The board tells you at a glance: design is ready and assigned to dev. Tasks implement and test have no fired readiness rules yet — their prerequisites haven't completed — so they don't appear on the board until they become actionable.

3. Set your identity

hence does not have a login system. Your identity is an environment variable. The reasoner uses it to filter tasks assigned to you and to sign any facts you assert.

export HENCE_AGENT=dev

To make this permanent, add it to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Cryptographic identity

Simple name-based identity works fine for local single-user use, but hence also supports cryptographic agent identifiers. Each agent has an Ed25519 keypair; the public key is embedded in fact assertions so that any reader can verify who wrote what.

hence agent whoami

Output:

supervisor:ed25519:xfRAzZFG
agent:ed25519:xfRAzZFG
evaluator:ed25519:3jB3fzQT
PeerId: 12D3KooWP96WBe...

The first time you run hence agent whoami, hence generates a keypair for the current HENCE_AGENT name and stores it in ~/.local/share/hence/keys/. Subsequent runs load the existing key.

When multiple agents share a plan via hence.run, facts are stored in the canonical agent:PUBKEY format — the human-readable name followed by a colon and the hex-encoded Ed25519 public key. This means you can have two agents both named alice on different machines without collision; the public keys distinguish them.

4. Find your tasks

With your identity set, ask the reasoner what you should work on:

hence task next project.spl

Output (with HENCE_AGENT=dev):

Next actions for dev:
  1. design @dev — hence task claim design project.spl --agent dev

hence task next does three things in one query:

1. Evaluates all readiness conclusions under defeasible logic
2. Filters to tasks where the assignment literal holds for the current agent
3. Excludes tasks that are already claimed or completed

The assignment is derived — the plan's (normally r-assign-design ...) rule fired with no defeaters, so the reasoner concluded the assignment. You do not query a database; you query the logical consequences of the rules and accumulated facts in the .spl file.

5. Claim and complete a task

Claiming a task appends a (claims agent:dev ...) block to the plan file. Other agents querying the same plan will see it as in-progress. This is how concurrent agents avoid stepping on each other's work.

1. Claim the task

   hence task claim design project.spl

   Output:

   Added: (claims agent:dev :at "2026-02-24T10:15:03Z" ...)
     (given claim-v1-design)
     (normally r-cl-state-v1-design claim-v1-design state-claimed-v1-design)
     (normally r-cl-chain-v1-design state-claimed-v1-design claimed-design)
   
   Next actions for dev:
     (no actions available)

   The plan file now contains that (claims ...) block, and subsequent queries will see claimed-design as a derived conclusion.

2. Do the actual work

   This is the step that varies — write code, run a script, gather data, call an API. hence does not supervise what you do between claim and complete. For supervised LLM agent execution, see Supervision.

3. Assert findings

   While working, you may discover facts that other tasks depend on. Record them with hence task assert. The argument is a valid SPL fact expression:

   hence task assert '(given found-something)' project.spl

   You can assert multiple facts in one call:

   hence task assert \
     '(given dependency-version "2.3.1")' \
     '(given env-validated)' \
     project.spl

   These facts are appended to the plan file as given clauses and are immediately visible to any subsequent query — whether made by you, another agent, or an LLM reasoning about the plan state.

   Tip

   Assertions are the primary output channel for agents. If a later task's readiness rule references a fact, asserting it here is what unblocks that task. Think of assertions as structured findings, not just log messages.
4. Complete the task

   hence task complete design project.spl

   Output:

   Added: (claims agent:dev :at "2026-02-24T10:42:17Z" (given completed-design))
   
   Next actions for dev:
     1. implement @dev — hence task claim implement project.spl --agent dev

   The plan file gains that (claims ...) block, and completed-design is immediately provable by the reasoner.

5. Check the board again

   hence plan board project.spl

   The board now reflects the updated state:

   +--------------+--------------+--------------+--------------+--------------+
   |  BACKLOG     |   READY      | IN PROGRESS  |  BLOCKED     |    DONE      |
   +--------------+--------------+--------------+--------------+--------------+
   |              |implement @dev|              |              |design        |
   +--------------+--------------+--------------+--------------+--------------+
   
   Tasks: 0 backlog, 1 ready, 0 in-progress, 0 blocked, 1 done

   Completing design caused completed-design to become provable. The reasoner re-evaluated the readiness rule for implement — its guard is now satisfied — and promoted it to READY.

6. Check what unlocked

After completing a task, run hence task next again to see what became available:

hence task next project.spl

Output:

Next actions for dev:
  1. implement @dev — hence task claim implement project.spl --agent dev

The reasoner re-evaluated all readiness rules after completed-design became provable and found implement is now assignable. You get a copy-pasteable claim command immediately.

If you were running a multi-agent system, agents poll hence task next on a schedule. As soon as one agent completes a task, the next poll by any other agent returns the newly unblocked work — no message passing, no pub/sub, no coordinator process. The plan file is the shared state, and the reasoner is the coordinator.

7. Explain a conclusion

hence can explain why any conclusion holds or does not hold. This is useful for debugging plans, for building operator UIs, and for giving LLMs grounded context about the current plan state.

Why is a task ready?

hence query explain ready-design project.spl

Output:

=== Explanation for: ready-design ===

Contributing Sources (1):
  - unknown:anonymous

Derivation Tree:
  - ready-design [via r-ready-design, from unknown:anonymous]
    - task-design [via f2, from unknown:anonymous]
    - no-deps-design [via f5, from unknown:anonymous]

The explanation shows contributing sources and a derivation tree: which rule fired (r-ready-design) and which atoms it depended on (task-design, no-deps-design). For a task with a dependency guard:

hence query explain ready-implement project.spl

Output after design is complete:

=== Explanation for: ready-implement ===

Contributing Sources (1):
  - unknown:anonymous

Derivation Tree:
  - ready-implement [via r-ready-implement, from unknown:anonymous]
    - completed-design [via f15, from unknown:anonymous]

Why is a task not ready yet?

hence query why-not explains why a conclusion does not hold — which guards are unsatisfied, which defeaters are active, or which rules are simply absent.

hence query why-not ready-implement project.spl

Output (before design is complete):

===============================================================
Why not: ready-implement
===============================================================

To prove +∂ ready-implement, these conditions must hold:

(1) Definitely provable (+Δ): [FAIL]
    Not definitely provable

  -> Checking defeasible proof path...

(2) Negation not definitely provable (-Δ ¬q): [PASS]
    No strict rule derives ¬ready-implement

(3) Applicable rule exists: [FAIL]
    Rules exist but none are applicable (missing prerequisites)

    Rules for this literal:
      [FAIL] r-ready-implement: [r-ready-implement] completed-design => ready-implement
        Missing:
          * completed-design


========= FAILURE POINT =========
Rules exist but prerequisites are not satisfied.

========= SUGGESTIONS =========
  1. Prove or assert 'completed-design' to enable rule

Both explain and why-not support --json for machine-readable output, and both work on any derived predicate in your plan — not just readiness. You can explain assignment conclusions, custom domain predicates, or any other rule head.

8. Minimal working example

Here is a complete self-contained plan for a two-task design-then-implement cycle. Copy it to a file and work through the full lifecycle shown below.

The plan file

; minimal.spl — a complete two-task plan

; ── Meta ──────────────────────────────────────────────────────────
(meta plan minimal
  (title "Minimal Example")
  (description "Design followed by implementation. Demonstrates the full task lifecycle."))

; ── Agents ────────────────────────────────────────────────────────
(given agent-dev-available)

; ── Tasks ─────────────────────────────────────────────────────────
(given task-design)
(given task-implement)

; ── Readiness ─────────────────────────────────────────────────────
; design is immediately ready — no prerequisites
(normally r-ready-design
  (and task-design no-deps-design)
  ready-design)

; implement is ready only after design is completed
(normally r-ready-implement
  (and task-implement completed-design)
  ready-implement)

; ── Assignment ────────────────────────────────────────────────────
(normally r-assign-design
  (and ready-design agent-dev-available)
  assign-to-design-dev)

(normally r-assign-implement
  (and ready-implement agent-dev-available)
  assign-to-implement-dev)

; ── Task metadata ─────────────────────────────────────────────────
(meta task-design
  (description "Design the feature")
  (acceptance "Design doc approved"))

(meta task-implement
  (description "Implement according to the design")
  (acceptance "All tests pass"))

Full lifecycle walkthrough

1. Initialise and inspect

   hence plan board minimal.spl

   Expected: design READY (assigned to dev); implement not yet shown (prerequisite incomplete).

2. Claim and work on design

   export HENCE_AGENT=dev
   hence task next   minimal.spl    # → design
   hence task claim  design minimal.spl

3. Assert findings

   After completing the design work, record any facts other tasks may depend on:

   hence task assert '(given design-approved)' minimal.spl

   You can assert multiple facts in one call:

   hence task assert \
     '(given api-contract-frozen)' \
     '(given design-approved)' \
     minimal.spl

4. Complete design

   hence task complete design minimal.spl

5. See implement is now ready

   hence task next minimal.spl    # → implement

6. Explain why implement is ready

   hence query explain ready-implement minimal.spl

   The explanation shows that completed-design is now provable, which satisfies the readiness guard for task-implement.

7. Claim, implement, and complete

   hence task claim    implement minimal.spl
   # ... do the implementation work ...
   hence task assert '(given tests-passing)' minimal.spl
   hence task complete implement minimal.spl

8. Final board state

   hence plan board minimal.spl

   Expected output:

   +--------------+--------------+--------------+--------------+--------------+
   |  BACKLOG     |   READY      | IN PROGRESS  |  BLOCKED     |    DONE      |
   +--------------+--------------+--------------+--------------+--------------+
   |              |              |              |              |implement     |
   |              |              |              |              |design        |
   +--------------+--------------+--------------+--------------+--------------+
   
   Tasks: 0 backlog, 0 ready, 0 in-progress, 0 blocked, 2 done

   Both tasks done. The plan is complete.

What's next