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 plus its Prolog library tree.

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

By default the script installs to:

• ~/.local/bin/hence — the executable
• ~/.local/lib/plt/ — the bundled Prolog library (do not move this separately)

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 and LIB_DIR to override the defaults. The binary and library must be installed together — the binary locates the Prolog runtime relative to its own path.

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

Manual installation

If you prefer not to pipe scripts from the internet, or need to install on an air-gapped machine:

1. Download the archive for your platform from https://files.anuna.io/hence/latest/
2. Extract the archive: tar xzf hence-*.tar.gz
3. Copy the contents, preserving the directory structure:

   cp bin/hence ~/.local/bin/hence
   cp -r lib/plt ~/.local/lib/plt

4. Make the binary executable: chmod +x ~/.local/bin/hence

Verify the installation

hence --version

You should see output like:

hence 0.4.1

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      |
+--------------+--------------+--------------+--------------+--------------+
|implement     |design @dev   |              |              |              |
|test          |              |              |              |              |
+--------------+--------------+--------------+--------------+--------------+

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

The board tells you at a glance: task-design is ready and assigned to dev; task-implement and task-test are in BACKLOG because their prerequisites have not yet completed.

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

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:a3f9b2c1
agent:alice
evaluator:ed25519:b4e8f3d2
PeerId: 12D3KooW...

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=alice):

task:   setup
label:  Environment setup
status: ready
reason: normally (ready setup) — no defeaters active

hence task next does three things in one query:

1. Evaluates all (ready T) conclusions under defeasible logic
2. Filters to tasks where (assigned T alice) holds
3. Excludes tasks that are already (done T) or (in-progress T)

The word assigned here is derived — the plan's (normally (assigned setup alice)) 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 records a (claimed setup alice) fact in 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 setup project.spl

   Output:

   claimed: setup
   by:      alice
   at:      2026-02-24T10:15:03Z

   The plan file now contains:

   (given claimed setup alice "2026-02-24T10:15:03Z")

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 (given env-validated), 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 setup project.spl

   Output:

   completed: setup
   by:        alice
   at:        2026-02-24T10:42:17Z

   The plan file gains:

   (given done setup alice "2026-02-24T10:42:17Z")

5. Check the board again

   hence plan board project.spl

   The board now reflects the updated state:

   +--------------+--------------+--------------+--------------+--------------+
   |  BACKLOG     |   READY      | IN PROGRESS  |  BLOCKED     |    DONE      |
   +--------------+--------------+--------------+--------------+--------------+
   |              |review @bob   |              |              |setup         |
   +--------------+--------------+--------------+--------------+--------------+
   
   Tasks: 0 backlog, 1 ready, 0 in-progress, 0 blocked, 1 done

   Completing setup asserted (done setup ...). The reasoner re-evaluated the readiness rule for review — its guard (done setup) is now satisfied — and promoted it to READY.

6. Check what unlocked

After completing a task, run hence task next again (this time as bob) to see what became available:

HENCE_AGENT=bob hence task next project.spl

Output:

task:   review
label:  Review findings
status: ready
reason: normally (ready review) if (done setup) — guard satisfied

The reason field is the defeasible rule that fired. It includes the guard condition that was satisfied and confirms no defeater overrode the conclusion. This is the same information you get from hence query explain, surfaced inline for convenience.

If you were running a multi-agent system, bob's agent loop would be polling hence task next on a schedule. As soon as alice completes setup, the next poll by bob returns review — 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-setup project.spl

Output:

Conclusion: (ready setup)
Status:     HOLDS

Derivation:
  Rule:     (normally (ready setup))
  Defeaters: none
  Therefore: (ready setup) holds by default

The explanation traces the defeasible derivation. For a task with a guard:

hence query explain ready-review project.spl

Output after setup is complete:

Conclusion: (ready review)
Status:     HOLDS

Derivation:
  Rule:     (normally (ready review) if (done setup))
  Guard:    (done setup)
    ↳ (given done setup alice "2026-02-24T10:42:17Z") — fact in plan
  Defeaters: none
  Therefore: (ready review) holds

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-review project.spl

Output (before setup is complete):

Conclusion: (ready review)
Status:     DOES NOT HOLD

Analysis:
  Rule:     (normally (ready review) if (done setup))
  Guard:    (done setup)
    ↳ no matching fact or derived conclusion found
  Result:   guard unsatisfied — rule does not fire

  No other rules conclude (ready review).
  Conclusion cannot be derived.

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 setup-then-review 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-name   "Minimal Example")
(meta description "Setup followed by review. Demonstrates the full task lifecycle.")
(meta version     "1.0.0")

; ── Agents ────────────────────────────────────────────────────────
(given agent alice)
(given agent bob)

; ── Tasks ─────────────────────────────────────────────────────────
(given task setup)
  (meta task setup label       "Environment setup")
  (meta task setup description "Install dependencies and verify the environment is healthy.")

(given task review)
  (meta task review label       "Review findings")
  (meta task review description "Review what setup produced and approve or flag for rework.")

; ── Readiness ─────────────────────────────────────────────────────
; setup is immediately ready — no prerequisites
(normally (ready setup))

; review is ready only after setup is marked done AND env-validated was asserted
(normally (ready review)
  if (done setup)
  and (given env-validated))

; ── Assignment ────────────────────────────────────────────────────
(normally (assigned setup  alice))
(normally (assigned review bob))

Full lifecycle walkthrough

1. Initialise and inspect

   hence plan board minimal.spl

   Expected: setup READY, review BLOCKED.

2. Alice claims and works on setup

   export HENCE_AGENT=alice
   hence task next   minimal.spl    # → setup
   hence task claim  setup minimal.spl

3. Alice asserts her findings

   After verifying the environment, alice records the key fact that review's readiness rule depends on:

   hence task assert '(given env-validated)' minimal.spl

   She can also record richer structured findings:

   hence task assert \
     '(given node-version "20.11.0")' \
     '(given all-deps-installed)' \
     minimal.spl

4. Alice completes setup

   hence task complete setup minimal.spl

5. Bob sees review is now ready

   export HENCE_AGENT=bob
   hence task next minimal.spl    # → review

6. Bob explains why review is ready

   hence query explain ready-review minimal.spl

   The explanation traces both guard conditions: (done setup) satisfied by alice's completion fact, and (given env-validated) satisfied by alice's assertion.

7. Bob claims, does the review, and completes

   hence task claim    review minimal.spl
   # ... conduct the review ...
   hence task assert '(given review-approved)' minimal.spl
   hence task complete review minimal.spl

8. Final board state

   hence plan board minimal.spl

   Expected output:

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

   Both tasks done. The plan is complete.

What's next