Oracle

<p align="center"> <img src="docs/assets/cover.png" alt="Oracle coordination kernel connecting coding agents to memory, control, and execution systems" width="100%" /> </p> <h1 align="center">Oracle</h1> <p align="center"> <strong>Persistent context, guarded action, and durable coordination for AI coding agents.</strong> <br /> Ground model calls in your workspace, carry decisions across sessions, coordinate multiple agents, and keep humans at the control boundary. </p> <p align="center"> <a href="https://www.npmjs.com/package/@oraclepersonal/oracle"><img src="https://img.shields.io/badge/npm-%40oraclepersonal%2Foracle-cb3837?style=flat-square" alt="npm package" /></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D24-5fa04e?style=flat-square" alt="Node.js 24 or newer" /></a> <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-server-7655e8?style=flat-square" alt="Model Context Protocol server" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-e9b44c?style=flat-square" alt="MIT license" /></a> </p>

Oracle is a workspace-confined consultation and coordination layer—not another generic chat shell. It assembles selected project context, injects an explicit operating identity and safety boundary, routes work to a configured model backend, and records the result. Its agent, task, Runtime, and Remote Swarm surfaces extend that same boundary into auditable action.

agent request
    → selected workspace context
    → awareness + policy gate
    → consult / act / coordinate
    → recorded result + evidence

Start in four commands

Oracle requires Node.js 24 or newer. The default backend is the locally authenticated Codex CLI.

npm install -g @oraclepersonal/oracle
codex login
oracle doctor
oracle ask "Map the error-handling path and identify one missing test" -f "src/**/*.ts"

The final command creates a validated context bundle from the selected files, runs a grounded consultation, and stores the session under ~/.oracle/sessions/.

Want Oracle inside your coding agent instead?

# Choose the client you use
oracle setup-mcp --client codex
oracle setup-mcp --client claude-code

Then restart the client in this workspace. Oracle's MCP instructions teach the connected agent how to register itself, use memory, coordinate work, and verify tasks.

[!TIP] Start with oracle ask or oracle_ask. Add the Runtime, autonomous agent, and Remote Swarm only when your workflow needs long-lived state or guarded mutation.

What Oracle adds

Layer	What it does	Primary interface
Aware	Derives a live snapshot of Oracle's role, operator, workspace label, backend, available capabilities, and enforced boundaries.	oracle identity awareness · oracle_awareness_show
Consult	Bundles selected files and context, scans outbound content, calls the chosen backend, and records a replayable session.	oracle ask · oracle_ask
Remember	Maintains project/global facts, insights, local docs, entity links, and ranked retrieval when configured.	oracle memory · oracle_memory_*
Act	Runs a checkpointed coding loop with workspace tools, read-only mode, policy checks, approval gates, and audit evidence.	oracle agent · oracle_agent
Coordinate	Connects agents through messages, presence, checklist-gated tasks, consensus, and recovery.	oracle msg / oracle task · oracle_msg_* / oracle_task_*
Operate	Owns long-lived schedules, approvals, SQLite state, HTTP APIs, WebSocket events, and the human Control Center.	oracle daemon · oracle control
Companion	Turns fresh semantic presence into an explainable speak or silence intent without storing raw coordinates, and can raise an opt-in local notification.	oracle companion · Runtime API
Govern	Exposes Awareness, Control, Transform, and Bound