TheOz 🧠

AI Dev Engine — AST-aware, RAG-powered, safe code modification with token observability.**

TheOz is a standalone npm package that integrates into any existing repository. It uses chunk-level RAG and AST dependency graphs to understand your codebase, and applies AI modifications safely via precision diffs—never full-file rewrites.

(Placeholder)

Key Features

• Architectural Guardian: Enforces safety with AST validation, Type Diff audits, and AI Critic consensus.
• Zero-API Mode: Fully local RAG with @xenova/transformers. No API keys required.
• AI Orchestrator: Works as a native IDE tool via MCP (Model Context Protocol) or Watchdog mode.
• Token Observability: Real-time cost and token tracking across all runs.
• Rollback Safety: Automatic git snapshots before every change.
• Chunk-Level RAG: Splits your TypeScript codebase into semantic functions and classes for precise knowledge retrieval.
• Dependency Graph: Understands what imports what, automatically analyzing the impact of potential changes.
• Safe Patching: Modifies code via strict diff applying and AST re-parsing. Automatically rolls back on failure or regression.
• AI Critic Validation: A secondary AI reviews all generated changes for regressions or side effects before they touch your disk.
• Cost Controls & Observability: Real-time token usage and cost metrics per file and stage, with hard limit pre-flight guards.
• Safe Mode & Dry Run: Restrict the AI to safe operations or preview its execution plan before anything is modified.

Quickstart (Zero-API & MCP)

TheOz is designed to be your Architectural Guardian without upfront API costs.

# 1. Install & Setup
# This initializes .theoz AND auto-registers the MCP server for Antigravity/Cursor!
npx theoz setup

# 2. Refresh your IDE
# Click 'Refresh' or 'Restart' in your IDE's MCP settings.

# 3. Ask TheOz (via Chat or CLI)
# In Chat: "oz: Add a loading state to the dashboard"
# In CLI: npx theoz ask "Add a loading state"

Commands

• theoz setup: Scans the project, builds the dependency graph, chunks code, and generates embeddings.
• theoz ask "<prompt>": Orchestrates the AI pipeline to analyze, plan, and execute your request.
  • --safe: Restricts edits to max 2 files, enforces critical path rules, and runs the AI critic twice.
  • --force: Skips the interactive execution plan approval.
  • --dry-run: Generates the plan and patches, but exits before applying anything.
• theoz metrics: View token and cost usage aggregated across your project.
• theoz dashboard: Starts a local web server (default port 4242) with real-time UI charts of your metrics.
• theoz replay <id>: View the state and outcome of a previous run.

Configuration

TheOz is configured via theoz.config.ts in your project root:

export default {
  aiMode: "internal", // or "external" for IDE Watchdog
  embeddingProvider: "openai", // or "local" for Zero-API RAG
  model: "gpt-4o",
  embeddingModel: "text-embedding-3-small",
  safeMode: false,
  autoCommit: true,
  maxTokensPerRequest: 5000,
  maxCostPerRun: 0.10, // Hard stop if cost exceeds this
  requirePlanApproval: true
};

You can define rules to protect your codebase in .theoz/rules.json:

{
  "protected": ["src/core/db.ts"],
  "maxFilesToEdit": 5,
  "allowedExtensions": [".ts", ".js", ".tsx", ".jsx"]
}

Architecture

TheOz is built cleanly using modular engines:

1. Analyzer: ts-morph AST parser and function chunker.
2. Context Scope: Graph-impacted boundaries ensuring the AI only changes what it's allowed to.
3. AI Pipeline: Intent classifier -> Planner -> Generator -> Critic.
4. Patch Engine: Unified diff generation and rollback snapshotting.

License

MIT