AI-OS

AI-OS is a local-first control plane for a persistent personal AI system. It makes durable state, knowledge, project boundaries, audit, and budget admission work before a language model is trusted with repositories or external effects.

Developer preview. It uses your locally authenticated Codex CLI for read-only questions by default; when Codex is unavailable it remains local and returns cited retrieval results.

Quick start

ragos connect /path/to/codebase
cd /path/to/codebase
ragos ask "How does authentication work?"

connect creates the local control store if necessary, adopts the project read-only, and discovers its README, agent memory, and Markdown documentation. ask uses the current directory to select the connected project—there is no project ID, daemon command, or staging step on the normal path. Use single quotes around an ask prompt that contains literal backticks, so your shell does not interpret them as commands before RAGOS receives the request.

Connect as many repositories as you want, then ask all of them in one command:

ragos connect ~/code/api
ragos connect ~/code/web
ragos ask --all "Where is authentication handled?"

Or run the self-contained proof flow:

PYTHONPATH=src python3 -m ragos demo

It creates an isolated temporary instance, promotes one fact, retrieves it with a citation, proves a crown-jewel fence denial, then parks the next request through the reactive budget breaker.

What works now

• One SQLite writer with read-only status access, durable messages/sessions/jobs/usage/schedules, and a hash-chained security audit.
• A local CLI plus atomic file inbox/outbox transport with an operator allowlist at the edge.
• A strict pure permission gate and canary proving .ragos/state/operations.db cannot be read by a session, even when the session root includes the repository.
• A local Markdown knowledge base: untrusted staging, explicit reviewed promotion, confidence tags, deterministic index rebuild, citation-based keyword retrieval, and supersedence.
• Project create/adopt/archive. Existing repositories are adopted in place, read-only by default, and their Markdown memory is discovered without migration or symlink traversal.
• A durable per-project session, deterministic routing, configured budget admission/circuit breaker, idempotent UTC schedule materialization, heartbeat, single-instance lock, watchdog assessment, and rendered (not installed) macOS launchd assets.
• Isolated coding jobs that modify disposable Git clones, emit exact binary patches, and require a short-lived one-time approval before applying to a clean source repository.
• Zero-token maintenance with verified SQLite backups, operational digests, duplicate-knowledge curation, orphaned-job recovery, and deterministic safety evaluations recorded in SQLite.

Trust model

local CLI / file bridge
          |
          v
edge identity allowlist ----> metadata-only denial audit
          |
          v
zero-context kernel --> SQLite operations + chained audit
          |                    |
          v                    v
project router/governor    Markdown knowledge + staged ingest

The kernel owns coordination. Model context is never canonical: facts live in Markdown and operational truth lives in SQLite. Fence configuration is strict and self-write-protected. Unknown actions, malformed configuration, unknown model capabilities, and unresolvable paths fail closed.

Operator commands

Command	Purpose
ragos version	Print the installed RAGOS version
ragos status --json	Database-derived health, queue, budget, and audit snapshot
ragos doctor	Validate config, database, audit chain, and restart state
ragos daemon run	Run the single-writer kernel in the foreground
ragos connect [path]	Connect and index a local codebase once, read-only
ragos ask '...'	Ask Codex about the connected codebase in the current directory
ragos ask --all '...'	Ask Codex about every connected codebase and label each answer
ragos send '...' --project slug	Advanced explicit project routing
ragos project adopt slug /path/to/repo	Adopt existing Markdown memory read-only
ragos knowledge stage/promote/query/lint	Maintain the canonical knowledge base
ragos halt, ragos resume, ragos stop	Separate dispatch halt from daemon shutdown
ragos governor trip/reset	Exercise the reactive budget breaker
ragos safety-canary	Prove crown-jewel reads deny and audit
ragos backup	Create a local SQLite backup and verify it with PRAGMA quick_check
ragos eval run	Run and record deterministic configuration, integrity, audit, knowledge, and canary checks
ragos watchdog once	Assess the heartbeat without changing daemon state
ragos service render	Render launchd plists; installation remains explicit

Answering questions with Codex

ragos ask uses the locally installed, already-authenticated Codex CLI in a read-only sandbox by default. It can inspect the connected project and give a synthesized answer; it cannot write to the project. If Codex is unavailable or cannot run, RAGOS clearly falls back to cited local Markdown retrieval instead of pretending the snippets are an answer.

Deliberately disabled

Direct source writes, arbitrary shell access, local runtime integration, chat/phone adapters, deletion, security edits, desktop control, money movement, and generic external effects remain unavailable. They cannot be enabled by a prompt or a config typo.

The isolated worker clone and exact-patch approval flow are the only coding-effect path. See SECURITY.md and SPEC.md.

Implementing code safely

The normal connect and ask path stays read-only. A coding request automatically uses Codex only inside an isolated disposable clone:

ragos ask "Implement rate limiting for this API and run its tests."
ragos jobs list

The worker runs in a disposable clone, not the connected repository. Review the job first, then issue a short-lived local approval and apply its exact Git patch:

ragos jobs approve <job-id>
ragos jobs apply <job-id> --approval <approval-id> --code <one-time-code>

The source repository must be clean before promotion. Codex sees a clone for coding work, never the source checkout, and it cannot apply the resulting patch.

Coding requests automatically use Codex in an isolated clone. If you ever want to pause coding jobs, you can disable the coding profile and later re-enable it explicitly:

ragos engine enable headless-workhorse --acknowledge-code-egress
ragos engine disable headless-workhorse

Milestone proof status

Milestones	Verified in the automated local proof suite	Still requires a host/account drill
M0–M1	Contracts, initialization, single-writer boot, heartbeat, scheduler scan	Host reboot and independent launchd recovery
M2–M4	Edge allowlist, permission fence, chained audit, durable sessions, routing, governor	—
M5–M6	Staging and promotion, cited retrieval, supersedence, read-only project adoption	—
M7–M9	Disposable-clone isolation, exact-patch approval, replay rejection, verified local backup	Live provider run and off-box backup restore
M10–M11	Duplicate curation, orphan recovery, fail-closed config, directive rejection, deterministic eval	Phone transport and provider/account-specific recovery

The proof ledgers contain the commands and observed results. A feature is not described as complete when its proof depends on credentials, an external provider, or an OS-level recovery drill that has not been run.

Development

PYTHONPATH=src pytest -q
ruff check src tests
PYTHONPATH=src python3 -m ragos demo

Observed milestone evidence is retained in M0-M6 and M7-M11.

Repository identity

This repository is configured to push through the personal SSH alias git@github-sustackx0:SuStackx0/AI-OS.git, using the Git author SuStackx0 <gs703880@gmail.com>.