https://github.com/flyingrobots/xyph
The Causal Operating System for Agentic Orchestration
https://github.com/flyingrobots/xyph
agentic-os ai causal-ai warp-graphs
Last synced: 5 months ago
JSON representation
The Causal Operating System for Agentic Orchestration
- Host: GitHub
- URL: https://github.com/flyingrobots/xyph
- Owner: flyingrobots
- License: apache-2.0
- Created: 2026-02-16T01:00:23.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-16T02:30:58.000Z (5 months ago)
- Last Synced: 2026-02-16T08:46:27.970Z (5 months ago)
- Topics: agentic-os, ai, causal-ai, warp-graphs
- Language: JavaScript
- Homepage:
- Size: 461 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
```text
██████
██████
████████ ███████████████ ███████ ██████ █████████ ██████ ██████
██████ ███████ ██████ ██████ █████ ████ █████ █████ █████████
█████ █████ ██████ ██████ ████ ████ ██████ ████ █ ███████
████████ ██████ ██████ ████ ███ ███████ ████ █ ███████
███████████ █████ █████ ████████ ███████ ██████ ███████
██████ ███████ ██████████ ██████████████████ ██████ ███████
████████ ███████ ████████ ██████ ██████████ ██████ ███████
██████ ██████
██████ ██████
██████ ██████
```
# XYPH ([/ˌzɪf/](https://ipa-reader.com/?text=%CB%8Cz%C9%AAf))
**The Causal Operating System for Agentic Orchestration**
XYPH is a planning compiler where the project roadmap is a living, deterministic graph. Humans and agents collaborate by reading and writing to that graph — no server, no database, just git.
## How It Works
Everything lives in a single **WARP graph** — a multi-writer CRDT stored in git. Humans decide *what* to build and *why*. Agents figure out *how* and do the work. Nobody sends messages to coordinate; instead, everyone reads and writes to the shared graph. This pattern is called **stigmergy** — coordination through the environment itself.
The rest of this README tells that story through a walkthrough. Ada is a human. Hal is an agent. They're going to build a feature together.
## Getting Started
**Prerequisites:** Node.js v20+, Git
```bash
npm install
```
Every participant has an identity set via the `XYPH_AGENT_ID` environment variable. Humans use the `human.` prefix; agents use `agent.`:
```bash
export XYPH_AGENT_ID=human.ada # Ada is a human
export XYPH_AGENT_ID=agent.hal # Hal is an agent
```
Verify everything is working:
```bash
npx tsx xyph-actuator.ts status --view roadmap
```
## Walkthrough: Building a Feature Together
### 1. Ada Declares an Intent
Every piece of work in XYPH must trace back to a human decision. Ada starts by declaring an **Intent** — a statement of *why* something should exist. Intents are the sovereign roots of all work; agents cannot create them.
```bash
export XYPH_AGENT_ID=human.ada
npx tsx xyph-actuator.ts intent intent:live-alerts \
--title "Users need real-time notifications" \
--requested-by human.ada
```
This creates an `intent:` node in the graph. Everything built downstream will point back here.
### 2. Ada Plans the Work
Ada groups related work under a **Campaign** — a named collection, like a milestone or epic. Inside the campaign she creates **Quests** — the individual units of work (think tickets or tasks). Each quest belongs to a campaign and is authorized by an intent:
```bash
npx tsx xyph-actuator.ts quest task:notif-001 \
--title "WebSocket event bus" \
--campaign campaign:live-alerts \
--intent intent:live-alerts
npx tsx xyph-actuator.ts quest task:notif-002 \
--title "Toast notification UI" \
--campaign campaign:live-alerts \
--intent intent:live-alerts
```
The chain from quest → campaign → intent is the **Genealogy of Intent**. It's how XYPH enforces that every piece of work traces back to a human decision (Constitution Art. IV).
Ada can also toss a rough idea into the **Inbox** for triage later:
```bash
npx tsx xyph-actuator.ts inbox task:notif-003 \
--title "Maybe: email digest fallback?" \
--suggested-by human.ada
```
And later promote or reject it:
```bash
npx tsx xyph-actuator.ts promote task:notif-003 --intent intent:live-alerts
npx tsx xyph-actuator.ts reject task:notif-003 --rationale "Out of scope for v1"
```
### 3. Hal Sets Up
Hal is a **Causal Agent** — an autonomous participant with its own writer identity in the graph. Before doing any work, Hal generates a cryptographic keypair (one-time setup):
```bash
export XYPH_AGENT_ID=agent.hal
npx tsx xyph-actuator.ts generate-key
```
This creates an Ed25519 private key in `trust/agent.hal.sk` (gitignored) and registers the public key. Hal's completed work will carry a verifiable **Guild Seal** — a cryptographic signature proving who did the work.
### 4. Hal Claims a Quest
Hal checks the roadmap for available work:
```bash
npx tsx xyph-actuator.ts status --view roadmap
```
He sees `task:notif-001` in BACKLOG and volunteers for it using the **Optimistic Claiming Protocol (OCP)** — a pattern where agents claim work optimistically and the graph resolves conflicts via CRDT convergence:
```bash
npx tsx xyph-actuator.ts claim task:notif-001
```
If two agents claim the same quest simultaneously, last-writer-wins. No locks, no race conditions — just deterministic resolution.
### 5. Hal Does the Work
Hal creates a feature branch, implements the WebSocket event bus, and passes quality gates:
```bash
npm run build && npm test
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow.
### 6. Hal Seals the Quest
When the work is done, Hal **seals** the quest. This marks it DONE and produces a **Scroll** — a cryptographic artifact that records *what* was built, *who* built it, and *why* it was authorized:
```bash
npx tsx xyph-actuator.ts seal task:notif-001 \
--artifact abc123def456 \
--rationale "WebSocket bus implemented and tested"
```
The scroll is signed with Hal's Guild Seal and linked to the quest in the graph.
### 7. Ada Checks the Result
Ada opens the dashboard to see the full picture:
```bash
XYPH_AGENT_ID=human.ada ./xyph-dashboard.tsx
```
She can see the campaign, its quests, who claimed them, and the sealed scrolls — all traceable back to her original intent. The lineage view (`status --view lineage`) shows the complete Genealogy of Intent from scroll → quest → campaign → intent → human.
She can also audit that every quest has a valid chain:
```bash
npx tsx xyph-actuator.ts audit-sovereignty
```
## Dashboard
The interactive TUI provides a visual browser for the WARP graph:
```bash
XYPH_AGENT_ID=human.yourname ./xyph-dashboard.tsx
```
| Key | Action |
|---------|-----------------------------------------------|
| `Tab` | Cycle views (roadmap → lineage → all → inbox) |
| `↑↓` | Navigate |
| `Space` | Fold/unfold campaign · open quest detail |
| `r` | Refresh snapshot |
| `?` | Help modal |
| `p` | Promote inbox task (human.* only) |
| `x` | Reject inbox task |
| `Esc` | Close modal |
| `q` | Quit |
## CLI Reference
All commands run via `npx tsx xyph-actuator.ts `.
| Command | What it does |
|---------|-------------|
| `status --view ` | View the graph (`--include-graveyard` to see rejected) |
| `intent --title "..." --requested-by human.` | Declare a sovereign intent |
| `quest --title "..." --campaign --intent ` | Create a quest |
| `inbox --title "..." --suggested-by ` | Suggest a task for triage |
| `promote --intent ` | Promote inbox task to backlog |
| `reject --rationale "..."` | Reject to graveyard |
| `reopen ` | Reopen a rejected task |
| `claim ` | Volunteer for a quest (OCP) |
| `seal --artifact --rationale "..."` | Mark done; produces a guild-sealed scroll |
| `generate-key` | Generate an Ed25519 Guild Seal keypair |
| `audit-sovereignty` | Verify all quests have a Genealogy of Intent |
## Architecture
```text
src/
├── domain/ # Pure domain models (Quest, Intent, ApprovalGate, ...)
├── ports/ # Interfaces (RoadmapPort, DashboardPort, IntakePort, ...)
├── infrastructure/
│ └── adapters/ # git-warp adapters (WarpRoadmapAdapter, WarpDashboardAdapter, ...)
└── tui/ # Ink-based interactive dashboard
├── Dashboard.tsx # Root component (landing, help, tab routing)
├── HelpModal.tsx # ? key help overlay
├── QuestDetailPanel.tsx # Reusable quest detail panel
├── Scrollbar.tsx
├── logos/ # ASCII art logos (1–10.txt)
└── views/
├── LandingView.tsx # Startup screen with WARP stats
├── RoadmapView.tsx # Campaign/quest tree with fold/unfold
├── LineageView.tsx # Genealogy of Intent tree
├── AllNodesView.tsx # Full graph node browser
└── InboxView.tsx # Triage inbox (Gmail-style)
# Root entry points
xyph-actuator.ts # CLI for graph mutations (quest, intent, seal, ...)
xyph-dashboard.tsx # Interactive TUI entry point
```
## Milestones
| # | Milestone | Status |
|---|-----------|--------|
| 1 | BEDROCK — foundations, repo, actuator | ✅ DONE |
| 2 | HEARTBEAT — coordinator daemon + ingest pipeline | ✅ DONE |
| 3 | TRIAGE — rebalancer + origin context | ✅ DONE |
| 4 | SOVEREIGNTY — cryptographic guild seals, approval gates, genealogy of intent | ✅ DONE |
| 4+ | POWERLEVEL™ — full orchestration pipeline refactor | ✅ DONE |
| 5 | WARP Dashboard TUI — interactive graph browser | 🚧 IN PROGRESS |
| 6 | WEAVER — DAG scheduling + dependency graph ([RFC_001](docs/canonical/RFC_001_AST_DRIVEN_INGEST.md)) | ⬜ PLANNED |
| 7 | ORACLE — intent classification + policy engine | ⬜ PLANNED |
| 8 | FORGE — emit + apply phases | ⬜ PLANNED |
## Constitution
Every mutation must obey the [CONSTITUTION.md](docs/canonical/CONSTITUTION.md). Key articles:
- **Art. II** — No cycles in the dependency graph (hard reject)
- **Art. IV** — Every quest must have a Genealogy of Intent (sovereign `intent:` root)
- **Art. IV.2** — Critical path changes require an ApprovalGate signed by a human
### Canonical Docs
The `docs/canonical/` directory contains the foundational specifications:
- [ARCHITECTURE.md](docs/canonical/ARCHITECTURE.md) — System architecture
- [GRAPH_SCHEMA.md](docs/canonical/GRAPH_SCHEMA.md) — Node and edge type definitions
- [ORCHESTRATION_SPEC.md](docs/canonical/ORCHESTRATION_SPEC.md) — Planning pipeline phases
- [SECURITY_AND_TRUST.md](docs/canonical/SECURITY_AND_TRUST.md) — Cryptographic trust model
- [VISION_NORTH_STAR.md](docs/canonical/VISION_NORTH_STAR.md) — Project vision
---
Built with Ω¹ by [FLYING ROBOTS](https://github.com/flyingrobots)
¹ Ω (Omega) — the final convergence point of the WARP graph; symbolizes deterministic state resolution.