⚠️ Superseded by SuperXOpenPraxis is no longer developed. Last commit May 2026. It is kept public as prior art and as a working record of what it proved.
The successor is SuperX — the same thesis, rebuilt in Rust on an append-only substrate: k8nstantin.github.io/superx
Reading this repository: the documentation below describes the system as designed, and in several places the design outran the code before development stopped — the independent watcher was removed, cost tracking was gutted pending a redesign, retry and the proposer loop were partially wired, and forecasting was never built. Treat the README as intent and the code as the source of truth. That gap is itself part of what the rewrite was for, and the specifics are recorded in What carried forward below.
OpenPraxis is a full DAG execution engine for AI-assisted software development. One captured Idea becomes a Product. A Product holds chained Manifests (versioned specs with deliverables). Each Manifest holds chained Tasks that dispatch agents (Claude Code, Cursor, Codex) in isolated git worktrees. Every action is captured, every completed Task is audited independently of the agent, every cost unit attributes back to the spec that drove it — on a single graph, visualised, searchable, self-hosted.
flowchart TB
Idea[/"<b>Idea</b><br/><i>captured concept</i>"/]:::idea -->|becomes| P
P(["<b>Product</b><br/><i>top-level spec</i>"]):::product -->|holds| MH([Manifests])
MH --- M1["<b>Manifest A</b><br/><i>versioned spec</i>"]:::manifest
MH --- M2["<b>Manifest B</b>"]:::manifest
M1 -->|holds| T1a["Task<br/><i>atomic</i>"]:::task
M1 --- T1b["Task<br/><i>atomic</i>"]:::task
T1a -. depends_on .-> R1a[Review<br/>Task]:::review
T1b -. depends_on .-> R1b[Review<br/>Task]:::review
M2 --- T2a["Task<br/><i>atomic</i>"]:::task
T2a -. depends_on .-> R2a[Review<br/>Task]:::review
classDef idea fill:#1a1a2e,stroke:#3b82f6,stroke-width:2px,color:#e4e4e7
classDef product fill:#4c1d95,stroke:#8b5cf6,stroke-width:3px,color:#fff
classDef manifest fill:#1e3a5f,stroke:#3b82f6,stroke-width:2px,color:#e4e4e7
classDef task fill:#0a0a0f,stroke:#71717a,color:#a1a1aa
classDef review fill:#0a0a0f,stroke:#f59e0b,color:#f59e0b
Progression: Idea → Product → Manifest → Task (atomic) → Review Task. Idea at the top — the captured concept. Product beneath it as the spec root. Manifests hang off the Product as independent specs — they do not depend on each other by default; each Manifest is its own fireable unit. Tasks hang off each Manifest as grapes — the Task is the atomic unit of work that dispatches one agent in one worktree. Each Task pairs with its own Review Task, chained via depends_on: when the parent Task completes, the Review Task auto-activates, inspects the real-world side effects, and posts review_approval or review_rejection on the parent. The watcher's gate findings surface as comments; the Review Task owns the verdict.
(Manifest-to-manifest and product-to-product depends_on dependencies are supported in the model — see Workflow Engine reference — but the primary pattern keeps Manifests independent. Complex cross-manifest coordination becomes useful as agents mature.)
Cost control, independent quality audit, cross-agent comparison, and forecasting are outcomes of the engine — not separate tools bolted on.
OpenPraxis was the first attempt at a governed execution layer for autonomous coding agents. What it established still holds, and is built into SuperX from the substrate up:
- Agents cannot be trusted to self-report completion. Verification has to run somewhere the agent cannot see or skip.
- Work is a graph, not a ticket queue. Products decompose into specs and specs into tasks, and dependency order is the plan.
- Constraints must be mechanical. A rule the agent acknowledges and a check that runs afterwards are two different things, and only the second one counts.
- Cost and turns have to attribute back to the spec that caused them, or there is no way to answer whether the work was worth it.
- Memory has to outlive the session, or every run starts from zero.
- The protocol belongs in the substrate, not in code — versioned, auditable, changeable without a release.
What the rewrite changed, and why:
| OpenPraxis | SuperX | Why |
|---|---|---|
| Five entity tables (products, manifests, tasks, ideas, skills), later collapsed into one | One node table + one edge table, kinds as rows in a registry | The collapse was forced. Starting there removes a whole class of type-specific special cases — and new kinds become a command instead of a migration. |
| Status column updated in place; the documented state machine's only writer was never instantiated, so nothing ever closed a task | Lifecycle derived from append-only chains; "current" computed at read time | Two sources of truth disagree eventually. One of them has to be a projection. |
valid_to stamped on the superseded row; Remove overwrote created_by/reason on the row it closed |
Retraction is a new row; nothing mutates history | Attribution is destroyed by editing the record you are superseding. |
| Comment types aliased to one constant to keep call sites compiling — which silently made "was this approved?" unanswerable | Typed edges and enum-constrained fields, enforced by the engine | The alias compiled fine and deleted the semantics. Rust makes that collapse a build error. |
| Prompt scaffold in a versioned template table — which ended up holding only seeded defaults, with every real prompt written as a comment instead | The per-entity instruction stream is the authoring surface, and each run pins the exact instruction version it dispatched with | Build the surface people actually use, then version that. |
| Sixteen tables dropped at boot as the migration strategy | Insert-only; tolerant schema re-apply with a version gate | A migration that cannot be reversed is not a migration. |
| An in-process mutex standing in for a storage invariant (defeated by the second process on the same file) | Uniqueness expressed in the schema | A lock in one process is not a constraint. |
| Retry counters and failure streaks kept in the mutable settings table, with no history | Every fact, including the system's own decisions, is an inserted row | An autonomous system that cannot explain why it fired is not auditable. |
Also worth knowing: go-leiden was built by OpenPraxis. The first native Go implementation of the Leiden algorithm was written end to end by autonomous agents driven through this engine, with no human code commits — k8nstantin/go-leiden. That experiment is the strongest evidence for the thesis, and the reason it was worth rebuilding properly.
Everything below is the original documentation, unchanged.
- Trace-grounded feedback loop. (v0.9) Every retry sees what the previous run attempted — prior execution digests and agent review comments injected into the prompt automatically. Agents stop repeating the same mistakes. Pass rates per task queryable via API. An autonomous proposer loop evolves the prompt scaffold when tasks plateau. Full guide →
- End-to-end product build graph. One Product, many independent Manifests (fire each on its own), many Tasks per Manifest with paired Review Tasks chained via
depends_on. The graph plans, dispatches, audits, and costs every step from initiative spec to merged commit. IDE agents, orchestration SDKs, and observability proxies each cover a slice; OpenPraxis owns the whole chain. Detailed comparison → - Line-item cost attribution. Every cost unit spent attributed to a task, a spec, a product, a day, and the authorizing policy.
- Pre-fire cost forecasting. Predict what the next run, manifest, or sprint will cost from your actual history, per model, per agent, per spec shape.
- Independent quality audit. Every completed task audited against spec, build, and diff by a separate watcher; paired review tasks post the final verdict.
- Cross-agent efficiency comparison. Claude Code vs Cursor vs Codex measured on your real code — cost per approved task, review-approval rate, diff cleanliness.
- End-to-end audit trail. Every action, decision, and verdict persists with full provenance for compliance, postmortems, and root-cause analysis.
- Team-wide shared memory. Specs, memories, decisions, and rules sync across every engineer's machine over the local network — no SaaS lock-in.
- Central governance. Daily budgets, per-task caps, approval rules, and scope boundaries enforced by the platform; engineers keep shipping.
- Atomic-granularity observability. Drill from a product's total spend to the exact tool call that caused it in two clicks.
- Interactive build DAG. The whole plan as a clickable, status-colored graph — brief a stakeholder without a deck.
- Self-hosted, offline-capable. Control plane runs on your hardware; we're not in your data path.
- → How is OpenPraxis different from other AI-agent tools? Full landscape map vs IDE agent runtimes (Cline, Cursor, OpenHands, Goose), orchestration SDKs (CrewAI, LangChain), observability proxies (Helicone, Langfuse, AgentOps), enterprise platforms (watsonx, UiPath), and closest concept match (Paperclip). Plus OpenClaw comparison ↓ for the consumer-assistant axis.
flowchart LR
subgraph Inputs [" "]
direction TB
Spec[Spec / Manifest]
Budget[Budget, Rules, Caps]
end
OP(["<b>OpenPraxis</b><br/>control plane"])
subgraph Agents [Multi-agent execution]
direction TB
A1[Claude Code]
A2[Cursor]
A3[Codex]
end
subgraph Outputs [" "]
direction TB
Git[(Git<br/>branch per task)]
Cost[Cost attribution<br/>per action · task · day]
Quality[Independent audit<br/>watcher + reviews]
Memory[Shared memory<br/>LAN peer sync]
DAG[Interactive DAG<br/>status-colored plan]
end
Spec --> OP
Budget --> OP
OP <--> A1
OP <--> A2
OP <--> A3
OP --> Git
OP --> Cost
OP --> Quality
OP --> Memory
OP --> DAG
Developers write the spec. Leadership sets the budget, caps, and rules. OpenPraxis dispatches the work to whichever agent is best for the job, captures every action the agent takes, audits the result independently of the agent, attributes the spend to the originating spec, and syncs the memory across the team — all on your hardware, on your terms.
One organizational model, used everywhere. OpenPraxis orchestrates work as a three-level hierarchy borrowed from how actual engineering teams already think. Everything — cost, turns, status, settings, review verdicts — cascades up or down this spine.
Peer (your machine, identified by UUID v7 + MAC fingerprint)
│
├── Idea [CAPTURED CONCEPT — upstream of any build work]
│ │ priority (low/medium/high/critical) · tags
│ │ link_idea_manifest ties ideas to the specs they spawned
│ │
├── Product [SPEC — top level, groups manifests under one umbrella]
│ │ title · tags · status · cost rollup · DAG root
│ │
│ ├── Manifest [SPEC — versioned markdown with deliverables]
│ │ │ depends_on other manifests (build order)
│ │ │ jira_refs · status · linked ideas · comments
│ │ │
│ │ ├── Task [ATOMIC UNIT OF WORK — executes one agent]
│ │ │ │ depends_on other tasks · schedule (once / 5m / at:)
│ │ │ │ status, cost, turns, run_count, branch · comments
│ │ │ │
│ │ │ ├── Run [ATOMIC UNIT OF EXECUTION — one attempt]
│ │ │ │ │ started_at / completed_at · cost · exit code
│ │ │ │ │
│ │ │ │ └── Action [ATOMIC UNIT OF MEASUREMENT — one tool call]
│ │ │ │ tool_name · tool_input · tool_response · cwd
│ │ │
│ │ └── Review Task [ATOMIC UNIT OF VERDICT — paired via depends_on]
│ │ auto-activates on parent completion
│ │ posts review_approval / review_rejection on parent
│ │
│ └── More manifests … chained by manifest depends_on
│
└── More products …
The taxonomy at a glance:
| Level | What it is | Atomic? |
|---|---|---|
| Idea | Captured concept — priority + tags. Upstream of any build work; links to the Manifests it spawned. | No (seed) |
| Product | Top-level spec — groups related manifests under one umbrella | No (container) |
| Manifest | Versioned detailed spec with deliverables, depends_on, status | No (container) |
| Task | Scheduled unit of work that dispatches one agent session | Atomic unit of work |
| Run | One execution attempt of a task | Atomic unit of execution |
| Action | One tool call made by the agent during a run | Atomic unit of measurement |
| Review Task | A depends_on-paired Task that audits its parent's output |
Atomic unit of verdict |
- Organization matches reality. Initiatives have specs. Specs have work items. Work items have runs. Runs have tool calls. The model holds all the way down.
- Aggregation is free. Cost and turns roll up at every level with no manual bookkeeping — drill from "the product cost X" → "this manifest accounted for most of it" → "this one task spent the bulk" → "this one agent turn burned the peak" → "here's the exact prompt and tool call that caused it".
- Settings cascade. 12 execution knobs resolve via
task → manifest → product → system. Setmax_turns=100once at the product, every task under it inherits. Override for one hard manifest. Override again for one risky task. The resolver walks the chain on every read. - Dependencies at every layer. Products depend on products. Manifests depend on manifests (build order). Tasks depend on tasks (run order + paired reviews). The same
depends_onprimitive powers all three — and the scheduler blocks dependents until prerequisites are terminal. - Reviews ride the same chain. The review-task pattern pairs every main task with a verify task via
depends_on; when main completes, review auto-activates, polls real-world state, and posts the canonical verdict. No watcher can override it; no review agent can impersonate the watcher.
The hierarchy isn't just a data model — it's a picture. Every product renders as an interactive Directed Acyclic Graph. You see the whole build plan at once: what's done, what's running, what's blocked, what's next, where the money went, and exactly which task implements which line of which spec.
- Purple product node at the top — the initiative.
- Manifest nodes linked by blue manifest-dep edges — the build order.
- Task nodes under each manifest linked by yellow task-dep edges — the execution chain.
- Ownership edges (dashed) from manifest to each root task — the "I belong to this spec" relationship.
- Status colours — green done, grey pending, red failed, amber in flight. One glance tells you where the build is.
- Any shape, no custom code. Linear 12-task chain (like the ELS product:
T1 → T1R → T2 → T2R → … → T6R)? Renders top-to-bottom. Eight independent pairs (like INT MySQL backup/verify)? Renders as eight parallel short columns. Multi-parent fan-in? Dagre figures it out. Empty manifest? Graceful. The renderer takes the edge set and delegates layout to dagre (PR #158); we don't do arithmetic on positions anymore. - Click any node to drill in. Purple → product detail. Blue → manifest detail. Chain node → task detail with live output.
#view-products/<id>/dagis shareable. - Contract-tested at the API level.
TestProductHierarchy_EmptyProduct / _LinearChain / _ParallelPairslocks the/api/products/:id/hierarchypayload the renderer rides on so a new DAG shape can't silently break the layout (PR #160).
Why it matters. A spec without a picture is a PDF nobody reads. A DAG without real numbers is a toy. OpenPraxis combines both — you see the plan and the current cost, status, run count, and cost-per-turn of every node in it, live, in one view.
- Features · How it fits · The Hierarchy · The DAG · Where OpenPraxis fits (vs OpenClaw)
- See it in action
- Dashboard — cost today vs. budget, tasks ranked by spend
- Live tool output — watch the agent work, turn by turn
- Products → Manifests → Tasks — every cost and every turn rolls up
- Visualize the plan — interactive DAG, status-colored
- Every conversation, every tool call, every visceral-rule ack — searchable forever
- Independent evaluation — three gates an agent can't override
- Hierarchical execution controls — budgets, turns, and agent knobs that inherit
- How It Works
- Architecture
- Key Concepts
- Dashboard (17 Tabs)
- MCP Tools (55 as of 2026-04-22)
- Quick Start
- Stats
- Database
- Project Structure
- Hooks
- Peer Sync
- Configuration
- Mobile App
- License
Deeper references:
- Compared to other AI-agent tools — full landscape map — IDE runtimes, orchestration SDKs, observability proxies, enterprise platforms, and Paperclip
- Execution Controls — all 12 knobs in detail
- Workflow Engine — DAG, states, activation model, review loop, SCD principle
- Changelog — April 2026 release notes
If an AI model is a CNC machine, OpenPraxis is the factory. The model cuts metal; OpenPraxis is everything around it: the specs (manifests), the work orders (tasks), the shop floor (execution engine), the time clock (cost + turn tracking), the QA station (watcher), the archive (memory), and the shift log (activity feed). One developer with OpenPraxis runs an engineering shop, not a chat thread.
Professional AI development tool — not a consumer agent-message manager. OpenPraxis lives on the builder's side of the tool: every action an agent takes is captured, every cost unit is attributed, every rule is enforceable, every decision is auditable months later. It is purpose-built for the person who has to track the cost of every agent run, defend the merges, and find out what the agent actually did on Tuesday.
OpenPraxis is not a consumer chat wrapper. If you are looking to route inbound WhatsApp / iMessage / Telegram messages to a local assistant, OpenPraxis isn't the tool — OpenClaw or a similar assistant gateway is. OpenPraxis starts where the build request starts and ends where the commit lands.
| OpenPraxis | Consumer agent-message managers (e.g. OpenClaw) | |
|---|---|---|
| Domain | AI-assisted software development | Local personal assistant over chat/voice |
| Front door | Manifests + scheduled tasks written by a developer | Inbound messages on WhatsApp, iMessage, Telegram, Signal, Slack, Discord, ... |
| Output | Commits, branches, PRs, dashboard state | Reply messages in the source channel + voice + canvas |
| Unit of work | A task that runs an agent session against a spec | A conversation turn in a messaging thread |
| Isolation | One agent per task, in its own git worktree | One agent per channel / account / workspace |
| Cost model | Per-task, per-turn, per-day, per-product spend — first-class metric | Not a first-class surface |
| Audit model | Independent watcher + typed review comments + execution_review retrospectives | Conversation history |
| Ideal user | Professional developer / team with AI spend to justify and merges to defend | Power user who wants a private assistant across their chat apps |
| Persistence | Embedded local store with semantic + keyword search | JSON config + workspace dirs |
| Primary language | Go (single binary) | TypeScript / Node.js |
Short version: OpenPraxis captures what the agent did and what it cost, every turn, forever. That's the core. Everything else — specs, review workflows, peer sync, the DAG viewer — is in service of that capture loop.
Most agent tools hand you a black box: you push "run", hope for the best, and reconstruct what happened from a log scroll. OpenPraxis inverts that. Every turn, every tool call, every commit, every dollar — captured as it happens, aggregated upward, and surfaced on a single dashboard. Cost is a first-class metric on the task, the manifest, the product, and the day. Activity is a first-class record: every prompt, every tool input, every tool result, every acknowledgement of a visceral rule. Independent evaluation is non-negotiable: the watcher audits every completed task and posts findings the agent cannot delete.
The result is cost and quality control by construction — you set a daily budget, you see spend accrue against it live, the watcher flags every failed gate, and runaway sessions can't hide behind a finished status.
One glance tells you the entire cost and efficiency story of your fleet:
- AI Stats (cumulative) — total cost, turns, actions, and runs across all time (or scoped to today). Trend charts for cost, turns, and actions show where spend accelerated.
- Cache hit ratio — dial gauge. 98% means almost every token was served from cache; a drop here is the earliest signal that prompts drifted and cost is about to spike.
- Token split — stacked bar:
cache_read(green) vsinput(blue) vscache_create(orange) vsoutput(yellow). Lets you see exactly how token budget is allocated across the fleet. - Actions / hour — 12-hour histogram. Identify burst windows, overnight runs, and idle periods at a glance.
- Top tools — ranked by call count across the last 300 actions. Know whether your agents spend time in
Bash,Read,Edit, or MCP calls. - Nodes & Sessions — peer roster with live session cards: which agents are connected, turn count, last activity.
Open any task and see everything in one panel:
- Execution control dials — semicircle gauges for max turns, max cost, temperature, reasoning effort, and more. Set them per-task; they inherit from manifest → product → system when not overridden.
- Dependency chain — which tasks this one depends on, and which depend on it.
- Run history — every execution attempt with start time, cost, turns, exit reason, and status. Click any run to drill into its action log.
- Live output — bash commands, file reads, edits, and MCP calls stream in turn-by-turn as the agent runs.
- Pause (SIGSTOP) / Stop / Emergency Stop All — freeze or kill from the task header; no waiting for the agent.
- Comments thread — typed comments (
agent_note,review_approval,watcher_finding, etc.) on the same page as the run output.
Hierarchy: Product → Manifest → Task → Run → Action. Costs and turns aggregate at every level. Drill from "the product cost X" → "this manifest accounted for most of it" → "this one task spent the bulk" → "this one agent turn burned the peak" → "here's the exact prompt and tool call."
Every product renders as an interactive directed acyclic graph:
- Product node at the top — the initiative root.
- Manifest nodes linked by manifest-dep edges — the build order.
- Task nodes under each manifest linked by task-dep edges — the execution chain.
- Status colors — green done, gray pending, red failed, amber in flight.
- Zoom, pan, click to drill. Click any node to open its detail panel inline.
Every agent session is captured as a conversation:
- Every turn — prompt, response, tool call, tool result, thinking block.
- Visceral-rule acknowledgements — an agent that skips the
visceral_rules→visceral_confirmhandshake is flagged as amnesia on the dashboard (look at the badge in the nav — 10000 violations shown here). - Semantic search — 768-dim embeddings via Ollama. "Find the session where we fixed the sqlite busy_timeout bug" is a similarity query, not a filename search.
- Per-peer, per-session grouping — every conversation is tagged with the peer that ran it, so multi-machine teams get one unified history.
The watcher is a separate process outside every agent session. After a task finishes, it runs three gates:
- Git gate — did the agent produce commits on the task branch? (Zero commits = observation flagged.)
- Build gate — does the code compile? (
go build ./...here; configurable per language.) - Manifest gate — were the deliverables addressed? (Parses the manifest markdown into a checklist, scores how many items were actually touched in the diff.)
As of 2026-04-22 the watcher is observer-only (PR #149). Gate outcomes persist as watcher_audits rows and auto-post a watcher_finding comment on the task. The watcher does not mutate task status and does not block downstream activation — the paired review task (if any) is the sole decision point for the verdict.
Why the shift: ops-style tasks (SSH-dispatch, fire-and-forget infrastructure jobs) legitimately produce zero commits, and the earlier "zero commits = instant fail" behaviour kept downgrading those to failed and blocking their chained verify task. The three gates are still valuable signals — they still surface in the UI and in the audit history — but verdicts belong to the review task, which can see the live state on the remote target.
The review task pattern: pair every main task with a depends_on-linked review task that auto-activates on completion, polls the real-world side effects, and posts review_approval or review_rejection as the canonical verdict.
![]() |
![]() |
| Settings — global config with provider integrations | Task — execution knobs with inheritance from manifest → product → system |
Twelve execution knobs — max_parallel, max_turns, max_cost_usd, daily_budget_usd, timeout_minutes, temperature, reasoning_effort, default_agent, default_model, retry_on_failure, approval_mode, allowed_tools — configurable at four scopes with inheritance: task → manifest → product → system. Set a product-wide budget once; every task under it inherits. Override one manifest's max_turns for a hard job; the product default still covers the rest.
- Inline provenance — every knob shows where the value came from ("inherited from product X") so you know which scope to edit to change it everywhere vs. here.
- Reset to inherited — one click drops a local override, reverts to the scope above.
- Soft-cap warnings — push
daily_budget_usdabove the visceral rule's hard cap and the UI warns before save; the runner clamps at runtime regardless. - Debounced save — slide the value, it saves 300 ms after you stop; no "Apply" button to forget.
- Agent-readable — the MCP
settings_resolvetool returns the effective value walking the inheritance chain, so agents query the budget instead of guessing.
Storage: a single settings table with (scope_type, scope_id, key) primary key. The resolver walks task → linked manifests → product → system on every read, clamped by visceral rules. Nine HTTP endpoints (/api/settings/...) mirror the four MCP tools for dashboard use.
📖 Full reference: all 12 knobs, types, ranges, and enforcement — what each knob does, how the runner uses it, and which scope typically owns it.
You have an idea
|
v
[Idea] -----> [Manifest] -----> [Task] -----> [Agent Session]
capture it write the spec schedule it autonomous execution
| | | |
v v v v
[Product] [Dependencies] [Dependency [Watcher]
group specs chain manifests chain tasks] audit: git, build,
track cost set build order sequential manifest compliance
execution agent can't self-grade
- Capture ideas — save feature requests, bugs, improvements with priority and tags
- Write manifests — detailed markdown specs with deliverables, architecture, requirements
- Organize into products — group manifests under products. Set manifest dependencies for build order
- Create tasks — break manifests into executable tasks with dependency chains
- Execute autonomously — the task runner spawns independent agent sessions (Claude Code, Cursor) with the manifest spec, visceral rules, and relevant memories as context
- Audit independently — the watcher (server-side, outside the agent) checks every completed task: did the agent commit code? does it compile? were deliverables addressed?
- Enforce rules — visceral rules are non-negotiable constraints every agent must acknowledge. Violations are flagged automatically as amnesia
- Share across sessions — every decision, conversation, and tool call persists. New sessions inherit context from previous ones. Multiple machines sync via peer-to-peer
You
|
+-----------+-----------+
| | |
Claude Code Cursor Copilot
| | |
+-----+-----+-----+----+
| |
stdio MCP hooks
| |
+-----+-----------+--------+
| OpenPraxis |
| |
| entities (SCD-2) | ← all types: product/manifest/task/skill/idea
| execution_log | ← append-only event-sourced runs
| relationships | ← all edges: owns/depends_on/links_to
| schedules (SCD-2) | ← universal DAG dispatcher
| Watcher > Audit |
| Memory > Persistence |
| Rules > Compliance |
| Ideas > Pipeline |
| Chat > Dashboard |
| |
+-----+----------+---------+
| |
SQLite+vec Dashboard
(memories.db) (localhost:9966)
|
Peer Sync (mDNS + Automerge)
|
Other Machines
OpenPraxis is a single Go binary that runs as:
- MCP server (stdio) — spawned by coding agents as a subprocess, exposing 55 tools
- HTTP server — dashboard UI, REST API, WebSocket events, hook handler
- DAG dispatcher — universal scheduler: any entity (product/manifest/task/skill) can be scheduled; agent receives entity UUID, reads the DAG via HTTP API, executes
- Watcher — independent server-side auditor that agents cannot override
- Peer node — mDNS discovery + Automerge CRDT sync with other OpenPraxis instances
Top-level organizational hierarchy. A product groups related manifests into a single initiative with aggregated cost, turns, and task status. Visualized as an interactive DAG showing the manifest dependency chain with tasks below each manifest.
Hierarchy: Product > Manifest > Task > Run
Development specs — detailed markdown documents describing a feature, module, or refactor. Manifests have:
- Versions — every update bumps the version
- Statuses — draft, open, closed, archive
- Dependencies — manifests chain to each other (
depends_on). The scheduler blocks tasks from a manifest until its dependency manifests are closed - Linked tasks — many-to-many relationship
- Linked ideas — trace which idea spawned which spec
- Deliverables — extracted from markdown checklists, verified by the watcher
Scheduled work units linked to manifests. The execution engine:
- Picks up due tasks from the scheduler
- Spawns an independent agent session (Claude Code subprocess)
- Injects: manifest spec, visceral rules, relevant memories, allowed tools, git workflow instructions
- Captures all output, tool calls, and costs in real-time
- Supports: dependency chains (
depends_on), pause/resume (SIGSTOP/SIGCONT), max turns, recurring schedules - On completion: watcher audit runs independently
Server-side execution observer. Runs outside the agent session — the agent has no visibility or control. Three gates on every completed task:
- Git Gate — did the agent create commits on the task branch?
- Build Gate — does the code compile? (
go build ./...) - Manifest Gate — were the deliverables addressed? (Scores deliverables found in diff)
Observer-only (PR #149). Each gate posts a watcher_finding comment on the task capturing the result. The watcher never mutates task state and never blocks downstream ActivateDependents. The paired review task (if any) is the sole decision point for review_approval / review_rejection. This decouples code-check gates from ops-task lifecycles that legitimately produce zero commits.
Every entity (product, manifest, task, skill, idea) carries an append-only comment thread. Two core types (v0.6+):
| Type | Purpose |
|---|---|
prompt |
Active instructions for this entity — the latest prompt comment is what the next agent run executes |
comment |
Context, findings, decisions — feeds next run's situational awareness |
Special subtypes used by the system:
| Type | Purpose |
|---|---|
execution_review |
Agent post-run retrospective (required by runner) |
review_approval |
Final verdict from a paired review task — success |
review_rejection |
Final verdict from a paired review task — failure |
watcher_finding |
Observer-posted gate result (watcher only) |
Legacy types (agent_note, user_note, decision, link) are transparently remapped to comment at both MCP and HTTP boundaries (v0.6 PR #344).
Capture product ideas, feature requests, bugs, and improvements with priority levels (low/medium/high/critical) and tags. Ideas link to manifests — trace which idea became which spec, and track from concept to execution.
Semantic, path-organized knowledge stored with embeddings for vector search. Memories persist across sessions and agents — decisions, patterns, bugs, and constraints survive.
/project/openpraxis/bugs/macos-codesign-required
/project/openpraxis/audit/task-e33-slog-postmortem
/personal/gryphon-data-lake/testing/preferences
Memories have scopes (personal, project, team), types (insight, decision, pattern, bug, context, reference), and tiered responses (L0 one-liner, L1 summary, L2 full content).
Non-negotiable operating constraints set by the user. Every agent session must call visceral_rules then visceral_confirm before doing any work. Violations are flagged as amnesia on the dashboard. Examples:
- "Never fix scripts on the fly — fix the original source"
- "Every new code modification is a new branch"
- "Daily budget = $100"
- "SQLite must always use WAL mode + busy_timeout=5000"
- "Never start or fire a task unless the user explicitly says to start it"
Every agent session's tool calls and interactions are captured — searchable by semantic similarity and browsable by date, agent, and project. Full audit trail of what every agent did.
Multi-provider AI chat built into the dashboard. Supports Anthropic (Claude), Google (Gemini), OpenAI (GPT-4), and Ollama (local models) with streaming, tool use, vision, and extended thinking.
Grouped in the sidebar under three headers — Memory, Development, Network.
| Tab | Group | What it shows |
|---|---|---|
| Overview | — | Running tasks, total cost, turns, session count, peer list |
| Visceral | Memory | Rules list, pattern detection, confirmation tracking |
| Memories | Memory | Semantic + keyword search, path browser, tiered content |
| Conversations | Memory | Keyword-first paginated search with <mark> highlights + "Related by meaning" semantic tail on page 0 (PR #152); infinite scroll |
| Actions | Memory | Every tool call, keyword search with snippet highlights + infinite scroll (PR #152) |
| Amnesia | Memory | Agent sessions that skipped visceral_rules + visceral_confirm |
| Ideas | Development | Capture, prioritize, link to manifests |
| Products | Development | Interactive DAG (cytoscape + dagre, bundled locally), cost aggregates, manifest chains |
| Manifests | Development | Specs with dependencies, linked tasks/ideas, version history, comment threads |
| Tasks | Development | Status, dependency chains, run history, real-time output, pause/resume, comments, review verdicts |
| Chat | Development | Multi-provider AI chat with model switching + thinking toggle |
| Delusions | Development | Agent output that contradicts the manifest spec |
| Watcher | Development | Audit history (git/build/manifest gates) — observer-only as of PR #149 |
| Peers | Network | mDNS-discovered OpenPraxis instances on the LAN |
| Activity | Network | Real-time feed across all sessions and peers |
| Recall | Network | Soft-deleted items, restorable |
| Settings | Network | Profile, agent integrations, chat provider config |
| Category | Tools |
|---|---|
| Memory | memory_store, memory_search, memory_recall, memory_list, memory_forget, memory_status, memory_peers |
| Conversations | conversation_save, conversation_search, conversation_list, conversation_get |
| Visceral | visceral_rules, visceral_confirm, visceral_set, visceral_remove |
| Ideas | idea_add, idea_list, idea_update, link_idea_manifest, unlink_idea_manifest |
| Products | product_create, product_get, product_list, product_update, product_delete, product_dep_add, product_dep_remove, product_dep_list |
| Manifests | manifest_create, manifest_get, manifest_list, manifest_update, manifest_delete, manifest_search, manifest_dep_add, manifest_dep_remove, manifest_dep_list |
| Tasks | task_create, task_list, task_get, task_start, task_pause, task_resume, task_cancel, task_approve, task_reject, task_link_manifest, task_unlink_manifest |
| Markers | marker_flag, marker_list, marker_done |
| Comments | comment_add — thread on any product/manifest/task; typed (agent_note / execution_review / review_approval / review_rejection / watcher_finding / user_note / decision / link); short-marker target IDs are auto-resolved to full UUIDs (PR #136) |
| Settings | settings_catalog, settings_get, settings_set, settings_resolve — task → manifest → product → system inheritance with visceral-rule clamping |
Comment-add and target-id resolvers now canonicalize short markers at both the MCP boundary (PR #136) and the HTTP boundary (PR #139), so agents and dashboards both hit the right row regardless of id form.
- Go 1.22+
- Ollama with
nomic-embed-textmodel (for semantic search)
# Install Ollama and pull the embedding model
ollama pull nomic-embed-textmake build # Build binary (includes macOS codesign)
./openpraxis serve # Start dashboard + MCP + sync (port 9966)Add to your project's .mcp.json:
{
"mcpServers": {
"openpraxis": {
"command": "/path/to/openpraxis",
"args": ["mcp"]
}
}
}Claude Code will spawn OpenPraxis as a subprocess. On first session, the agent receives instructions to call visceral_rules + visceral_confirm before any work.
Open http://localhost:9966.
| Metric | Count |
|---|---|
| Go source files | ~155 |
| Go lines of code | ~38,000 |
| Dashboard | React 19 + Vite + Tailwind v4 + TanStack Router + shadcn/ui — compiled to ui/dashboard-v2/dist/, embedded in binary |
| MCP tools | 55 |
| HTTP routes | ~150 (REST, WebSocket, hook endpoint, MCP over streamable HTTP) |
| Dashboard tabs | 12 (Operations: Overview, Actions Log, Products, Manifests, Tasks, Inbox, Recall · Governance: Productivity, Audit, Activity · Configuration: Settings) |
| Persistent tables | 20 primary + vec-search virtual tables (13 legacy tables dropped in v0.6) |
| Go test files | ~70, incl. contract tests for the product hierarchy DAG shapes (PR #160) |
SQLite with WAL mode (_journal_mode=WAL&_busy_timeout=5000, visceral rule #10). Single file at ~/.openpraxis/data/memories.db.
Core (v0.6+ unified): entities (SCD-2, all types: product/manifest/task/idea/skill), execution_log (append-only event-sourced runs), relationships (all edges: owns/depends_on/links_to), comments, schedules (SCD-2)
Support: memories, conversations (+ session_turns), actions, sessions, markers, settings
Compliance: amnesia, delusions, visceral_confirmations, watcher_audits, rule_patterns
Vector search: vec_memories, vec_conversations (sqlite-vec extension, 768-dim cosine similarity)
Note: 13 legacy tables dropped in v0.6: products, manifests, ideas, task_runs, task_run_host_samples, task_dependency, product_dependencies, manifest_dependencies, idea_manifest_links, task_manifests, task_runtime_state, execution_log_samples, model_pricing.
cmd/ CLI commands (cobra): serve, mcp, version
internal/
action/ Action recording + visceral/delusion compliance
config/ YAML config loader + platform detection
conversation/ Conversation storage + vector search
embedding/ Ollama embedding client (nomic-embed-text, 768-dim)
idea/ Ideas store
mcp/ MCP server (stdio + streamable HTTP), 55 tool handlers
memory/ Memory store + tiered responses (l0/l1/l2) + vector search
node/ Node orchestrator — wires all stores together
peer/ mDNS peer discovery + Automerge CRDT sync
schedule/ SCD-2 schedules table + cron-driven DAG dispatcher
setup/ Agent detection + auto-configuration (Claude Code, Cursor, etc.)
task/ Task runner + prompt builder (unified entity model)
web/ HTTP handlers, WebSocket hub, embedded dashboard
ui/dashboard-v2/ React dashboard (Vite + React 19 + Tailwind v4 + TanStack Router + shadcn/ui)
mobile/ React Native (Expo) companion app
tools/ Python utility scripts
OpenPraxis registers Claude Code hooks in ~/.claude/settings.json:
| Hook | Trigger | What it does |
|---|---|---|
PostToolUse (*) |
Every tool call | Records action, checks visceral compliance + manifest delusion |
PreToolUse (mcp__openpraxis__*) |
OpenPraxis tool calls | Enforces visceral rules are loaded first |
| UserPromptSubmit | User sends message | Tracks session activity |
| Stop | Session ends | Checks compliance, flags amnesia, saves conversation |
| SessionEnd | Session cleanup | Saves conversation from transcript |
All hooks hit http://127.0.0.1:9966/api/hook.
OpenPraxis instances discover each other via mDNS on the local network and synchronize using Automerge CRDTs. Each node has a stable UUID v7 identity and MAC fingerprint.
Laptop (OpenPraxis) <--mDNS--> Desktop (OpenPraxis) <--mDNS--> Server (OpenPraxis)
Memories, conversations, manifests, and visceral rules sync automatically. Each peer maintains its own SQLite database — sync is eventually consistent.
Default config at ~/.openpraxis/config.yaml:
node:
uuid: "auto-generated-uuidv7"
display_name: "Your Name"
email: "you@example.com"
avatar: "\U0001F989"
server:
host: 127.0.0.1
port: 9966
open_browser: true
sync:
host: 0.0.0.0
port: 6699
embedding:
ollama_url: http://localhost:11434
model: nomic-embed-text
dimension: 768
storage:
data_dir: ~/.openpraxis/dataReact Native (Expo) companion app — acts as a full OpenPraxis peer from your phone. Create manifests, schedule tasks, monitor execution, browse memories. Syncs to laptop peers over local network.
cd mobile
npm install
npx expo startApache License 2.0. See LICENSE.










