Hypha
An event-backed TypeScript framework that turns LLM agents into governed, durable, auditable production systems via DomainPacks.
- Source repo
- CodeSoul-co/Hypha
- Stars
- ★ 452
- Last updated
- 5d ago
- License
- Apache-2.0
- Primary language
- TypeScript
- FA score
- 55/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- High · needs real infrastructure
- You'll need
- Typical use
- Platform teams that need internal domain agents (e.g. finance reconciliation or legal review) to be replayable and auditable
- Not a fit if
- Solo developers who want zero-infrastructure setup without MongoDB and Redis
- Teams that only need a thin LLM script and no event-sourced recovery
- Small teams unwilling to own policy, approval, and cache-consistency runtime duties
- Website
- codesoul-co.github.io/Hypha ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-15latest release v1.0.1 (2026-08-14)
- Source review
- 55/100 · Major gaps
What does this agent do, and when should you use it?
Hypha is an open-source TypeScript framework split into an Agent Core and a Production Harness. The Core handles ReAct reasoning, planning, tool selection, Memory access and model/context orchestration; the Harness turns those decisions into bounded, event-backed execution with FSM control, policy and approval, checkpoints, recovery, replay and audit. Product behavior is declared in a DomainPack (YAML, JSON or TypeScript) rather than hard-coded, so one runtime can be instantiated as coding, finance, legal or research agents. State is derived from Events and content-addressed Artifacts, and every cache layer is a disposable projection that can never authorize a side effect, skip policy, or advance the FSM. It ships as 15 version-aligned @codesoul-co/hypha-* npm packages alongside an Express API server and an example CLI, under Apache-2.0 for source code.
On startup the Express server composes the canonical Event authority and durable execution graph; session-command, ReAct continuation, timer, recovery and reconciliation workers run an initial sweep before readiness. A DomainPack is loaded into a DomainPackRegistry via LocalDomainPackLoader and compiled with compileDomainPackToHarnessedSystem into fsmProcess, harnessedSystem, agentPatch, bindings, sessionInitialization, dependencySnapshot and processHash. The trusted composition layer must then register Skills, bind Tool contracts to local, HTTP, plugin, execution or MCP adapters, approve exact MCP capability revisions, and persist the dependency snapshot alongside Run events. Execution follows DomainPack → validated bindings → framework-owned Harness FSM → bounded ReAct quantum → governed Tool/MCP/Memory/Execution activity → Event, receipt and Artifact evidence → projection, continuation, recovery, replay and evaluation. The HTTP API exposes /api/v1/chat and /chat/stream, /runtime/runs/:runId with events, replay, audit and regression projections, /tools, /tool-approvals, /mcp, /memory, /skills and /workflows, plus OpenAPI 3.1 generated from the mounted Express routes; the CLI offers login, chat --stream, tools, skills and workflows. Caching is layered into Serving, Thinking, WorkCache, Tool/Execution, Memory/Context and Prefix/KV, configured through HYPHA_SERVING_CACHE and HYPHA_WORKCACHE with memory, sqlite or redis stores.
- Platform teams that need internal domain agents (e.g. finance reconciliation or legal review) to be replayable and auditable
- SaaS vendors running several vertical agents on one runtime and swapping only the DomainPack
- Compliance-sensitive teams whose tool calls require approval, policy and durable Event/Artifact evidence
- Workflow owners needing long-running tasks with checkpoints, bounded recovery and human review
- Application developers who want to customize prompts, skills and workflows through DomainPacks instead of patching the core
- Infrastructure teams deploying agents on a private or local stack and reusing Redis/SQLite caches to cut cost
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
docker run -d --name hypha-mongodb -p 27017:27017 mongo:8docker run -d --name hypha-redis -p 6379:6379 redis:7-alpine
- Environment variables
HYPHA_OWNER_PASSWORDJWT_SECRETHYPHA_LLM_DEFAULT_MODELOPENAI_API_KEYHYPHA_MEMORY_CONFIG_PATH- Config files
.env.example.envconfig.yaml- Runtime
- Node.js 22
- Install notes cover
- Docker
How do you install or deploy this agent?
You need Node.js 22 or newer, npm, MongoDB and Redis, and at least one configured model provider or reachable local model endpoint.
git clone https://github.com/CodeSoul-co/Hypha.git
cd Hypha
npm ci
cp .env.example .envOptionally run disposable local MongoDB and Redis containers:
docker run -d --name hypha-mongodb -p 27017:27017 mongo:8
docker run -d --name hypha-redis -p 6379:6379 redis:7-alpineConfigure identity and a model provider in .env; keep credentials out of config.yaml and source control:
[email protected]
HYPHA_OWNER_PASSWORD=replace-with-a-private-password
JWT_SECRET=replace-with-at-least-32-random-characters
HYPHA_LLM_DEFAULT_PROVIDER=openai
HYPHA_LLM_DEFAULT_MODEL=gpt-4o-mini
OPENAI_API_KEY=your-provider-keyBuild once and start the compiled server in a production environment:
npm run lint
npm run typecheck
npm run build
npm test
NODE_ENV=production npm startNote that npm run test:release intentionally fails when real Memory or Execution services and credentials are unavailable.
How do you use this agent?
Start the dev server and check liveness plus the traffic gate:
npm run dev
curl -fsS http://127.0.0.1:3000/api/v1/health
curl -fsS http://127.0.0.1:3000/api/v1/readyLog in and issue a streamed chat with the example CLI:
npm run cli -- login --email [email protected]
npm run cli -- chat "Explain the active runtime" --stream
npm run cli -- tools
npm run cli -- skills
npm run cli -- workflowsLoad and compile a DomainPack as a library, then register the compiled system in your composition layer:
import {
applyDomainAgentPatch,
compileDomainPackToHarnessedSystem,
DomainPackRegistry,
LocalDomainPackLoader,
} from '@codesoul-co/hypha-domain';
const registry = new DomainPackRegistry();
await new LocalDomainPackLoader({
directories: ['configs/domain-packs'],
}).loadInto(registry);
const domainPack = registry.get('domain.minimal', '0.0.0');
if (!domainPack) throw new Error('DomainPack not found');
const compiled = compileDomainPackToHarnessedSystem(domainPack, {
agentRef: { id: 'agent.default', version: '1.0.0' },
taskSchemaId: 'task.minimal',
workflowId: 'workflow.minimal',
sessionProfileId: 'session.local',
memoryProfileId: 'memory.local',
});
const agent = applyDomainAgentPatch(
{
id: 'agent.default',
version: '1.0.0',
name: 'Default Agent',
modelAlias: 'default-chat',
},
compiled.agentPatch
);Narrow capabilities per workflow state, for example read-only tools plus a required skill:
states:
- id: Research
goal: Collect bounded evidence.
allowedTools: [common.search]
allowedSkills: [skill.context-enrichment]
requiredSkills: [skill.context-enrichment]
allowedMCPProfiles: [mcp.local]
permissionScopes: [search.query]
policyRefs: [policy.readonly]
timeoutPolicy:
timeoutMs: 30000
onTimeout: fail
retryPolicy:
maxAttempts: 2To turn on reuse, set HYPHA_SERVING_CACHE=memory|sqlite|redis and HYPHA_WORKCACHE=off|memory|sqlite|redis, and point HYPHA_MEMORY_CONFIG_PATH at a validated Memory profile set.
What are this agent's strengths and limitations?
- Clear Core/Harness split with concrete components for FSM execution, checkpoints, recovery, replay and audit rather than prompt-level discipline
- DomainPack is a documented product boundary: compilation yields fsmProcess, bindings and dependencySnapshot so one runtime hosts many domain agents
- Cache layering with an explicit 'reuse without authority' invariant, including tests that cache on and off must preserve source-of-truth semantics
- Governed tool and MCP invocation with version approval, plus per-state allowedTools, requiredSkills, timeouts and policies
- Published as 15 version-aligned npm packages with an Express HTTP API, generated OpenAPI 3.1 and a working example CLI
- Requires your own MongoDB and Redis, and the production checklist adds TLS, backups and retention, which is heavier than a single library
- Wide configuration surface across DomainPack, config.yaml, tools.yaml, memory-profiles.yaml and many env vars; misconfiguration can fail readiness
- Release acceptance expects real Memory and Execution providers and fails by design without credentials, so verification costs real setup
- Brand assets are excluded from Apache-2.0, so forks and third-party products must rebrand
- Only an OpenAI model example is shown in the quickstart; other providers need your own configuration and verification
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Hypha This agent | 55 · Major gaps | Self-hosted serviceFree + model costs | ★ 452 | 5d ago | TypeScript | OpenAI API |
| RocketRide | 84 · Good | — | ★ 20k | today | Python | — |
| Swarm | 47 · Major gaps | Agent plugin / skillFree | ★ 754 | 6mo ago | TypeScript | Claude Code |
| Kun Workspace | 57 · Major gaps | Desktop appFree + model costs | ★ 6.4k | 5d ago | TypeScript | ChatGPT · Codex · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
least_privilege: README and tool-mcp-security.md require tool/MCP/file/execution writes to pass policy, approval, idempotency and harness boundaries, and DomainPacks need explicit registration before gaining runtime authority — a documented least-privilege design (2). user_confirmation: docs state write/irreversible capabilities require explicit policy and may require approval, but the sample shows no concrete approval UI or default-deny logic, only documentation assertions (2). data_flow_transparency: README describes Event/Artifact/receipt as source of truth and cache as non-authoritative, with clear layering (2). sensitive_data_handling: the security guide requires credentials outside ToolSpec/DomainPack, forbids auth headers or sensitive paths in events, and mandates auditPolicy.redactPaths; tests verify DLQ records are redacted. However the framework ships no secret manager, leaving that to deployment (2). dependency_security: package.json has an npm audit script and CI runs npm run audit and test:audit-policy, with some pinned versions; but the dependency surface is large and no audit results are provided, so absence of known vulnerabilities cannot be confirmed (2). external_effects: the security guide distinguishes none/read/write/external_effect/irreversible and requires idempotency or receipt reconciliation; known limitations note interrupted writes become conflict without a reconciler (2). rollback: checkpoint, recovery, replay, legacy migration rollback modules and a RecoveryTree exist, but no end-to-end rollback drill is shown in the sample (2). source_attribution: README cites benchmark results without reproducible scripts or data links; the Skill asks for source preservation but framework-level provenance evidence is limited (1).
self_consistency: README architecture matches core/adapters exports, the CLI thin-client positioning, and test assertions such as /ready failing closed (2). dependency_availability: engines require Node>=22, README lists MongoDB/Redis and a model provider as prerequisites, and CI uses mongo:7/redis:7 services; however local adapters depend on the better-sqlite3 native module whose cross-platform availability is not verified in the sample (2). failure_messages: the CLI catches errors and prints code: message, and /ready returns structured component status; but no runtime error taxonomy or user-facing recovery guidance is visible (1).
audience_and_scenarios: README targets developers of production-grade LLM agent applications and gives a DomainPack integration path plus a release-agent example (2). capability_boundaries: docs state DomainPack is the product integration boundary, product logic must not enter core/kernel, and cache cannot authorize side effects (2). trigger_precision: the sample Skill uses only an always trigger; no conditional triggers or conflict resolution rules are shown (1). environment_fit: supports local SQLite/file, Docker, remote HTTP, PostgreSQL and S3 adapters, covering a broad range of environments (2).
information_architecture: README is clearly layered and docs include guides/adr/reference, a sound structure (2). install_notes: Quick start gives Node version, npm ci, .env configuration, docker commands for Mongo/Redis, and health-check commands (2). naming_stability: package names @codesoul-co/hypha-* and version 1.0.1 are consistent, and the CLI version is fixed (2). examples_and_faq: only one release-agent example and a Skill sample exist; no FAQ or broader scenario examples (1). known_limitations: docs/reference/tool-mcp-known-limitations.md lists concrete limits on storage, cache, cancellation, secret management and API-key auth (2). license: the repository root contains the full Apache-2.0 LICENSE and package.json declares it consistently (3). versioning_changelog: README links the v1.0.1 release and UPGRADING.md, but no CHANGELOG content is in the sample (1). maintenance_responsibility: the publisher is unverified and README gives no maintainers, support channel or SLA (1).
output_usability: the framework provides a CLI, REST API, DomainPack compiler outputs and structured output contracts usable directly to build agent products (2). marginal_value: its differentiation is the harness/cache/recovery layer, but the README benchmark beats direct model calls by only about one percentage point, so marginal value evidence is weak (1). cost_benefit: the cache and reuse plane claims API-cost savings, but no verifiable cost data is provided and deployment adds MongoDB/Redis operational cost (1).
claim_traceability: the README benchmark table cites main@ef33263 but provides no dataset, scripts or raw results, so it cannot be traced (1). cross_source_corroboration: test files and CI workflows partially corroborate claims about /ready, command idempotency and zero-skipped MCP tests, but benchmark and cache-benefit claims have no cross-source evidence (1). fact_inference_separation: architecture descriptions and performance claims are interleaved without clear separation of fact from inference (1).
- Publisher identity is not verified by FollowAgents; maintenance responsibility and support channels are unclear, so evaluate before production adoption.
- README benchmark results lack reproducible scripts and raw data and should not be used as a selection basis.
- The framework ships no secret manager; credentials and audit redaction must be configured by the deployer.
- Local adapters depend on the better-sqlite3 native module whose cross-platform availability is not verified in the sample.
- The API-key authentication path is not enabled; deployments must not advertise X-API-Key request authentication.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.0.1 Hypha npm release 1.0.1
Release notes excerpt
Patch release of the @codesoul-co/hypha-* npm line. Fixes since the 1.0.0 publication: - @codesoul-co/hypha-skills now ships the framework built-in skills (context-enrichment, intent-classification) in its tarball and exposes resolveBuiltinSkillsDirectory() (#22). The 1.0.0 tarball could not load built-in skills for npm consumers. - Repository gates: npm audit findings (js-yaml, nanoid) resolved (#23). All 15 packages are published at 1.0.1 with exact-version internal dependencies.View on GitHub ↗ -
v1.0.0 Hypha v1.0.0
Release notes excerpt
Hypha v1.0.0 is the initial stable release of the ReAct + FSM agent-system framework. Highlights: - Application-defined FSM runs from validated FSMProcessSpec values or compiled DomainPack workflows. - FSM topology analysis and governed manual state transitions with policy, revision, lease, fencing, idempotency, terminal events, and replay evidence. - Production harness, DomainPack, provider-neutral memory, storage, tools, skills, MCP, inference, local adapters, serving cache, and testing packages. - OpenAPI 3.1 route inventory and a standalone release consumer example. …View on GitHub ↗
FAQ
Can a cache hit let a tool write, or skip an approval?
Does a DomainPack file become live just by sitting on disk?
Can a custom FSM topology bypass the harness phases?
What has to be running for the server to accept traffic?
Is commercial use allowed?
Is Hypha free?
Is Hypha open source?
Is Hypha safe to use?
Is Hypha still maintained?
Who makes Hypha?
What is Hypha's official website?
Thanks — we use this to improve the page.