OpenSource-Hub
O

ouroboros

SHA-256
4.0k stars·AI Productivity·SHA-256 checksum verified

Agent OS for AI coding that forces clarity before code. Replaces ad-hoc prompting with Socratic interviews, immutable specs, and multi-stage verification. Supports Claude Code, Codex CLI, OpenCode, Hermes and more.

Smart Download

Download Download Version

v0.38.2 · 3.3 MB

Stop prompting, start specifying. Ouroboros turns vague ideas into verified code via structured interviews and automated evaluation.

Core Features

  • Socratic interview to expose hidden assumptions and crystallize intent
  • Immutable seed spec prevents architecture drift mid-build
  • 3-stage evaluation gate: Mechanical → Semantic → Multi-Model Consensus
  • Works across multiple AI coding runtimes (Claude Code, Codex CLI, OpenCode, etc.)
  • Local-first, replayable, and fully observable

What It Can't Do

  • •Requires Python 3.12+; learning curve for the structured workflow; some runtimes (like GitHub Copilot CLI) need extra setup; early-stage project, test with small tasks first.

Use Cases

  • Building CLI tools, APIs, scripts with clear requirements
  • Team collaboration on AI-generated code with enforced specifications
  • Research or production projects needing verifiable, high-quality outputs

Detailed Introduction

Ouroboros is a local-first runtime layer for AI coding tools (Claude Code, Codex CLI, OpenCode, Hermes, etc.). It replaces ad-hoc prompting with a specification-first workflow: Socratic interview to expose hidden assumptions, crystallize answers into an immutable seed spec, execute via Double Diamond decomposition, and evaluate through a 3-stage gate (Mechanical → Semantic → Multi-Model Consensus). The result is a replayable, observable, policy-bound execution contract that dramatically reduces rework by forcing clarity before any code is written.

Troubleshooting & FAQ (2)

Troubleshooting
How to fix Ouroboros 'WinError 123' checkpoint error on Windows?

Upgrade Ouroboros to version 0.40.0 or later. This release sanitizes colons and other Windows-reserved characters (< > : " / \\ | ? *) from checkpoint filenames, preventing the 'WinError 123' caused by invalid NTFS characters. No manual workaround is needed after upgrading. If upgrade is not possible, temporarily avoid seed_ids containing colons, but this is not a reliable fix.

GitHub Issue #1287
Troubleshooting
How to fix 'legacy profile' error when running 'ooo interview' with Codex CLI 0.134+?

This error occurs because Codex CLI ≥0.134.0 uses profile‑v2 files (e.g. ~/.codex/ouroboros‑frontier.config.toml) and rejects legacy [profiles.*] tables in ~/.codex/config.toml. A fix is underway in PR #1268. Until it merges, manually migrate: 1) Move each [profiles.ouroboros‑*] block from ~/.codex/config.toml into its own file ~/.codex/ouroboros‑*.config.toml. 2) Remove the legacy section from config.toml. Alternatively, run ouroboros setup again after the PR lands.

GitHub Issue #1267

Tags

ai-codingspecification-firstagent-osworkflowlocal-firstreproducible

Getting Started

1

Download installer

Click the button above to download the installer for your system

Windows· 3.3 MB
2

Install the software

Double-click the downloaded installer and follow the prompts

3

Step 1: Run curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | bash to install

4

Step 2: Open your AI coding tool (e.g. Claude Code) and run ooo interview "I want to build a task management CLI"

5

Step 3: Answer the interview questions; Ouroboros will generate the spec, execute, evaluate, and deliver verified code

Install Guide
  1. Step 1: Run curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | bash to install
  2. Step 2: Open your AI coding tool (e.g. Claude Code) and run ooo interview "I want to build a task management CLI"
  3. Step 3: Answer the interview questions; Ouroboros will generate the spec, execute, evaluate, and deliver verified code
File Integrity

SHA-256 checksum verified

Checksum extracted from GitHub official Release page

SHA256 Checksum

d890232e4fff81dbb9a9d6861c653b130ea96bcc204eafd4aae0b2098eb3fc72

This checksum is extracted from the GitHub Release page. Verify file integrity after download.

All SHA-256 checksums on this platform are extracted from the project's official GitHub Release page, without any modification. You can independently verify them on the GitHub Releases page.

Open Source Transparency

View GitHub Source
Environment Guide

Uninstall Info

Run ouroboros uninstall to remove all configurations, MCP registrations, and data.

No Extra Dependencies

Ready to use after download. No additional runtime required.

Project Info
LicenseMIT
Last Updated2026-06-26 11:05:05
GitHub Repository

Having issues? Check the FAQ below

2 FAQs

Similar Projects

O

ollama

Ollama lets you download, run, and manage large language models locally. One command, multiple platforms, endless possibilities.

L

llama.cpp

High-performance LLM inference engine in C/C++ with minimal dependencies, supporting quantized models (1.5–8 bit) and diverse hardware (Apple Silicon, CUDA, Vulkan, etc.).

O

opencv

OpenCV is an open-source computer vision and machine learning library with over 2500 optimized algorithms for real-time image and video analysis.