Hypha: a TypeScript agent harness where the DomainPack is the product and the runtime stays generic
Harness-oriented agent system framework for production-grade LLM agent applications
At a glance
- What is it?
- Hypha splits an LLM agent into an Agent Core and a Production Harness, with product behaviour declared in a DomainPack rather than hard-coded. The design is coherent and the cache taxonomy is unusually precise, but the public material is a v1.0.x README and a versioned guide, not a set of worked failure reports.
- Who is it for?
- Adopt Hypha if you are building more than one agent product on shared infrastructure and you want policy, checkpointing and replay to live in the runtime rather than in each product. Do not adopt it if you need a single ReAct loop with a handful of tools, because the DomainPack compilation step and the event/artifact evidence model are overhead you will pay without using.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 12 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Hypha addresses is agent reuse across products, not agent construction
Most TypeScript agent libraries optimise for getting one agent to call one tool. Hypha is aimed at the situation that follows: you have shipped a coding agent and now need a finance agent and a legal agent, and you do not want three divergent copies of approval logic, checkpoint handling and audit trails. The README frames this as two cooperating layers, an Agent Core and a Production Harness, with product-specific behaviour declared through a DomainPack rather than hard-coded into the runtime. The stated goal is that a coding agent, finance agent, legal agent or research agent can share the same Core and Harness while changing the DomainPack, capability bindings, policies, evaluation contracts and domain-specific state. That is a real organisational problem and it is not the problem most agent frameworks solve. The target reader is an engineer who already knows what a ReAct loop is and is now responsible for the operational surface around it: who approved this tool call, what happens when the process dies mid-plan, and how you reconstruct what the agent did last Tuesday.
The Agent Core and Production Harness split, and what actually crosses the boundary
The division of labour is stated plainly in the architecture table. The Agent Core owns reasoning and ReAct, planning, tool selection, Memory access, and model and context orchestration. The Production Harness owns FSM execution, Event and checkpoint control, policy and approval, continuation, recovery, audit, and replay. Read that boundary carefully, because it is the whole design argument. The Core is allowed to be non-deterministic and exploratory; the Harness is where decisions become bounded and event-backed. A DomainPack then compiles tasks, workflows, capabilities, prompts, Memory, policy, evaluation and output contracts into that shared runtime. The consequence is that the interesting engineering happens at compile time, in the DomainPack, and the runtime is deliberately boring. The topic list confirms the shape of the bet: finite-state-machine, event-sourcing, policy-engine, human-in-the-loop, replay. Those are infrastructure concerns borrowed from workflow systems, applied to LLM agents. Whether that is the right trade depends on your failure tolerance. A single-user script does not need an FSM. A system that moves money or files tickets does.
Six cache layers with different invalidation rules, and why that is the most specific part of the design
The README claims cache is a first-class control plane rather than a single response-cache feature, and it justifies that by enumerating six layers with distinct validity boundaries. Serving Cache holds an exact normalized model response, bounded by model and provider identity, the normalized request, scope, TTL and response validity. Thinking Cache holds a reasoning node, path or reusable subgraph, bounded by model and provider, reasoning strategy and version, prompt blocks, tool schema, inference parameters and scope. WorkCache holds event-derived typed agent work, bounded by source-event provenance, dependency and revision closure, scope, validity state and future demand. Tool and Execution Cache holds eligible read-only tool results or deterministic execution results, bounded by capability revision, Policy, external-state evidence, workspace or environment snapshot, idempotency and scope. Memory and Context Cache holds memory search and assembled context projections, bounded by memory scope, mutation generation, source revision, provenance and context policy. Prefix and KV Cache holds prompt-prefix blocks, provider prefixes or backend KV segments, bounded by model or backend, Agent/Session/Domain scope, prompt dependencies and prefix or KV revision. The point of listing them separately is that invalidating an exact response is not the same operation as invalidating a reasoning subgraph, and treating them as one cache is how stale agent state gets shipped. The README is explicit that the cache plane is a disposable projection: it can accelerate execution but can never become authority or replace Event, Artifact, receipt or checkpoint evidence.
Cache trees, semantic trees, and the lookup structure that is not the source of truth
The mechanism for storing these layers is a cache tree with three node kinds. A typed root partitions reusable artifacts by type. Compact parent nodes route lookups by hash prefix. Full logical keys sit at the leaves. The README states that new leaves can be inserted without rebuilding unrelated branches, and stale leaves can be invalidated locally. That gives you partial invalidation without a full rebuild, which matters when one tool's capability revision changes and you do not want to discard every cached plan that happened to touch it. The physical tree is described as a lookup structure only; Event and Artifact evidence remain the source of truth. WorkCache extends the same pattern into semantic cache trees for agent execution, with PlanTree named in the truncated material as reusing plans. The README cuts off mid-sentence at that table, so the full set of semantic trees is not confirmable from what is available here. Treat the PlanTree entry as an example of the pattern rather than a complete inventory, and check the versioned guide for the rest.
Getting it running: npm packages, the versioned guide, and where the setup instructions are thin
The current public release is v1.0.1, published 2026-08-14, with v1.0.0 published roughly an hour earlier the same day. The README states that v1.0.1 aligns 15 packages named @codesoul-co/hypha-*, and links to npm under the org codesoul-co. Installation is therefore from npm, not from a source checkout, though the README does not print an install command in the material available here. The documented entry points are the versioned user guide at codesoul-co.github.io/Hypha, the official website at hypha.code-soul.com, and the v1.0.1 release page. The README says the guide includes an API atlas for every package, custom FSM control, and a complete composition example. That composition example is the thing to read first, because a DomainPack compiles tasks, workflows, capabilities, prompts, Memory, policy, evaluation and output contracts, and the shape of that compilation is the learning curve. What is missing from this material is anything resembling a quickstart: no install command, no minimal DomainPack snippet, no config keys. I cannot state the package names beyond the @codesoul-co/hypha-* pattern, and I cannot give you a config key because none appears in the supplied text. If you need a five-minute hello-world before evaluating, this README will not give it to you.
Where Hypha is the wrong choice, and what the cache plane cannot promise
The framework is built for governed, durable, reusable domain agents, and that phrasing is a scope statement. If your agent is a single ReAct loop with a few tools and no approval step, the Harness is dead weight: you will declare a DomainPack, compile it, and then run an FSM that has one state. The event-sourcing model also imposes a discipline on how you describe work. The README is firm that cache state can never become authority and cannot replace Event, Artifact, receipt or checkpoint evidence. That is a correct safety property, but it means you cannot treat the cache as your record of what happened. If you were hoping to reconstruct agent history from cached responses, you cannot, by design. There is a second limitation worth naming: the material describes the architecture in terms of what each layer is responsible for, not in terms of what happens when a layer misbehaves. There is no failure report, no recovery walkthrough, no worked example of a checkpoint resuming after a crash. Recovery and replay are listed as Harness responsibilities, and the guide is said to cover custom FSM control, but the README does not demonstrate the recovery path. Until you read that guide section, you are taking the durability claim on structure rather than on evidence.
How Hypha differs from running a ReAct agent library directly
The obvious alternative is a general-purpose agent library that gives you a ReAct loop, tool definitions and a memory store, and leaves orchestration to your application code. The difference is not features, it is where state lives. In that model, your application owns the loop, so approval checks, retries and audit logging are code you write around each call, and they diverge the moment you build a second agent. In Hypha, those concerns are declared in the DomainPack and executed by the Harness, so the same policy and checkpoint machinery applies to every agent compiled against it. The cost is that you must express your task and workflow in Hypha's terms before anything runs, and you inherit its FSM and event model whether or not your domain needs them. A second alternative worth considering is a durable workflow engine with an LLM step inside it. That inverts the layering: the workflow engine owns execution and recovery, and the model call is one activity among many. Hypha's bet is that reasoning and execution deserve a shared runtime rather than a boundary between two systems, which is why the Cache and Reuse Plane spans reasoning, tools, Memory, execution and inference rather than sitting next to them.
Licence, package surface, and the upgrade cost you are signing up for
Hypha is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. That is a permissive licence, and it does not carry the copyleft obligations of the GPL family. It also does not carry the source-availability or network-use conditions that some other licences impose. This is a description of the licence identifier, not legal advice; if you are redistributing Hypha inside a product, read the licence text and your own counsel's guidance. The practical cost sits in the package surface. The README states that v1.0.1 aligns 15 packages under the @codesoul-co/hypha-* namespace. Fifteen packages means fifteen version constraints to reconcile, and the two releases listed here landed about an hour apart on the same day, which suggests a coordinated publish process rather than independent package lifecycles. If you pin to the aligned set, upgrading is a single decision. If you pin individual packages, you own the compatibility matrix. The README does not describe a versioning policy or a deprecation window, so that is another item to confirm in the guide before you depend on the namespace in production.
Editorial conclusion
Adopt Hypha if you are building more than one agent product on shared infrastructure and you want policy, checkpointing and replay to live in the runtime rather than in each product. Do not adopt it if you need a single ReAct loop with a handful of tools, because the DomainPack compilation step and the event/artifact evidence model are overhead you will pay without using. Before committing, verify three things against the versioned guide: which of the 15 @codesoul-co/hypha-* packages you actually need, what the DomainPack compilation contract requires of your task and workflow declarations, and whether the recovery path from a checkpoint has a documented example you can reproduce locally.
Community notes