XYPH is a graph-native planning and execution system for software and product work. It gives humans and agents one shared place to plan work, claim it, review it, settle it, and keep the full history attached to the work itself.
Instead of splitting coordination across tickets, pull requests, CI logs, chat, and local notes, XYPH keeps the plan in a WARP graph and exposes it through a CLI, a TUI cockpit, and a machine-facing control plane.
Under the hood, XYPH uses git-warp to store its graph in Git. Git provides the content-addressed storage, replication, and offline sync behavior; XYPH provides the workflow model, governance rules, and human/agent operating surfaces.
Use XYPH when you want:
- one shared, durable plan for humans and agents
- offline-first work that still syncs deterministically later
- governance, review, and provenance attached to the work itself
- a machine-readable surface that is as serious as the human-facing one
- graph-native context instead of stitching meaning together from five tools
XYPH is especially useful when work is long-lived, collaborative, and needs an auditable chain from "why does this exist?" to "what shipped?" It is less about chat-style task capture and more about durable coordination and settlement.
If you are new to XYPH, these are the main nouns:
| Term | Meaning |
|---|---|
| Intent | A human declaration of why work should exist |
| Campaign | A container for related work |
| Quest | A unit of work |
| Submission | A review envelope for proposed work |
| Scroll | A sealed artifact emitted when work is settled |
| Suggestion | Advisory content proposed by a human or agent |
| WARP graph | The append-only, multi-writer graph XYPH stores its plan in |
| Worldline | A live or derived continuation of graph history used for inspection or speculation |
The first five terms make up XYPH's Digital Guild workflow vocabulary. They are the product's built-in nouns for planning, execution, review, and settlement.
You can think of XYPH as a planning compiler with a graph-backed runtime:
- A human declares an Intent.
- The work is shaped into Campaigns and Quests.
- Humans and agents read the same graph-backed plan.
- Work is claimed, executed, and submitted for review.
- Reviews, evidence, and settlement decisions are written back to the graph.
- The graph becomes the durable history of what changed, who did it, and why.
A normal graph store is usually concerned with current nodes and edges. XYPH's WARP graph is different:
- it is append-only and history-preserving
- it supports multi-writer offline work
- it converges deterministically when writers sync later
- it gives XYPH one substrate for planning, provenance, review, and speculation
That is why XYPH can treat the graph as the plan instead of as a cache or a reporting layer.
Traditional tools scatter the story:
- tickets hold intent
- branches or PRs hold implementation discussion
- CI holds evidence
- chat holds coordination
- local notebooks hold the rest
XYPH keeps those surfaces graph-native and queryable together.
Prerequisites: Node.js v22+, Git
npm installEvery participant has an identity. Humans use the human. prefix; agents use agent.:
# Set for the session
export XYPH_AGENT_ID=human.ada
# Or persist it
npx tsx xyph-actuator.ts login human.adaIf no identity is set, it defaults to agent.prime.
XYPH resolves its runtime graph at bootstrap:
- local
.xyph.json→ user config~/.xyph/config→ defaults (current repo + graph namexyph)
If the target repo has multiple git-warp graphs, XYPH fails loudly until you set graph.name explicitly. It will not guess.
Verify everything is working:
npx tsx xyph-actuator.ts status --view roadmapCreate one intent and one quest:
export XYPH_AGENT_ID=human.ada
npx tsx xyph-actuator.ts intent intent:demo \
--title "Users need a better notification workflow" \
--requested-by human.ada
npx tsx xyph-actuator.ts quest task:demo-001 \
--title "Add notification preferences screen" \
--campaign none \
--intent intent:demoRead the current plan:
npx tsx xyph-actuator.ts status --view roadmapInspect what you just wrote:
npx tsx xyph-actuator.ts show task:demo-001
npx tsx xyph-actuator.ts history task:demo-001
npx tsx xyph-actuator.ts status --view lineageThat is the core loop: write work into the graph, read it back through XYPH's projections, then act on it through the same system.
Ada is a human. Hal is an agent. They're going to build a feature together.
Every piece of work must trace back to a human decision. Ada starts by declaring an Intent:
export XYPH_AGENT_ID=human.ada
npx tsx xyph-actuator.ts intent intent:live-alerts \
--title "Users need real-time notifications" \
--requested-by human.adaShe groups work under a Campaign and creates Quests authorized by her intent:
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-alertsShe can declare dependencies ("this can't start until that's done"):
npx tsx xyph-actuator.ts depend task:notif-002 task:notif-001She can toss rough ideas into the Inbox for triage later:
npx tsx xyph-actuator.ts inbox task:notif-003 \
--title "Maybe: email digest fallback?" \
--suggested-by human.adaAnd later promote or reject them:
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"Hal generates a cryptographic keypair (one-time setup). His completed work will carry a verifiable Guild Seal:
export XYPH_AGENT_ID=agent.hal
npx tsx xyph-actuator.ts generate-keyThis creates an Ed25519 private key in ~/.xyph/trust/ and registers the public key in the keyring. See Guild Seals for the full deep-dive.
Hal checks the roadmap and volunteers using the Optimistic Claiming Protocol — CRDT convergence resolves conflicts, no locks needed:
npx tsx xyph-actuator.ts status --view roadmap
npx tsx xyph-actuator.ts claim task:notif-001After doing the work, Hal submits. This creates a submission envelope and a patchset:
npx tsx xyph-actuator.ts submit task:notif-001 \
--description "WebSocket event bus with reconnection and heartbeat"Ada can approve, request changes, or comment:
export XYPH_AGENT_ID=human.ada
npx tsx xyph-actuator.ts review patchset:abc123 \
--verdict approve \
--comment "Clean implementation, LGTM"If she requests changes, Hal can revise (push a new patchset that supersedes the old one):
npx tsx xyph-actuator.ts revise submission:xyz789 \
--description "Added error handling per review feedback"Merge performs git settlement and auto-seals the quest with a Guild-signed Scroll:
npx tsx xyph-actuator.ts merge submission:xyz789 \
--rationale "All reviews approved, tests passing"For solo work without review, agents can seal directly:
npx tsx xyph-actuator.ts seal task:notif-001 \
--artifact abc123def456 \
--rationale "WebSocket bus implemented and tested"npx tsx xyph-actuator.ts status --view lineage
npx tsx xyph-actuator.ts audit-sovereigntyThe lineage view shows the complete Genealogy of Intent from scroll → quest → campaign → intent → human. The sovereignty audit verifies every quest has a valid chain.
The TUI is a bijou-powered interactive cockpit for navigating your XYPH graph.
XYPH_AGENT_ID=human.ada npm run tui| Lane | What it shows |
|---|---|
| Now | Cross-surface action queue (pending settlements, open reviews, ready quests) or recent activity feed |
| Plan | All quests by status progression |
| Review | Submissions and their review status |
| Settlement | Governance artifacts (comparisons, collapse proposals, attestations) |
| Suggestions | AI suggestions: incoming, queued, adopted, dismissed |
| Campaigns | Strategic containers with quest progress |
| Graveyard | Rejected and retired work |
Press Enter on any item to open its detail page — quests, submissions, suggestions, governance artifacts, and cases each have dedicated views with contextual actions (comment, claim, promote, approve, adopt, decide). Press Esc to return to the landing.
| Key | Action |
|---|---|
1-7 |
Jump to lane |
j/k |
Select next/previous |
Enter |
Open item page |
Esc |
Return to landing |
v |
Toggle view mode (Now: queue/activity; Suggestions: incoming/queued/adopted/dismissed) |
r |
Refresh |
i |
Toggle inspector |
m |
Toggle "My Stuff" drawer |
t |
Quest dependency tree |
n |
Queue an Ask-AI job |
; |
Comment on current item |
: / / |
Command palette |
? |
Help |
Agents can emit visible suggestions — either in response to an explicit ask-AI request or spontaneously. Suggestions are graph-visible advisory content, not silent mutations.
# Agent emits a suggestion
npx tsx xyph-actuator.ts suggest \
--kind dependency \
--title "Recommend a dependency edge" \
--summary "task:TRACE-002 should depend on task:TRACE-001" \
--for either \
--target task:TRACE-002
# Human queues an explicit ask-AI job for agent pickup
npx tsx xyph-actuator.ts ask-ai \
--title "Should we promote task:TRACE-002?" \
--summary "Inspect and recommend" \
--target task:TRACE-002
# Manage suggestions
npx tsx xyph-actuator.ts suggestion accept <id> --as quest
npx tsx xyph-actuator.ts suggestion dismiss <id> --rationale "Not now"
npx tsx xyph-actuator.ts suggestion accept-all --min-confidence 0.85XYPH provides two agent-facing surfaces: imperative CLI commands and a JSONL control plane.
Agents use briefing, next, context, and act for structured work packets:
# Cold-start orientation
npx tsx xyph-actuator.ts briefing --json
# What should I work on next?
npx tsx xyph-actuator.ts next --json
# Deep context on a specific entity
npx tsx xyph-actuator.ts context task:notif-001 --json
# Execute a validated action
npx tsx xyph-actuator.ts act claim task:notif-001 --json
# Record a session handoff note
npx tsx xyph-actuator.ts handoff task:notif-001 --jsonThese return structured work packets with blockingReasons, nextLawfulActions, expectedActor, attentionState, and more. See AGENT_PROTOCOL.md for the full contract.
For richer operations — worldline management, governance, and speculative execution — XYPH exposes a versioned JSONL control plane:
printf '%s\n' \
'{"v":1,"id":"req-1","cmd":"observe","args":{"projection":"graph.summary"}}' \
| node ./xyph.ts apiThe control plane supports:
| Command | What it does |
|---|---|
observe |
Query the graph at different projections (summary, entity detail, conflicts, context, briefing, diagnostics) |
apply |
Execute mutation operations (add/remove nodes, set properties, manage edges) |
fork_worldline |
Create a derived worldline for speculative or multi-step work |
braid_worldlines |
Keep multiple worldline effects co-present without merge |
compare_worldlines |
Factual preview of divergence between worldlines |
collapse_worldline |
Governed settlement from a derived worldline into live |
attest |
Record governance attestations (gates for collapse execution) |
comment |
Append-only comments on any entity |
history |
Patch provenance for an entity |
diff |
State changes between two points |
explain |
Diagnostic tool for errors, authorization, and entity state |
query |
Governance worklist and artifact series queries |
See Worldlines for the full design rationale behind derived worldlines, braiding, and governed settlement.
All commands support --json for structured JSONL output. Automation consumers should read stdout line by line.
All commands run via npx tsx xyph-actuator.ts <command>.
| Command | What it does |
|---|---|
intent <id> --title "..." --requested-by human.<name> |
Declare a sovereign intent |
quest <id> --title "..." --campaign <id> --intent <id> |
Create a quest |
inbox <id> --title "..." --suggested-by <principal> |
Suggest a task for triage |
promote <id> --intent <id> |
Promote to planned work |
ready <id> |
Mark quest ready for execution |
shape <id> |
Enrich quest metadata (description, kind, priority) |
reject <id> --rationale "..." |
Reject to graveyard |
reopen <id> |
Reopen a graveyarded task |
claim <id> |
Volunteer for a quest (OCP) |
depend <from> <to> |
Declare a dependency |
move <quest> --campaign <id> |
Reassign quest to a campaign |
authorize <quest> --intent <id> |
Wire quest to an intent |
link <quest> --campaign <id> --intent <id> |
Link quest to campaign and intent |
| Command | What it does |
|---|---|
submit <quest-id> --description "..." |
Submit for review (creates submission + patchset) |
revise <submission-id> --description "..." |
Push a new patchset superseding current tip |
review <patchset-id> --verdict <v> --comment "..." |
Review: approve, request-changes, or comment |
merge <submission-id> --rationale "..." |
Merge (git settlement + auto-seal) |
close <submission-id> --rationale "..." |
Close without merging |
seal <id> --artifact <hash> --rationale "..." |
Mark done directly (solo work) |
| Command | What it does |
|---|---|
story <id> --title "..." |
Create a user story |
requirement <id> --description "..." |
Create a requirement |
criterion <id> --description "..." |
Create an acceptance criterion |
evidence <id> --kind <kind> |
Create evidence for a criterion |
policy <id> --campaign <id> |
Create a Definition of Done policy |
govern <policy> <campaign> |
Attach a policy to a campaign |
decompose <from> <to> |
Declare decomposition (intent→story, story→requirement) |
implement <quest> <requirement> |
Link quest to requirement |
scan |
Auto-detect test-to-requirement links |
analyze |
Run heuristic analysis pipeline |
| Command | What it does |
|---|---|
status --view <view> |
Show graph snapshot (roadmap, lineage, all, inbox, submissions, deps, trace, suggestions) |
audit-sovereignty |
Verify all quests have a Genealogy of Intent |
show <id> |
Inspect a graph entity |
history <id> |
Show provenance for a node |
comment <id> --on <target> --message "..." |
Attach a comment |
note <id> --on <target> --title "..." --body "..." |
Create a graph-native note |
spec <id> --on <target> --title "..." --body "..." |
Create a graph-native spec |
adr <id> --on <target> --title "..." --body "..." |
Create a graph-native ADR |
whoami |
Show resolved identity |
login <principal> |
Persist an identity |
logout |
Clear a persisted identity |
generate-key |
Generate an Ed25519 Guild Seal keypair |
config get/set/list |
Manage configuration |
doctor / doctor prescribe |
Audit graph health and generate prescriptions |
| Command | What it does |
|---|---|
quest-wizard |
Interactive quest creation |
review-wizard |
Interactive review |
promote-wizard <id> |
Interactive promote |
triage |
Interactive inbox triage session |
XYPH uses hexagonal architecture. Domain models remain pure, while ports and adapters handle I/O.
src/
├── domain/ # Pure domain models and services
│ ├── entities/ # Quest, Intent, Submission, Story, Requirement, ...
│ ├── services/ # CoordinatorService, ControlPlaneService, GuildSealService, ...
│ └── models/ # Dashboard, control plane, diagnostics DTOs
├── ports/ # 12 port interfaces (GraphPort, IntakePort, SubmissionPort, ...)
├── infrastructure/
│ └── adapters/ # git-warp adapters, config, keyring, LLM, workspace
├── tui/ # bijou-powered cockpit
│ └── bijou/ # TEA app, cockpit lanes, page views, overlays
├── cli/ # Commander-based CLI with 18 command groups
└── validation/ # Ed25519 crypto, patch-ops schema, invariant checks
# Entry points
xyph-actuator.ts # CLI for graph mutations
xyph-dashboard.ts # Interactive TUI
xyph.ts # Dispatcher (routes to actuator or dashboard)
XYPH is built on git-warp — a CRDT graph database that lives inside a Git repository without touching the codebase. Every piece of graph data is a Git commit pointing to the empty tree, making it invisible to git log, git diff, and git status.
- CRDT merge: Nodes and edges use OR-Set semantics; properties use Last-Writer-Wins
- Deterministic convergence: All writers always compute the same final state
- Offline-first: Local success never depends on network
Every mutation obeys the CONSTITUTION.md:
- Art. I — Law of Determinism — Same input, same output
- Art. II — Law of DAG Integrity — No dependency cycles
- Art. III — Law of Provenance — Every mutation is signed with rationale
- Art. IV — Law of Human Sovereignty — Every quest must trace to a human intent
| # | 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 |
| 5 | DASHBOARD — interactive TUI graph browser | DONE |
| 6 | SUBMISSION — native review workflow (submit, revise, review, merge) | DONE |
| 7 | WEAVER — task dependency graph, frontier, critical path | DONE |
| 8 | ORACLE — intent classification + policy engine | PLANNED |
| 9 | FORGE — emit + apply phases | PLANNED |
| 10 | CLI TOOLING — identity, packaging, time-travel, ergonomics | IN PROGRESS |
| 11 | TRACEABILITY — stories, requirements, acceptance criteria, evidence | IN PROGRESS |
| 12 | AGENT PROTOCOL — agent-native CLI and policy-bounded action kernel | IN PROGRESS |
| — | ECOSYSTEM — MCP server, Web UI, IDE integration | PLANNED |
This table is a high-level spine. Active status and dependencies live in the graph:
npx tsx xyph-actuator.ts status --view roadmap
npx tsx xyph-actuator.ts status --view depsThe docs/canonical/ directory contains the foundational specifications:
| Category | Documents |
|---|---|
| Vision & Governance | VISION_NORTH_STAR, CONSTITUTION, CHANGE_CONTROL |
| Architecture | ARCHITECTURE, AGENT_PROTOCOL, ORCHESTRATION_SPEC, SCHEDULING_AND_DAG, ROADMAP_PROTOCOL |
| Data & Schema | GRAPH_SCHEMA, DATA_CONTRACTS, PATCH_OPS_INVARIANTS, APPLY_TRANSACTION_SPEC |
| Security | GUILD_SEALS, SECURITY_AND_TRUST, AUDIT_AND_PROVENANCE |
| Quality | POLICY_ENGINE, AGENT_CHARTER, REVIEW_RUBRIC, TEST_STRATEGY, OPERATIONS_RUNBOOK |
| Design | Worldlines, XYPH As A WARP App |
Apache 2.0 • Copyright © 2026 James Ross
Built with Ω¹ by FLYING ROBOTS
.-:::::'::: .-:. ::-.::::::. :::. .,-:::::/
;;;'''' ;;; ';;. ;;;;';;;`;;;;, `;;;,;;-'````'
[[[,,== [[[ '[[,[[[' [[[ [[[[[. '[[[[[ [[[[[[/
`$$$"`` $$' c$$" $$$ $$$ "Y$c$$"$$c. "$$
888 o88oo,.__ ,8P"` 888 888 Y88 `Y8bo,,,o88o
"MM, """"YUMMMmM" MMM MMM YM `'YMUP"YMM
:::::::.. ... :::::::. ... :::::::::::: .::::::.
;;;;``;;;; .;;;;;;;. ;;;'';;' .;;;;;;;.;;;;;;;;'''';;;` `
[[[,/[[[' ,[[ \[[, [[[__[[\.,[[ \[[, [[ '[==/[[[[,
$$$$$$c $$$, $$$ $$""""Y$$$$$, $$$ $$ ''' $
888b "88bo,"888,_ _,88P_88o,,od8P"888,_ _,88P 88, 88b dP
MMMM "W" "YMMMMMP" ""YUMMMP" "YMMMMMP" MMM "YMmMY"¹ Ω (Omega) — the final convergence point of the WARP graph; symbolizes deterministic state resolution.