Hypagraph

Give your coding agent a plan it can execute, inspect, and prove.

Hypagraph is a graph-workflow extension for the Pi coding agent. It turns an ordinary coding request or an existing implementation plan into an explicit workflow of tasks, checks, decisions, and bounded iteration regions.

You describe the work. Hypagraph builds and runs the graph.

It keeps canonical workflow state in Pi, controls which work is ready, records evidence, runs deterministic checks, parses declared reports, evaluates typed gates, tracks bounded iteration, and shows the live graph while the agent works.

flowchart LR
    A[Prepare candidate] --> B[Evaluate result]
    B --> C{Typed success?}
    C -- Yes --> D[Publish result]
    C -- No --> E[Next bounded iteration]
    E -. feedback .-> A

Loading

Why use Hypagraph?

Coding agents often begin with a reasonable plan and lose structure as the session grows. Hypagraph makes the plan executable.

• Automatic authoring: ordinary requests and supplied plans become the smallest useful graph.
• Graph-backed goals: /hypagoal atomically creates one root goal and its canonical workflow from ordinary prose.
• Dependency control: only ready work can start.
• Evidence-backed completion: task results and checks remain attached to durable attempts.
• Typed routing: gates select branches from declared facts.
• Bounded iteration: regions have typed success, hard limits, optional progress metrics, patience, and explicit outcome policy.
• Trusted evaluation: metric reports can declare validity, feedback limits, evaluation budgets, trust, and evaluator integrity.
• Independent components: disconnected loop regions keep independent state.
• Safe recovery: session state restores without repeating completed external effects.
• Live inspection: Pi shows workflow, goal-control, loop, check, and evaluator state.

Install

Install directly from GitHub:

pi install git:github.com/Hypabolic/Hypagraph

Restart Pi after installation. Hypagraph loads its extension and bundled skill automatically.

Update an existing installation:

pi update git:github.com/Hypabolic/Hypagraph

Install only for the current project:

pi install -l git:github.com/Hypabolic/Hypagraph

Start a Hypagoal

Open Pi in a repository and enter an ordinary prose objective:

/hypagoal Add an inspect command that reports the current workflow without starting execution.

Hypagraph then:

1. preserves the objective exactly;
2. inspects relevant repository context;
3. compiles the smallest useful canonical workflow;
4. validates the complete definition;
5. creates the workflow, initial readiness, and workflow-local goal lifecycle in one durable event batch;
6. reports the workflow ID, goal ID, revision, goal-control state, ready work, and authoring advisories.

The atomic creation operation does not start a task, run a check, or invoke an executor. After the authoring turn ends, the graph-aware controller selects one canonical action and dispatches it in one lane.

Hypagraph uses one generic action-dispatch model. Every selected action records a selected event, a dispatched event, and one terminal event. A model-lane action stores one state-bound continuation request and sends one Pi follow-up. A deterministic-lane action needs no reasoning, so the controller runs it directly: a ready gate is one reducer command, and a ready check runs through the existing durable check lifecycle. The controller selects again after the deterministic action resolves.

The current v0.6 product surface allows one root workflow and one root goal in the active Pi session. Replacing that root requires explicit confirmation bound to the exact current workflow, goal, revision, sequence, snapshot hash, session generation, and branch generation. The workflow domain itself remains able to represent separate workflow aggregates for the later goal-family architecture.

The controller selects from all runnable root components in stable definition order. An event-backed scheduler ordinal rotates selection when multiple components remain runnable. The scheduler ordinal advances for every selected action in every lane, so round-robin fairness does not depend on model usage. A disconnected branch or independent loop does not lose eligibility because another component produced the latest event. Each queued follow-up is bound to the goal, workflow, revision, sequence, snapshot hash, session generation, branch generation, node, and loop where applicable. A stale follow-up cannot change canonical state.

A Hypagoal can also declare a maximum substantive-turn count, a maximum token count, or both. Pi assistant usage is normalized from input, output, cache-read, and cache-write tokens. Each delivered model-lane continuation is charged once through a durable turn event before another model-lane action can be dispatched. Budget exhaustion stops autonomous continuation as budget_limited; it does not mark the workflow successful.

Consumed turns count model turns only. A deterministic action consumes no turn. /hypagoal status reports the scheduled action count next to the charged model-turn count and states this rule, so a user who compares node count with turn count does not think that work is missing. A turn-budget stop ends automatic continuation in every lane.

Deterministic work still has a bound. Loop iteration limits, patience, evaluation budgets, and check retry limits remain unchanged, and the controller stops after 64 consecutive deterministic dispatches in one pass.

When the selected action belongs to a bounded iteration region, the continuation includes canonical loop and evaluation context. It reports the current iteration, typed success condition, current and best accepted metrics, progress direction, patience, invalid-evaluation count, evaluation-attempt budget, purpose, trust, feedback mode, and failure policy when these values exist. It does not expose protected evaluator commands, paths, hashes, raw reports, standard output, standard error, hidden assertions, or holdout details.

Evaluation validity, numeric progress, and typed success remain separate. An invalid evaluation cannot update the best metric or satisfy success. The same root selector continues to rotate across disconnected branches and independent loop components. A loop does not own the next turn because it produced the latest event.

A session reload or branch change clears any queued continuation and persists a paused goal without dispatching work. Restore also closes a deterministic dispatch which a stopped host left pending, so a lost dispatch cannot block a later selection. Review canonical state and use /hypagoal resume to continue. Resume re-checks the current budget and runnable graph before it queues another state-bound follow-up.

Start a workflow

Open Pi in a repository and describe the work in normal language.

Move the remaining modules from the old parser to the new parser in safe batches.
Run compatibility checks after each batch. Stop when no old-parser imports remain,
then update the migration record.

Keep changes inside src/parser/** and tests/parser/**.

The bundled skill:

1. inspects the repository;
2. identifies the requested result and constraints;
3. finds relevant files and checks;
4. compiles the request into the smallest correct Hypagraph workflow;
5. validates the graph before execution;
6. runs only ready work;
7. revises the graph when new evidence makes the current plan incorrect.

A small request stays small. Hypagraph does not create a gate, loop, or extra node unless the work needs it.

You can also paste an issue, checklist, or implementation plan. Hypagraph preserves the intent while converting sequence, dependencies, conditions, checks, and repeated work into executable graph structure.

Pi commands

Command	Action
/hypagoal <objective>	Inspect repository context and atomically create one root graph-backed goal.
/hypagoal status	Show the exact objective, workflow phase, goal state, active or next work, budgets, loops, evaluations, blockage, revision state, and stop reason.
/hypagoal pause [reason]	Pause the root goal through the canonical lifecycle.
/hypagoal resume	Resume a paused or recoverable blocked goal after budget and runnable-path validation.
/hypagoal cancel [reason]	Cancel the root goal without implying success.
/hypagoal graph	Open or focus the graph pane with root-goal details.
/hypagraph	Show the active workflow.
/hypagraph loop	Show canonical loop, progress, evaluation, and outcome state.
/hypagraph graph	Open or focus the live graph pane.
/hypagraph graph toggle	Open or close the graph pane.
/hypagraph graph focus	Focus the graph pane.
/hypagraph graph close	Close the graph pane.
/hypagraph check active	Show the active deterministic check.
/hypagraph check cancel [node-id]	Cancel an active check.
/hypagraph history	Show the most recent page of the event timeline.
/hypagraph history <sequence>	Replay canonical state to one stored sequence and compare it with live state.
/hypagraph history <lane>	Show one timeline lane. A lane is workflow, goal, dispatch, node, check, evaluation, fact, route, loop, or unknown.
/hypagraph history revisions	Show revision segments and discarded results.
/hypagraph explain	Explain the goal decision and every node.
/hypagraph explain <node-id>	Explain why one node is or is not runnable.

Graph pane controls:

Key	Action
Arrow keys or h, j, k, l	Move between nodes.
Enter	Show selected-node details.
Home	Select the active node.
r	Select the ready frontier.
+ or -	Change graph density.
Escape	Release focus on a wide terminal.
q	Close the pane.

What a workflow can contain

Tasks

A task describes bounded agent work. It can declare acceptance criteria, required evidence, dependencies, and writable paths.

Command checks

A command check runs a deterministic local command without a shell. It supports timeouts, cancellation, bounded output, retry policy, environment allowlists, artifacts, and typed result facts.

Report checks

Report checks run a bounded producer command and parse one declared report through a versioned deterministic adapter.

Supported report formats include:

• Vitest JSON;
• ESLint JSON;
• Istanbul coverage summaries;
• scalar metric JSON.

Report paths remain inside the workspace. Reads are bounded. Malformed reports cannot publish facts.

File assertions

A file assertion can verify:

• existence or absence;
• exact size;
• SHA-256;
• bounded text content.

Protected evaluator file instruments reject symbolic links, use bounded descriptor reads, and verify the opened file identity before accepting content.

Git assertions

A Git assertion uses a fixed command and argument allowlist. It can verify:

• clean state;
• current branch;
• current revision;
• exact revision;
• changed-path sets;
• protected paths unchanged from an exact base revision.

Workflow definitions cannot supply arbitrary Git arguments.

Gates

A gate evaluates a typed condition against facts produced by earlier nodes. It persists one selected route and skips the other route.

Bounded iteration regions

A loop is a first-class bounded iteration region. It is not a repair command and repair is not its default purpose.

The same model can represent:

• refinement and optimization;
• bounded batch processing;
• search and repeated evaluation;
• reconciliation and migration;
• polling with a hard stop;
• check-and-repair as one pattern among many.

Each region declares:

• entry and evaluation boundaries;
• typed success;
• feedback edges;
• a hard iteration limit;
• optional numeric progress and patience;
• optional evaluation validity;
• explicit failure policy: fail-workflow, block-dependants, or record-and-continue.

A loop can connect to the wider graph or run as a disconnected top-level component. Its facts, attempts, routes, progress, validity, and resets remain independent from unrelated regions.

Trusted evaluation contracts

A numeric score is not automatically a trustworthy measure of progress.

Hypagraph keeps these concepts separate:

• success: may the region complete?
• progress: is this valid result better than the prior best result?
• validity: may the runtime use this observation?
• purpose: is this development, probe, or holdout evaluation?
• trust: is the evaluator transparent, protected, or isolated?

A metric evaluator can declare:

• scalar mappings into typed facts;
• aggregate or bounded-diagnostic feedback;
• total and per-purpose evaluation budgets;
• typed validity;
• protected file and Git instruments;
• evaluator version and fingerprint;
• transparent or protected trust.

An invalid result remains available for audit but cannot:

• complete the loop;
• update the accepted metric;
• replace the best result;
• change patience.

Evaluation budget is consumed when the external evaluator starts. Failed, invalid, timed-out, cancelled, interrupted, errored, and retried attempts count.

Protected evaluator output is not exposed in normal Pi messages. Protected local evaluation proves declared artifact integrity; it does not hide readable answers. Production isolated evaluation remains planned.

Session safety and recovery

Hypagraph stores accepted event batches in the Pi session. The event stream is the source of truth, and the current workflow is a deterministic projection.

A root Hypagoal creation is stored in this order:

workflow defined
    |
    v
initial ready nodes
    |
    v
goal started
    |
    v
one durable append

The active Pi state changes only after the complete creation append succeeds. Failed validation, sequence conflicts, branch changes, stale replacement confirmation, or snapshot mismatch expose no partial candidate state.

A deterministic check is stored in this order:

store check start
    |
    v
run bounded external effect
    |
    v
store raw result and evidence
    |
    v
publish declared facts
    |
    v
store verification and loop decision

Hypagraph does not start an external check when it cannot first store the check-start event.

Restore rebuilds canonical state only. It does not queue a continuation, dispatch model work, invoke an executor, or rerun completed commands, reports, assertions, or integrity checks. It closes interrupted attempts or resumes verification from stored observations. When an active Hypagoal is restored after a reload or branch change, Hypagraph persists an explicit pause and requires /hypagoal resume before another continuation.

Check artifacts are stored under .hypagraph/check-artifacts. Large output stays outside the Pi event stream and is referenced by artifact identity.

Current status

Implemented:

• automatic graph authoring skill;
• atomic root /hypagoal creation and hypagoal_start model surface;
• workflow-local goal lifecycle and workflow-derived terminal state;
• graph-aware root continuation with deterministic component selection;
• state-bound continuation requests and stale-delivery rejection;
• durable substantive-turn and token accounting;
• deterministic turn-limit and token-limit stops;
• reload and branch-change pause with explicit /hypagoal resume;
• task, check, and gate nodes;
• live terminal graph pane;
• typed facts and deterministic routes;
• durable event-based state and replay;
• command, report, metric, file, and Git checks;
• cancellation, retry, restore, and stale-result protection;
• generic bounded iteration regions;
• numeric progress, best-result tracking, and patience;
• independent loop components and explicit failure policies;
• evaluation validity and invalid-observation limits;
• protected feedback and event-backed evaluation budgets;
• evaluator purpose, trust, integrity, version, and fingerprint surfaces;
• loop-aware Hypagoal continuation from canonical iteration and evaluation state;
• protected evaluator redaction in model-visible prompts and check output;
• realistic multi-iteration continuation with independent-component fairness;
• deterministic blocker classification and one non-weakening automatic workflow revision;
• complete /hypagoal status, pause, resume, cancel, and graph controls;
• compact lifecycle messages and explicit typed stop reasons;
• narrow and wide root-goal terminal rendering;
• integrated v0.6 product-path dogfood across loops, evaluation, gates, reload recovery, revision, and canonical completion;
• a generic action-dispatch model with a deterministic, a model, and an executor lane;
• a scheduler ordinal which advances for every selected action, independent of model usage;
• direct deterministic dispatch of a ready gate and a ready check, without a model turn;
• an explicit maximum for consecutive deterministic dispatches in one controller pass;
• turn accounting which counts model turns only, and a product surface which says so;
• interrupted-dispatch recovery on reload, so a lost dispatch cannot block a later selection;
• a typed event timeline with lane classification, paging, and a lane filter;
• replay of canonical state to any stored sequence, with a comparison against live state;
• canonical explanations for why a node or a goal is not runnable;
• /hypagraph history, /hypagraph explain, and the matching hypagraph_read views;
• a replay mode of the graph pane;
• revision segments, discarded-result reporting, and a projection seam for later family and executor namespaces;
• integrated v0.7 dogfood for deterministic dispatch and inspectable history;
• the interaction node kind, the awaiting_response status, and a typed answer which publishes declared facts.

Next:

• the remaining interaction and approval node work: presentation effects, typed routing, deadlines, and reload;
• code nodes which run a definition-time program in a sandbox;
• external effects with explicit requested, observed, and indeterminate states and restart reconciliation;
• goal families and bounded child Hypagoals;
• isolated executors, worktree integration, and bounded concurrency;
• dynamic fan-out regions, only when a branch count is derived at run time;
• ACP and named direct agent adapters.

Develop locally

Development requires Node.js 22 or later.

git clone https://github.com/Hypabolic/Hypagraph.git
cd Hypagraph
npm install
npm run check
pi -e ./extensions/hypagraph.ts

CI runs on Ubuntu, macOS, and Windows with Node.js 22 and 24.

Documentation

• Product and technical specification
• Execution roadmap
• Deterministic orchestration plan
• Trigger and command surface plan
• Automatic graph authoring model
• Trusted evaluation contracts
• Hypagoal vertical slices
• Goal-family and concurrent-execution architecture
• Current session handoff
• M3.1 deterministic parser adapters
• M4 bounded iteration plan
• v0.5 dogfood record
• M6A deterministic dispatch plan
• M6A dogfood record
• M6B event history plan
• M6B dogfood record
• v0.7 release notes
• M6.1 interaction and approval nodes plan
• Comparison with script orchestration products