{"id":50445419,"url":"https://github.com/coe0718/praxis","last_synced_at":"2026-05-31T21:02:53.952Z","repository":{"id":348239443,"uuid":"1196659949","full_name":"coe0718/praxis","owner":"coe0718","description":"Praxis","archived":false,"fork":false,"pushed_at":"2026-05-20T01:26:13.000Z","size":26156,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T04:45:35.898Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coe0718.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":"audit.toml","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-30T23:12:16.000Z","updated_at":"2026-05-20T01:26:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"0e208fbf-2731-45e1-93df-615992aba726","html_url":"https://github.com/coe0718/praxis","commit_stats":null,"previous_names":["coe0718/praxis"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/coe0718/praxis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coe0718%2Fpraxis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coe0718%2Fpraxis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coe0718%2Fpraxis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coe0718%2Fpraxis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coe0718","download_url":"https://codeload.github.com/coe0718/praxis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coe0718%2Fpraxis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33748607,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-31T21:02:42.712Z","updated_at":"2026-05-31T21:02:53.927Z","avatar_url":"https://github.com/coe0718.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Praxis\n\nSelf-hosted personal AI agent infrastructure in Rust.\n\nPraxis is built for one operator, long-running local state, and safe autonomous behavior. It is not a hosted assistant and not a generic chatbot shell. The goal is a private, durable agent runtime that can wake up, inspect its own world, learn from execution history, and become more useful over time without losing operator trust.\n\nThe reference implementation is Axonix. Praxis is the framework extraction of those patterns into a reusable codebase.\n\n## Why Praxis\n\n- Private by default: local files, local SQLite, self-hosted runtime.\n- Built to last: identity, goals, memory, analytics, and proposals survive across sessions.\n- Safety-first autonomy: approvals, path policy checks, loop guards, quality gates, and deterministic offline fallbacks.\n- Rust and Docker friendly: single binary, small modules, and container-ready workflows from the start.\n\n## Current Status\n\nPraxis is in active development, but it is already a working local operator runtime.\n\nShipped today:\n\n- Lightweight `praxis ask ...` prompts that do not create or mutate session state\n- Resumable `orient -\u003e decide -\u003e act -\u003e reflect -\u003e sleep` session loop\n- Linux/macOS path handling plus Docker-first data-dir support\n- Markdown identity and goal files with dependency-aware goal selection\n- Parent/child goal metadata so open child work is selected before umbrella parent goals\n- SQLite-backed sessions, approvals, memories, reviews, evals, forensics, learning runs, and provider usage\n- Context budgeting, anatomy indexing, repeated-read avoidance, and token/cost ledgers\n- Anchor-preserving summarization for oversized context sources\n- Adaptive context allocation that nudges source budgets based on prior successful sessions\n- Hot/cold memory search plus operational memory for do-not-repeat notes and known bugs\n- In-place cold-memory decay for stale long-term memories, without blindly demoting them back to hot memory\n- Tool registry, approval queue, path policy enforcement, and loop guards for identical or repeating multi-step tool patterns\n- File-mutation circuit breakers for excessive protected-file writes or oversized append payloads\n- First real tool execution path for approved append-only writes inside allowed Praxis data files\n- Auto-maintained `CAPABILITIES.md` notes for installed tools, recent examples, and failure history\n- Provider routing with `stub`, Claude, OpenAI, Ollama, and router-mode failover\n- Explicit `budgets.toml` limits for ask/run attempt count, token spend, and estimated cost\n- Named model profiles in `profiles.toml` so `quality`, `budget`, and `offline` modes can steer backend behavior and context aggressiveness\n- Opt-in local-first fallback so low-risk `ask` and `act` phases can prefer Ollama before cloud providers\n- Model canary ledger plus `freeze_on_model_regression` gating so remote routes can be frozen until they pass an explicit canary run\n- Runtime heartbeat file plus `praxis heartbeat check` and `scripts/check-heartbeat.sh` for external liveness checks\n- Telegram, Discord, Slack, and WhatsApp operator surfaces plus a lightweight web API/SSE server for the frontend dashboard\n- Boundary maintenance commands plus recurring weekly review prompts surfaced in `status` and `/boundaries`\n- Explicit attachment policies for `praxis ask --file ...`, with visible reject, chunk, or summarize handling for oversized text files\n- Reviewer/eval quality gates during Reflect\n- Automatic markdown postmortems for reviewer failures, eval regressions, and similar bad outcomes\n- Fixture-backed replay tests for stateful session, forensics, and approval flows\n- Argus analysis for drift, repeated work, failures, and token hotspots\n- Learning runtime that mines opportunities and syncs them into `PROPOSALS.md`\n- Opportunity acceptance that promotes mined work into durable goals in `GOALS.md`\n- Manifest-versioned state export/import plus human-readable audit export\n- MCP (Model Context Protocol) server + client in `src/mcp/` with tool discovery, tool execution, and both stdio and SSE transport\n- Agent-to-agent delegation via `src/delegation/` with concurrency caps, allow/deny task filtering, and A2A protocol fallback\n- Plugin system with `src/plugins/` including discovery, validation, lifecycle hooks, and marketplace queries\n- Optional daily backup snapshots with retention pruning on top of manual export/import\n- `AGENTS.md` pattern capture with CLI support for future-run conventions and gotchas\n- AES-256-GCM at-rest encryption for `vault.toml` and `oauth_tokens.json` via a `master.key` generated on init\n- Automatic git state sync: every Reflect phase commits session state to the data-dir repo if one exists\n\nNot finished yet:\n\n- Two-process watchdog daemon (binary swap automation; CLI update/rollback exists)\n- Zero-LLM deterministic mode (StubBackend exists but no rule-based logic path)\n- Voice transcript streaming (Whisper integration)\n- Serverless/edge entry point (Cloudflare Workers / AWS Lambda)\n\n## Quick Start\n\nInitialize a local Praxis data directory:\n\n```bash\ncargo run -- --data-dir ./local-data init --name \"Praxis\" --timezone UTC\n```\n\nRun a single session:\n\n```bash\ncargo run -- --data-dir ./local-data run --once\n```\n\nInspect the current state:\n\n```bash\ncargo run -- --data-dir ./local-data status\n```\n\nValidate the installation:\n\n```bash\ncargo run -- --data-dir ./local-data doctor\n```\n\nBy default Praxis uses the deterministic `stub` backend, so the basic workflow works fully offline.\n\n## Provider Setup\n\n`praxis init` seeds both `praxis.toml` and `providers.toml`.\n\nUse a single remote backend:\n\n```toml\n[agent]\nbackend = \"claude\"\n```\n\n```bash\nexport ANTHROPIC_API_KEY=...\n```\n\nOr enable routed failover:\n\n```toml\n[agent]\nbackend = \"router\"\n```\n\n```toml\n[[providers]]\nprovider = \"claude\"\nmodel = \"claude-3-5-sonnet-latest\"\n\n[[providers]]\nprovider = \"openai\"\nmodel = \"gpt-5.4-mini\"\n\n[[providers]]\nprovider = \"ollama\"\nmodel = \"llama3.2\"\nbase_url = \"http://127.0.0.1:11434\"\n```\n\nWhen router mode is active, Praxis records every provider attempt, token count, and estimated cost in SQLite so `status` and Argus can explain what actually happened.\n\nIf you want Praxis to freeze remote model use until a provider/model pair passes an explicit probe, enable:\n\n```toml\n[agent]\nfreeze_on_model_regression = true\n```\n\nThen record a canary before normal remote use:\n\n```bash\ncargo run -- --data-dir ./local-data canary run\ncargo run -- --data-dir ./local-data canary status\n```\n\nAsk can also ingest local UTF-8 text attachments with an explicit overflow policy:\n\n```bash\ncargo run -- --data-dir ./local-data ask \\\n  --file ./notes/brief.md \\\n  --attachment-policy summarize \\\n  \"Pull out the action items.\"\n```\n\n## Docker\n\nPraxis is intended to stay runnable in Docker from the start.\n\nInitialize container state:\n\n```bash\ndocker compose run --rm praxis-init\n```\n\nRun one session:\n\n```bash\ndocker compose run --rm praxis-run\n```\n\nCheck status:\n\n```bash\ndocker compose run --rm praxis-status\n```\n\nThe compose file binds `./docker-data` to `/var/lib/praxis`, so state persists across container runs.\n\n## Core Workflows\n\n### Daily Runtime\n\n- `praxis ask ...`\n- `praxis run --once`\n- `praxis status`\n- `praxis doctor`\n- `praxis boundaries show`\n- `praxis forensics latest`\n- `praxis argus --limit 10`\n\n`praxis ask ...` is synchronous and stateless. `praxis run --once` is a real session run that updates durable Praxis state.\n\n### Approvals and Tools\n\n- `praxis queue`\n- `praxis approve \u003cid\u003e`\n- `praxis reject \u003cid\u003e`\n- `praxis tools list`\n- `praxis tools register ...`\n- `praxis tools request ...`\n\nCurrent real execution slice:\n\n```bash\ncargo run -- --data-dir ./local-data tools request \\\n  --name praxis-data-write \\\n  --summary \"Append reviewed journal note\" \\\n  --write-path JOURNAL.md \\\n  --append-text \"Operator approved this note.\"\n```\n\nAfter approval, `praxis run --once` will execute that request by appending the approved text to the declared allowed file inside the Praxis data directory.\n\n### Learning and Opportunity Mining\n\nPraxis can ingest notes from `learning/sources/`, synthesize learnings, detect repeated work, and create a throttled proposal queue:\n\n```bash\ncargo run -- --data-dir ./local-data learn note \"Prefer cargo test --locked before pushing\"\ncargo run -- --data-dir ./local-data learn run\ncargo run -- --data-dir ./local-data learn list\ncargo run -- --data-dir ./local-data learn accept 1\ncargo run -- --data-dir ./local-data learn dismiss 2\n```\n\n`LEARNINGS.md` is now an append-only operational log. Manual `learn note` entries and automatic source syntheses both append structured timestamped records instead of rewriting history.\n\nAccepted opportunities are not just status changes. Praxis links them into `PROPOSALS.md` and promotes them into `GOALS.md`, so the main loop can pick them up as real work later.\n\n### Future-Run Notes\n\nPraxis now has an explicit `AGENTS.md` surface for project-specific conventions, gotchas, and handoff notes that future sessions should load early:\n\n```bash\ncargo run -- --data-dir ./local-data agents view\ncargo run -- --data-dir ./local-data agents add --section workflow --note \"Prefer project-local scripts over one-off shell commands.\"\ncargo run -- --data-dir ./local-data agents add --section gotcha --note \"Docker rebuilds are expected to take a while after backend changes.\"\n```\n\nThat file is part of the foundation set, is loaded into Orient as its own context source, and is included in portable exports/imports.\n\n### Boundaries\n\nPraxis now treats hard limits as a maintained surface instead of a one-time setup note:\n\n```bash\ncargo run -- --data-dir ./local-data boundaries show\ncargo run -- --data-dir ./local-data boundaries add Never deploy after midnight\ncargo run -- --data-dir ./local-data boundaries confirm --note \"Reviewed after setup\"\n```\n\n`status` and Telegram `/boundaries` will surface when the weekly alignment review is due and explicitly ask whether hard limits changed.\n\n### Durability and Audit\n\nPraxis can now export a portable state bundle, import it into a different data directory, and generate a human-readable audit report:\n\n```bash\ncargo run -- --data-dir ./local-data export state --output ./praxis-backup\ncargo run -- --data-dir ./restored-data import --input ./praxis-backup\ncargo run -- --data-dir ./local-data export audit --output ./audit.md --days 30\n```\n\nState bundles include a versioned manifest, the SQLite schema version, runtime state, config, tools, goals, evals, learning sources, and the core markdown identity files. Imports re-home the config to the target data directory so restores stay portable across machines and Docker paths.\n\n### Messaging and Live Views\n\nPraxis supports Telegram, Discord, Slack, and WhatsApp as operator-facing messaging surfaces. Telegram support currently includes doctoring, polling, and command routing:\n\n```bash\nexport PRAXIS_TELEGRAM_BOT_TOKEN=...\nexport PRAXIS_TELEGRAM_ALLOWED_CHAT_IDS=12345,67890\n\ncargo run -- --data-dir ./local-data telegram doctor\ncargo run -- --data-dir ./local-data telegram poll-once\ncargo run -- --data-dir ./local-data telegram run --cycles 0\n```\n\nWhatsApp uses the Meta Cloud API for text messages and webhooks:\n\n```bash\nexport PRAXIS_WHATSAPP_PHONE_ID=...\nexport PRAXIS_WHATSAPP_ACCESS_TOKEN=...\nexport PRAXIS_WHATSAPP_WEBHOOK_VERIFY_TOKEN=...\n```\n\nMessaging semantics match the CLI split:\n\n- `/ask \u003cprompt\u003e` is low-latency and does not create a Praxis session.\n- `/run \u003ctask\u003e` executes a real stateful session and bypasses quiet-hours deferral because the operator explicitly requested it.\n\nRun the local web API/SSE server:\n\n```bash\ncargo run -- --data-dir ./local-data serve --host 127.0.0.1 --port 8787\n```\n\n## Architecture At A Glance\n\n- `src/loop/`: session runtime and phase orchestration\n- `src/context/`: budget engine and context assembly\n- `src/anatomy/`: file summaries, token estimates, and repeated-read avoidance\n- `src/identity/`: foundation files, goal parsing, and goal promotion\n- `AGENTS.md`: future-run conventions, gotchas, and handoff notes\n- `src/memory/`: memory loading plus operational memory support\n- `src/storage/`: SQLite persistence for runtime state and analytics\n- `src/tools/`: registry, policy, approval flow, and loop guards\n- `src/backend/` and `src/providers/`: model/provider execution and routing\n- `src/evolution/`: proposal lifecycle, performance scoring, and adaptive behaviour\n- `src/delegation/`: agent-to-agent delegation with A2A protocol fallback\n- `src/mcp/`: Model Context Protocol (server + client)\n- `src/speculative/`: multi-branch speculative execution with trust constraints\n- `src/cli/`: all `praxis \u003csub\u003e` commands and TUI\n- `src/config/`: `praxis.toml` model, validation, and hot-reload watcher\n- `src/plugins/`: plugin system with marketplace and registry\n- `src/a2a/`: Agent-to-Agent protocol client\n- `src/vault/`: AES-256-GCM encrypted credentials storage\n- `src/kanban/`: built-in kanban task board\n- `src/quality/`: reviewer and eval gates\n- `src/learning/`: learning runtime, opportunity mining, and proposal sync\n- `src/argus/`: drift, failure, repeated-work, and token hotspot analysis\n- `src/messaging/`, `src/web/`, and `frontend/`: Telegram/Discord/Slack/WhatsApp operator surfaces, web API/SSE server, and React dashboard\n- `docs/agent_runtime.md`: runtime boundary, adapter ownership, and replacement plan\n- [`docs/modules/`](docs/modules/): per-module API reference docs with public API, configuration, and examples\n- `tests/`: end-to-end CLI coverage\n\nThe codebase follows a small-module style and aims to keep Rust source files under 250 lines.\n\n## Development\n\nRun the main verification steps locally:\n\n```bash\ncargo fmt --all\ncargo test --locked\ndocker build --tag praxis:ci .\n```\n\nThe project currently targets offline-deterministic tests by default. Live providers and messaging surfaces are wired behind explicit configuration and environment variables.\n\n## Design And Roadmap\n\nThe canonical design document is [PRAXIS_DESIGN.md](PRAXIS_DESIGN.md). It tracks:\n\n- core runtime architecture\n- adopted ideas and future enhancements\n- build-order status\n- what is already implemented versus what is still planned\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoe0718%2Fpraxis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoe0718%2Fpraxis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoe0718%2Fpraxis/lists"}