# smfworks/praxis-prime architecture

> Architecture diagram of the GitHub repository smfworks/praxis-prime, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smfworks/praxis-prime
- Repository: https://github.com/smfworks/praxis-prime

## Overview

Praxis Prime is a local-first governed AI agent. The main workflow starts with a CLI or gateway request, runs through the agent loop, routes model calls, checks tool actions against policy and approvals, and returns a response; consequential actions wait for human approval. The README also documents coding mode, Telegram, a local decision engine, memory, audit, and optional compliance dials. Several subsystem links rely on README-level architecture or SOURCE INDEX references; unsampled internals and stub features are represented cautiously.

Main entry points: [`packages/prime-core/praxis_prime/loop/engine.py`](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/loop/engine.py) (Agent loop), [`packages/prime-core/praxis_prime/cli.py`](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/cli.py) (CLI), [`packages/prime-core/praxis_prime/gateway/server.py`](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/gateway/server.py) (Loopback gateway), [`packages/prime-core/praxis_prime/coding/session.py`](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/coding/session.py) (Coding mode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>[cli.py]"]
  node_repl["Interactive chat<br/>[repl.py]"]
  node_gateway["Loopback gateway<br/>[server.py]"]
  node_telegram["Telegram channel<br/>[telegram.py]"]
end

subgraph group_agent["Agent runtime"]
  node_runtime["Runtime setup<br/>[runtime.py]"]
  node_loop["Agent loop<br/>[engine.py]"]
  node_prompt["Prompt and events<br/>[prompt.py]"]
  node_memory[("Memory store<br/>[store.py]")]
  node_state[("Session state<br/>[state.py]")]
end

subgraph group_governance["Governance"]
  node_audit[("Audit log<br/>[log.py]")]
  node_policy["Policy engine<br/>[engine.py]"]
  node_approvals["Approval gate<br/>[gate.py]"]
  node_approval_queue["Approval queue<br/>[queue.py]"]
  node_decision["Decision engine<br/>[engine.py]"]
end

subgraph group_integrations["Models and tools"]
  node_router["Model router<br/>[router.py]"]
  node_model(("Model provider"))
  node_tools["Tool registry<br/>[registry.py]"]
  node_sandbox["Shell sandbox<br/>[bwrap.py]"]
end

subgraph group_extensions["Product capabilities"]
  node_coding["Coding mode<br/>[session.py]"]
  node_worktree["Git worktrees<br/>[worktree.py]"]
  node_compliance["Compliance dials<br/>[dials.py]"]
  node_jurisdiction["NC jurisdiction pack<br/>[nc.py]"]
end

node_user(("User"))

node_user -->|"starts request"| node_cli
node_cli -->|"opens chat"| node_repl
node_cli -->|"creates runtime"| node_runtime
node_cli -->|"starts coding"| node_coding
node_user -->|"sends request"| node_gateway
node_gateway -->|"dispatches turns"| node_loop
node_telegram -->|"uses protocol"| node_gateway
node_telegram -->|"presents approvals"| node_approval_queue
node_runtime -->|"provides runtime"| node_loop
node_loop -->|"requests completion"| node_router
node_router -->|"streams tokens"| node_model
node_loop -->|"builds prompts"| node_prompt
node_loop -->|"dispatches tools"| node_tools
node_loop -->|"checks actions"| node_policy
node_loop -->|"authorizes actions"| node_approvals
node_gateway -->|"serves approvals"| node_approval_queue
node_loop -->|"reads and writes"| node_memory
node_memory -->|"persists data"| node_state
node_audit -->|"stores audit"| node_state
node_tools -->|"runs shell safely"| node_sandbox
node_coding -->|"creates worktree"| node_worktree
node_coding -->|"runs coding task"| node_loop
node_loop -->|"screens requests"| node_decision
node_policy -->|"applies active dials"| node_compliance
node_compliance -.->|"includes pack"| node_jurisdiction

click node_cli "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/cli.py"
click node_repl "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/repl.py"
click node_gateway "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/gateway/server.py"
click node_telegram "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/channels/telegram.py"
click node_runtime "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/runtime.py"
click node_loop "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/loop/engine.py"
click node_prompt "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/loop/prompt.py"
click node_memory "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/memory/store.py"
click node_state "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/state.py"
click node_audit "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/audit/log.py"
click node_policy "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/policy/engine.py"
click node_approvals "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/approvals/gate.py"
click node_approval_queue "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/approvals/queue.py"
click node_decision "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/decide/engine.py"
click node_router "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/router/router.py"
click node_tools "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/tools/registry.py"
click node_sandbox "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/sandbox/bwrap.py"
click node_coding "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/coding/session.py"
click node_worktree "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/coding/worktree.py"
click node_compliance "https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/policy/dials.py"
click node_jurisdiction "https://github.com/smfworks/praxis-prime/blob/main/packs/jurisdictions/nc.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_repl,node_gateway,node_telegram,node_user toneBlue
class node_runtime,node_loop,node_prompt,node_memory,node_state toneAmber
class node_audit,node_policy,node_approvals,node_approval_queue,node_decision toneMint
class node_router,node_model,node_tools,node_sandbox toneRose
class node_coding,node_worktree,node_compliance,node_jurisdiction toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/cli.py): `packages/prime-core/praxis_prime/cli.py`
- [Interactive chat](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/repl.py): `packages/prime-core/praxis_prime/repl.py`
- [Loopback gateway](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/gateway/server.py): `packages/prime-core/praxis_prime/gateway/server.py`
- [Telegram channel](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/channels/telegram.py): `packages/prime-core/praxis_prime/channels/telegram.py`

### Agent runtime

- [Runtime setup](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/runtime.py): `packages/prime-core/praxis_prime/runtime.py`
- [Agent loop](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/loop/engine.py): `packages/prime-core/praxis_prime/loop/engine.py`
- [Prompt and events](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/loop/prompt.py): `packages/prime-core/praxis_prime/loop/prompt.py`
- [Memory store](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/memory/store.py): `packages/prime-core/praxis_prime/memory/store.py`
- [Session state](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/state.py): `packages/prime-core/praxis_prime/state.py`

### Governance

- [Audit log](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/audit/log.py): `packages/prime-core/praxis_prime/audit/log.py`
- [Policy engine](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/policy/engine.py): `packages/prime-core/praxis_prime/policy/engine.py`
- [Approval gate](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/approvals/gate.py): `packages/prime-core/praxis_prime/approvals/gate.py`
- [Approval queue](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/approvals/queue.py): `packages/prime-core/praxis_prime/approvals/queue.py`
- [Decision engine](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/decide/engine.py): `packages/prime-core/praxis_prime/decide/engine.py`

### Models and tools

- [Model router](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/router/router.py): `packages/prime-core/praxis_prime/router/router.py`
- **Model provider**
- [Tool registry](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/tools/registry.py): `packages/prime-core/praxis_prime/tools/registry.py`
- [Shell sandbox](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/sandbox/bwrap.py): `packages/prime-core/praxis_prime/sandbox/bwrap.py`

### Product capabilities

- [Coding mode](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/coding/session.py): `packages/prime-core/praxis_prime/coding/session.py`
- [Git worktrees](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/coding/worktree.py): `packages/prime-core/praxis_prime/coding/worktree.py`
- [Compliance dials](https://github.com/smfworks/praxis-prime/blob/main/packages/prime-core/praxis_prime/policy/dials.py): `packages/prime-core/praxis_prime/policy/dials.py`
- [NC jurisdiction pack](https://github.com/smfworks/praxis-prime/blob/main/packs/jurisdictions/nc.py): `packs/jurisdictions/nc.py`

### Other components

- **User**

## Connections

- User → CLI: starts request
- CLI → Interactive chat: opens chat (evidence: `packages/prime-core/praxis_prime/cli.py`)
- CLI → Runtime setup: creates runtime (evidence: `packages/prime-core/praxis_prime/cli.py`)
- CLI → Coding mode: starts coding (evidence: `packages/prime-core/praxis_prime/cli.py`)
- User → Loopback gateway: sends request
- Loopback gateway → Agent loop: dispatches turns
- Telegram channel → Loopback gateway: uses protocol (evidence: `packages/prime-core/praxis_prime/channels/telegram.py`)
- Telegram channel → Approval queue: presents approvals (evidence: `packages/prime-core/praxis_prime/channels/telegram.py`)
- Runtime setup → Agent loop: provides runtime (evidence: `packages/prime-core/praxis_prime/coding/session.py`)
- Agent loop → Model router: requests completion (evidence: `packages/prime-core/praxis_prime/loop/engine.py`)
- Model router → Model provider: streams tokens
- Agent loop → Prompt and events: builds prompts (evidence: `packages/prime-core/praxis_prime/loop/engine.py`)
- Agent loop → Tool registry: dispatches tools (evidence: `packages/prime-core/praxis_prime/loop/engine.py`)
- Agent loop → Policy engine: checks actions (evidence: `packages/prime-core/praxis_prime/loop/engine.py`)
- Agent loop → Approval gate: authorizes actions (evidence: `packages/prime-core/praxis_prime/loop/engine.py`)
- Loopback gateway → Approval queue: serves approvals (evidence: `packages/prime-core/praxis_prime/gateway/server.py`)
- Agent loop → Memory store: reads and writes (evidence: `packages/prime-core/praxis_prime/loop/engine.py`)
- Memory store → Session state: persists data (evidence: `packages/prime-core/praxis_prime/memory/store.py`)
- Audit log → Session state: stores audit (evidence: `packages/prime-core/praxis_prime/audit/log.py`)
- Tool registry → Shell sandbox: runs shell safely
- Coding mode → Git worktrees: creates worktree (evidence: `packages/prime-core/praxis_prime/coding/session.py`)
- Coding mode → Agent loop: runs coding task (evidence: `packages/prime-core/praxis_prime/coding/session.py`)
- Agent loop → Decision engine: screens requests (evidence: `packages/prime-core/praxis_prime/loop/engine.py`)
- Policy engine → Compliance dials: applies active dials (evidence: `packages/prime-core/praxis_prime/policy/engine.py`)
- Compliance dials → NC jurisdiction pack: includes pack