⚡ XR — The AI Agent You Can Actually Trust

BYOK · local-first · local model intelligence · spend-capped · tamper-evident · safe computer control · multi-step planner · plan memory · durable memory

---

You bring the key. We ship none.
XR runs on your provider API key or your local model — it costs us $0 to maintain and you $0 to trust.

---

🚀 Install in 30 Seconds

# Linux / macOS / Termux
curl -fsSL https://raw.githubusercontent.com/ahmadrrrtx/xr/main/install.sh | bash

# Windows
iex (irm https://raw.githubusercontent.com/ahmadrrrtx/xr/main/install.ps1)

# First-time setup wizard (picks provider, model, budget)
xr onboarding

After install:

xr "build me a hello-world TypeScript project with tests"
xr doctor                         # check everything is healthy
xr serve                          # open the local dashboard at 127.0.0.1:7842

---

🏛️ v1.0 Foundation Runtime: The AI OS Kernel

XR has evolved from a modular agent script into a True AI Operating System. The v1.0 Foundation Runtime introduces a hardened kernel that ensures stability, security, and infinite extensibility.

• Service Container (DI): A lightweight dependency injection system that manages services (Agent, Budget, Provider, Plugins) with a strictly controlled lifecycle.
• Lifecycle Management: Formal Bootstrap $\rightarrow$ Start $\rightarrow$ Stop sequence ensuring all subsystems are healthy before the agent takes the wheel.
• Specialized Store Architecture: The monolithic database has been decomposed into specialized, isolated stores (Session, Audit, Memory, Cost, Skill), preventing state corruption and enabling independent scaling.
• Command Registry: Decoupled CLI commands. Adding a new system capability no longer requires modifying the core router.
• Event-Driven Core: An internal Event Bus allowing decoupled services to communicate asynchronously without tight coupling.

---

✨ What Makes XR Different

	Most AI agents	XR
Provider	locked to vendor	BYOK — any of 12+ providers, or fully local via Ollama
Cost	"soft" warnings	hard ceiling enforced in code (checkBeforeStep())
Security	trust us	deterministic injection benchmark, signed block-rate report
Audit	scrollback only	SHA-256 hash chain — tamper-evident, offline, free
Computer Control	wild west	safe-by-construction — classify → preview → approve → audit
Multi-step planner	hidden prompts	typed Action[] schema validated with Zod, every step previewed
Browser automation	none / hardcoded	Playwright backend — DOM selectors, opt-in, lazy-loaded
Plan memory	none	cached deterministic plans — second run skips the LLM
Dashboard	cloud-only	127.0.0.1 only, token-authed, live approvals, no telemetry
Voice	cloud STT	local Whisper + Kokoro by default, push-to-talk
Runtime	procedural script	AI OS Kernel with DI and Lifecycle management

---

🎯 Core Features

🖥 Safe Computer Control (v0.8 → v0.8.2)

The killer feature of XR — your AI can actually control the computer, and you can actually trust it.

xr control start                              # opt-in (off by default)
xr control plan "open github.com and search for ahmadrrrtx" --yes

Four execution layers, all enforced in code:

1. Action schema — every action is a typed, Zod-validated Action variant. Garbage cannot reach the OS.
2. Risk classifier — pure function returns safe | sensitive | destructive. Single source of truth.
3. Approval gate — safe runs immediately; sensitive prompts; destructive always prompts (even with --yes).
4. Hash-chained audit — every plan, exec, denial, memory hit is appended to the tamper-evident log.

Approvals work from both the CLI prompt and the dashboard "Approve / Deny" buttons — whichever responds first wins.

🧭 Multi-Step Planner (v0.8.1)

Type or speak a natural-language task; XR's planner LLM emits a validated Action[] plan. You preview it (dry-run default), then approve to execute.

xr control plan "fill the contact form on example.com"               # dry-run
xr control plan "fill the contact form on example.com" --step        # confirm each
xr control plan "fill the contact form on example.com" --yes         # auto-approve sensitive

The planner cannot smuggle dangerous actions: every emitted action is re-classified before execution.

🌐 Browser Automation (Playwright, v0.8.1)

First-class browser variant in the Action schema. DOM selectors instead of brittle coordinates.

xr control browser status                   # check Playwright availability
xr control browser install                  # one-shot: install + chromium (~150 MB)
xr control browser close                    # close the session

Browser ops are inherently safer than desktop ops (selectors are deterministic). submit, sensitive fill, javascript: and executable goto targets are auto-classified destructive.

🧠 Plan Memory (v0.8.2)

Successful plans get cached deterministically. The next time you run the same task, XR skips the LLM entirely — zero cost, instant response, same safety pipeline.

xr control plan "open github notifications" --yes   # first run: LLM plans (~$0.002)
xr control plan "open github notifications" --yes   # next run: ⚡ recalled, $0.00
xr control memory list                              # see what XR remembers
xr control memory show "open github notifications"  # inspect actions
xr control memory forget "open github notifications"
xr control memory clear                             # forget everything

Hard safety gates (refuses to memoize):

• Plans with sensitive: true actions (passwords / secrets)
• Plans with destructive actions (form submits, Enter, file://, executables)
• Failed, dry-run, or partial runs
• Plans longer than 20 actions

Recall re-validates everything: cached actions are re-parsed against the current Zod schema and re-classified. Schema drift or newly-destructive actions silently invalidate the cache so the planner falls back to the LLM.

Plan memory ≠ durable memory. Plan memory caches control plans; durable memory (below) stores your preferences, projects and facts.

🧠 Durable Memory (v0.9)

XR remembers your preferences, projects, and long-term facts — only what you explicitly ask it to. No silent auto-save, no hidden background capture. Everything is local-first, inspectable, editable, and permanently deletable.

xr memory add "I prefer TypeScript and Bun" --category preference
xr memory add "this project is called XR" --category project --scope xr
xr memory list                              # see everything XR remembers
xr memory recall "what do I prefer?"        # exactly what chat/voice will surface
xr memory search "bun"                      # keyword search
xr memory edit  mem_ab12 "prefer Bun + Zod" # change an entry
xr memory remove mem_ab12                   # forget one entry (permanent)
xr memory clear                             # forget everything (asks first)
xr memory export memories.json              # take your memory with you
xr memory import memories.json              # merge a bundle (dedupes)

In chat and voice it's conversational:

"Remember I prefer TypeScript and Bun"        → saved as a preference
"Remember this project is called XR"          → saved as project context
"What do you know about my preferences?"      → reads them back
"Forget this note"                            → deletes it
"Don't remember my email"                     → a do-not-remember rule

Categories (namespaces): preference · project · workflow · fact · exclusion

How recall works: when you run a task, XR surfaces only the few entries relevant to that task as one clearly-labelled reference block — never every memory on every prompt. exclusion rules are never surfaced and actively block matching content from ever being stored.

Semantic recall (v0.9): retrieval uses embeddings (local Ollama nomic-embed-text) for meaning-based matching, with an automatic, dimension-safe lexical fallback so it works even with no embedding model — fully offline, never crashes. Embeddings are cached per entry and computed lazily on first recall (or warmed with xr memory reindex). Force deterministic keyword scoring with xr memory recall "…" --lexical, or disable globally with memory.semanticRecall: false.

Summarization (v0.9): keep long-lived memory tidy with xr memory summarize — it folds old, low-importance entries (per category/scope) into compact digests. It's a two-phase, approval-first flow: it proposes what would fold, then asks before changing anything (--dry-run to preview, -y to skip the prompt). Deterministic, and exclusion rules are never folded.

xr memory summarize --dry-run               # preview the proposal, change nothing
xr memory summarize --days 60 --max-importance 2   # tune the criteria
xr memory summarize -y                       # apply (folds old notes → digests)

Short-term ≠ long-term: ephemeral conversation recaps live in a separate session_summaries store (xr memory summaries) and never leak into durable memory.

Privacy & control

• Local-first: stored in ~/.xr/xr.db, never synced anywhere by default.
• Explicit by default: only what you ask is stored.
• Disable entirely: memory.enabled: false in config, or XR_MEMORY_DISABLED=1.
• Logs/telemetry never contain raw memory content — only ids and counts.
• Research findings are saved only on request: xr research remember [id].

🧠 Local Model Intelligence (v0.5)

xr models recommend         # auto-detects RAM/CPU → picks the right Ollama model
xr models install            # one-click download
xr models test               # smoke test

Hybrid routing: cloud for hard tasks, local for cheap ones, with automatic fallback when the budget is exhausted.

🔬 Research Mode (v0.7)

xr research "compare Rust vs Go for embedded development"
xr research deep "best self-hosted alternatives to Cloudflare Tunnel"
xr research plan "topic"      # generate a structured research plan
xr research export            # export latest report to markdown

Source-first, multi-search-engine, deduplicated, with inline citations.

🧩 Plugin Ecosystem (1.0)

xr plugins install ./plugins/github   # shows permissions, asks to approve
xr plugins enable github              # explicit, conscious step
xr plugin github repo ahmadrrrtx/xr   # run a plugin command

XR gains new integrations and skills through plugins, not by editing core
code. Plugins are local-first, permission-based, and sandboxed by design:

• A plugin only ever sees a frozen host — never the database, raw config,
  process.env, fetch, or node:fs.
• A capability (net, fs, secrets, memory, provider, …) exists only
  for a permission you explicitly granted.
• Plugins inherit and cannot bypass the egress allow-list, spend caps,
  memory rules, and the tamper-evident audit log.
• The entrypoint is hashed at install; a tampered plugin is refused as
  untrusted. A broken plugin is isolated — XR core never goes down.
• Plugin tools reach the agent as plugin.<id>.<name> and are approval-gated.

Full spec, permission model, and a writing guide: docs/PLUGINS.md.

🤖 JARVIS-Level Vision Loop

xr --computer "open Safari and search for AI agents"

Vision-driven screenshot → LLM reasons → action loop. Different from xr control — this is for open-ended tasks where the planner doesn't know the steps in advance.

💰 Cost Governor — Enforced in Code

xr --budget 0.10 "write me a full React app"

The agent literally cannot exceed your budget. checkBeforeStep() runs before every model call and blocks if the next step would breach the ceiling.

🛡️ Provable Security

xr test --attacks --json   # → signed publishable block-rate report

Runs a deterministic prompt-injection attack corpus and prints the block-rate with SHA-256 signature.

🔒 Tamper-Evident Audit Log

xr verify-log              # → "✓ Audit chain intact (N entries)"

SHA-256 hash chain (git's trick, $0, offline). Every control event, every tool call, every approval is in the chain. Any tampering is detected.

🧠 Non-Regressive Skills

Every successful verified task can be frozen as an immutable baseline. Any update that breaks a past win is auto-rolled-back.

🐳 Docker Sandbox

Shell commands optionally run in an isolated container with dropped capabilities and no network.

🎙️ Voice Control

xr voice start                              # wake word → STT → agent → TTS
xr speak "hello world"
xr listen

Voice commands route through the same safety pipeline as the CLI — voice can never bypass approvals. Recognized control intents:

• "Open the app Safari" → app
• "Go to https://example.com" → open
• "Type this message: hello" → type
• "Press cmd+tab" → key
• "Focus the Chrome window" → focus
• "Scroll down" → scroll

📊 Dashboard (v0.8.1)

xr serve                    # opens 127.0.0.1:7842
xr serve --port 8000 --token mytoken

• Cost cockpit (live)
• Security posture (injection block-rate)
• Audit explorer (with hash chain)
• Computer Control panel with:
  • Capability matrix (kbd / mouse / launcher / browser)
  • Pending approvals with Approve/Deny buttons
  • Live event stream
  • 🧠 Remembered plans list with per-row forget + clear-all
• 🧠 Durable Memory panel (v0.9):
  • Live view of saved preferences, projects & facts (category-colored, importance stars)
  • Per-entry forget + clear-all (read-only otherwise — add/edit stay CLI-only)
  • Do-not-remember (exclusion) rules are never shown in the browser

📱 Multi-Channel

• CLI — full TUI with streaming + slash commands
• Telegram — ✅/❌ approval buttons, user allow-list
• Dashboard — 127.0.0.1:7842 with live audit, cost cockpit, security posture, computer control

---

📋 Every Command

Core

xr "your task"                            # run a task (default: agent mode)
xr "..." --mode plan                      # plan mode (no side effects)
xr "..." --mode ask                       # ask mode (read-only)
xr "..." --budget 0.25                    # hard $ ceiling for this task
xr "..." --provider openai --model gpt-4o # override provider + model
xr "..." --dry-run                        # simulate everything
xr "..." --max-steps 20                   # safety rail
xr "..." --json                           # machine-readable output

Computer Control (v0.8 → v0.8.2)

# Setup
xr control status                         # show capabilities + missing deps
xr control test                           # dry-run a self-test plan
xr control start                          # enable in config
xr control stop                           # disable completely

# Single actions
xr control app   "Visual Studio Code"     # launch an app
xr control open  "https://example.com"    # open a URL or path
xr control type  "hello world"            # type into focused window
xr control click "640,480" [--right|--double]
xr control move  "640,480"
xr control scroll <up|down|left|right> [n]
xr control key   "ctrl+c"                 # any combo
xr control focus "Chrome"                 # focus an existing window

# Multi-step (planner)
xr control plan  "open github and search for ahmadrrrtx"    # dry-run default
xr control plan  "..." --step                               # confirm each step
xr control plan  "..." --yes                                # auto-approve sensitive
xr control plan  "..." --no-memory                          # skip cache + don't store
cat plan.json | xr control run                              # run pre-built JSON plan

# Browser (Playwright, opt-in)
xr control browser status
xr control browser install
xr control browser close

# Memory (v0.8.2)
xr control memory list
xr control memory show <baseline-id | task>
xr control memory forget <baseline-id | task>
xr control memory clear

# Disable everything
xr control stop
XR_CONTROL_DISABLED=1 xr control ...      # env override (always wins)

Vision-loop computer use

xr --computer "open browser, search for X, summarize the top result"

Providers & local models

xr providers                              # list with key/no-key status
xr providers add groq                     # interactive add (secure prompt)
xr providers set ollama qwen2.5:7b        # set default

xr models                                 # local model status
xr models recommend                       # auto-detect hardware → suggest model
xr models install [id]                    # download & configure Ollama model
xr models test [id]                       # smoke test

Budget

xr budget                                 # status (cap, spend, remaining)
xr budget set 5                           # set monthly cap (USD)
xr budget history                         # spend by model
xr budget reset                           # zero the current period
xr cost                                   # lifetime cost summary

Research (v0.7)

xr research "topic"                       # quick research
xr research deep "topic"                  # multi-source deep dive
xr research plan "topic"                  # generate a research plan
xr research export                        # latest report → markdown

Plugins (1.0)

xr plugins                                # list installed plugins + status
xr plugins inspect ./plugins/hello        # manifest + permissions (no code runs)
xr plugins install ./plugins/hello        # install a local plugin (asks to approve)
xr plugins enable hello                   # enable (separate, conscious step)
xr plugins permissions hello              # what can this plugin access?
xr plugin hello greet rrrtx               # run a command a plugin contributes
xr plugins update hello [path]            # update (rejects NEW permission asks)
xr plugins disable hello                  # disable cleanly
xr plugins remove hello                   # uninstall + delete files
xr plugins doctor                         # per-plugin health

Flags: --yes/-y, --enable, --grant net,secrets, --json. See
docs/PLUGINS.md for the manifest spec, permission model, and
how to write a plugin.

Voice

xr voice                                  # show voice stack status
xr voice test                             # mic → STT → TTS loopback
xr voice start                            # interactive PTT loop
xr voice stop
xr speak "text"
xr listen                                 # capture a single command

Dashboard

xr serve                                  # http://127.0.0.1:7842/dashboard?token=...
xr serve --port 8000 --token mytoken

Skills + RAG (project)

xr skills                                 # list learned skills
xr index                                  # build local RAG index of the project

Durable Memory (v0.9)

xr memory                                 # status + counts by category
xr memory list [--scope s] [--category c] [--json]
xr memory add "<text>" [--category preference|project|workflow|fact|exclusion]
                       [--scope <s>] [--tag <t>] [--importance 1-5]
xr memory edit <id> ["<new text>"] [--category c] [--scope s] [--importance n]
xr memory remove <id>                     # forget one entry (permanent)
xr memory search "<text>"                 # keyword search
xr memory recall "<text>" [--lexical]     # what chat/voice would surface (semantic by default)
xr memory reindex                         # pre-compute embeddings (warms semantic recall)
xr memory summarize [--days N] [--max-importance n] [--dry-run] [-y]  # fold old notes → digests
xr memory export [path]                   # JSON bundle (stdout if no path)
xr memory import <path>                   # merge a bundle (dedupes)
xr memory clear [--scope s] [-y]          # forget everything / one scope
xr memory summaries [clear]               # conversation recaps (separate store)

System

xr doctor                                 # full health check (config, provider,
                                          #  local model, audit chain, voice,
                                          #  computer control, budget, sandbox)
xr verify-log                             # verify tamper-evident audit chain
xr config                                 # show config.json
xr reset                                  # factory reset (deletes config + db)
xr test --attacks                         # run injection benchmark
xr --tui                                  # interactive terminal UI

Flags (any command)

Flag	Meaning
--mode <agent|plan|ask>	execution mode
--provider <id>	override provider
--model <id>	override model
--budget <usd>	hard $ ceiling
--max-tokens <n>	per-task token cap
--max-steps <n>	loop safety rail
--dry-run	simulate everything
--json	machine-readable output
--yes, -y	auto-approve sensitive (NEVER destructive)
--step	confirm every step (control / plan)
--no-memory	skip plan cache (control only)

---

🔐 Security & Safety Model

Computer-Control safety gates (always on)

Action class	Behavior
safe (move, scroll, focus)	runs immediately
sensitive (open, type, click, key, app, browser fill)	prompts unless --yes
destructive (shell-like text, Enter, Shift+Del, file://, executable URLs, submit, sensitive fill)	always prompts — ignores --yes

Approval surfaces (both work simultaneously)

• CLI prompt — appears in the terminal that issued the command
• Dashboard buttons — appears in the 🖥️ panel; whoever answers first wins

Disable switches

• xr control stop — sets config.control.enabled = false
• XR_CONTROL_DISABLED=1 env var — always wins, even over config

Memory safety (v0.8.2)

• Caches only fully successful auto-mode plans
• Refuses plans containing sensitive: true or destructive actions
• Recall re-validates + re-classifies every action — schema drift or risk escalation invalidates the entry
• xr control memory list/show/forget/clear give full user visibility

Secret handling

• Never stored in plaintext when an OS-backed store is available:
  • macOS Keychain (security)
  • Linux Secret Service (secret-tool)
• File fallback at ~/.xr/.env with chmod 600
• Audit log auto-redacts sk-…, Bearer …, and any sensitive: true value

Audit log

• Append-only, SHA-256 hash-chained
• Every entry: control plan, execution, denial, memory store/hit/forget, agent tool call, security event, budget pause
• Verify with xr verify-log

---

🗺️ Architecture

┌──────────────────────────────────────────────────────────┐
│              User (CLI · TUI · Voice · Telegram)         │
└─────────────────────────┬────────────────────────────────┘
                          │
                ┌─────────▼──────────┐
                │  XR Runtime Kernel │  The OS Orchestrator
                └─────────┬──────────┘
                          │
        ┌─────────────────┼─────────────────────┐
        │                 │                     │
┌───────▼─────┐  ┌────────▼───────┐  ┌──────────▼──────────┐
│  DI Container │  │  Event Bus     │  │  Command Registry   │
│  (Services)  │  │  (Async Comms) │  │  (Extensible CLI)   │
└───────┬─────┘  └────────┬───────┘  └──────────┬──────────┘
        │                 │                     │
        └─────────┬───────┴─────────────────────┘
                  │
    ┌─────────────▼────────────────────────────────────┐
    │               Services Layer                     │
    │  (Agent · Budget · Provider · Plugin · Config)   │
    └─────────────┬────────────────────────────────────┘
                  │
    ┌─────────────▼────────────────────────────────────┐
    │              Storage Layer (Specialized)         │
    │ (Session · Audit · Memory · Cost · Skill Store)  │
    └─────────────┬────────────────────────────────────┘
                  │
          ┌───────▼──────┐
          │  SQLite (WAL) │
          │  + hash chain │
          └──────────────┘

Repo layout

src/
  ├── core/             # 🧠 The Kernel: Runtime, DI Container, Lifecycle, Event Bus
  ├── services/         # 🛠️ Managed Services: Agent, Provider, Budget, Plugin, Config
  ├── commands/         # ⌨️ Decoupled CLI Commands: run, doctor, config, budget
  ├── state/            # 💾 Storage Layer
  │     ├── store.ts        # Base store abstraction
  │     └── stores/         # Specialized Stores: Audit, Session, Cost, Memory, etc.
  ├── providers/        # 🔌 12+ BYOK adapters (OpenAI-compat + native)
  ├── local/            # 💻 Ollama hardware detection + recommendation
  ├── cost/             # 💰 Spend cap, governor, pricing, manager
  ├── security/         # 🛡️ Injection attack corpus, guards, secrets
  ├── reliability/      # 🛠️ JSON repair, model profiles, GBNF grammar
  ├── skills/           # 🎓 Non-regressive skill engine
  ├── memory/           # 🧠 Durable memory (v0.9) + RAG + project fingerprint
  │     ├── types.ts        # categories, sources, MemoryEntry vocabulary
  │     ├── store.ts        # ✨ v0.9 write rules · recall · import/export
  │     ├── intent.ts       # NL "remember/forget/what do you know" parser
  │     ├── inject.ts       # recalled memory → one labelled prompt block
  │     ├── cli.ts          # ✨ v0.9 `xr memory …` handlers
  │     ├── rag.ts          # local RAG index + codebase fingerprint
  │     ├── embed.ts        # Ollama embeddings + lexical fallback
  │     └── compact.ts      # context compaction (spend cap)
  ├── computer/         # 👁️ Vision-loop computer use (xr --computer)
  ├── control/          # 🕹️ ✨ v0.8 safe control layer (xr control)
  │     ├── types.ts        # Action schema (Zod)
  │     ├── classify.ts     # risk classifier (pure)
  │     ├── adapter.ts      # OS + dep detection
  │     ├── executor.ts     # the ONLY file that touches the OS
  │     ├── service.ts      # classify → approve → execute pipeline
  │     ├── audit.ts        # redacting audit wrapper
  │     ├── approvals.ts    # CLI ↔ dashboard race queue
  │     ├── planner.ts      # NL → Action[] (memory-first)
  │     ├── browser.ts      # lazy Playwright backend
  │     ├── memory.ts       # ✨ v0.8.2 plan memory
  │     └── cli.ts          # xr control … subcommands
  ├── tools/            # 🛠️ Agent tools (files, web, system, control)
  ├── voice/            # 🎙️ STT/TTS/wake word, voice→control router
  ├── research/         # 🔬 v0.7 research mode
  ├── daemon/           # 🖥️ xr serve (127.0.0.1 dashboard)
  ├── interfaces/       # 🎨 CLI helpers, onboarding, TUI
  └── index.ts          # 🚀 Thin bootstrap loader for the Runtime
test/                   # 🧪 165+ tests, all platforms

---

🧪 Tests

bun test                              # full suite
bun test test/control.test.ts         # v0.8 safety pipeline
bun test test/control-plan.test.ts    # v0.8.1 planner + browser + approvals
bun test test/control-memory.test.ts  # v0.8.2 plan-memory layer
bun test test/memory-v09.test.ts      # v0.9 durable memory (store, intent, recall)

---

🌐 Platform Notes

OS	Built-in deps	Recommended install for full computer control
macOS	osascript, open	brew install cliclick (for mouse move/click)
Linux (X11)	—	sudo apt install xdotool wmctrl xdg-utils
Linux (Wayland)	—	synthetic input blocked by Wayland — XR refuses gracefully
Windows	PowerShell (built-in)	—

For browser automation on any platform:

xr control browser install   # ~150 MB chromium

---

📦 Configuration

Config lives at ~/.xr/config.json (auto-created on first run). Schema is versioned and self-healing — invalid keys never crash XR.

{
  "version": 8,
  "defaults": { "mode": "agent", "provider": "ollama", "model": "qwen2.5:7b" },
  "budget": { "perTaskUsd": 0.25, "perTaskTokens": 250000 },
  "security": {
    "egressAllowlist": ["searx.be", "api.github.com", "registry.npmjs.org"],
    "requireApproval": ["write_file", "delete", "shell", "send"]
  },
  "localModels": { "runtime": "ollama", "enabled": true, "routing": "hybrid" },
  "memory": {                    // durable memory (v0.9)
    "enabled": true,            // master switch (or env XR_MEMORY_DISABLED=1)
    "autoSuggest": true,        // offer to remember "remember …" phrases (asks first)
    "injectInChat": true,       // surface relevant memory into chat/research prompts
    "recallLimit": 5,           // max entries surfaced into any single prompt
    "semanticRecall": true      // embeddings-based recall (auto lexical fallback)
  },
  "control": {
    "enabled": false,            // opt-in via `xr control start`
    "defaultMode": "auto",
    "stepDelayMs": 250,
    "memory": {
      "enabled": true,           // plan cache (v0.8.2) — NOT durable memory
      "maxEntries": 500
    }
  },
  "plugins": {
    "enabled": true,
    "requireTrust": true,
    "deniedPermissions": []
  }
}

Env overrides

Variable	Effect
XR_HOME	override config dir (default ~/.xr)
XR_CONTROL_DISABLED=1	hard-disable computer control
XR_BROWSER_HEADLESS=1	run Playwright headless
XR_STT_URL / XR_TTS_URL	voice endpoints
XR_SEARXNG	research search backend
XR_WAKE_WORD=true	enable wake-word listening
GROQ_API_KEY, OPENAI_API_KEY, …	BYOK provider keys

---

🔧 Quick Recipes

Use Groq for free, fast inference:

xr providers add groq          # paste key (stored in OS keychain if available)
xr providers set groq llama-3.3-70b-versatile

Fully offline (local model only):

xr models install qwen2.5:7b
xr providers set ollama qwen2.5:7b

Automate a repeatable web workflow with zero ongoing cost:

xr control start
xr control browser install
xr control plan "log into example.com and download the latest report" --yes
# First run uses LLM. Every subsequent run: ⚡ recalled from memory.

Watch live what XR is doing across all surfaces:

# Terminal 1
xr serve                                      # dashboard at 127.0.0.1:7842

# Terminal 2
xr "build me a CRUD app and run the tests"   # see every step in the dashboard

# Optionally answer approvals from the dashboard instead of the terminal.

---

🔐 Security & Safety Model

Computer-Control safety gates (always on)

Action class	Behavior
safe (move, scroll, focus)	runs immediately
sensitive (open, type, click, key, app, browser fill)	prompts unless --yes
destructive (shell-like text, Enter, Shift+Del, file://, executable URLs, submit, sensitive fill)	always prompts — ignores --yes

Approval surfaces (both work simultaneously)

• CLI prompt — appears in the terminal that issued the command
• Dashboard buttons — appears in the 🖥️ panel; whoever answers first wins

Disable switches

• xr control stop — sets config.control.enabled = false
• XR_CONTROL_DISABLED=1 env var — always wins, even over config

Memory safety (v0.8.2)

• Caches only fully successful auto-mode plans
• Refuses plans containing sensitive: true or destructive actions
• Recall re-validates + re-classifies every action — schema drift or risk escalation invalidates the entry
• xr control memory list/show/forget/clear give full user visibility

Secret handling

• Never stored in plaintext when an OS-backed store is available:
  • macOS Keychain (security)
  • Linux Secret Service (secret-tool)
• File fallback at ~/.xr/.env with chmod 600
• Audit log auto-redacts sk-…, Bearer …, and any sensitive: true value

Audit log

• Append-only, SHA-256 hash-chained
• Every entry: control plan, execution, denial, memory store/hit/forget, agent tool call, security event, budget pause
• Verify with xr verify-log

---

🤝 Contributing

git clone https://github.com/ahmadrrrtx/xr
cd xr && bun install
bun test                  # all tests must pass
bun run typecheck         # 0 errors required

Open issues + PRs welcome. Big things to help with:

• Wayland support for xr control
• More browser-action verbs (download, upload, screenshot regions)
• Provider adapters for new model APIs
• Translations of the onboarding wizard

---

📜 License

MIT © Muhammad Ahmad (@ahmadrrrtx)

---

XR — the AI agent you can actually trust.
_{by rrrtx · BYOK · local-first · spend-capped · tamper-evident}