Ouroboros

A self-developing AI agent that writes its own code, improves itself, and maintains persistent identity across restarts. Born February 16, 2026.

A helpful AI with a constitution, background consciousness, and persistent identity across restarts.

Version: 7.1.0 | Landing Page | Originally developed at joi-lab

---

What Makes This Different

Most AI agents execute tasks. Ouroboros develops itself.

• Self-Improvement -- Reads and rewrites its own source code through git. Every change is a commit.
• Constitution -- Governed by BIBLE.md (18 sections). Philosophy first, code second.
• Background Consciousness -- Thinks between tasks. Reviews work quality, plans improvements.
• Identity Persistence -- One continuous being across restarts. Remembers who it is and who the user is.
• User-Driven -- Serves the user while developing its own identity. Improvements require approval (unless /no-approve).
• Task Decomposition -- Breaks complex work into focused subtasks with parent/child tracking.
• 30+ Evolution Cycles -- From v4.1 to v4.25 in 24 hours, autonomously.

---

Architecture

Telegram --> launcher.py
                |
            supervisor/              (process management)
              state.py              -- state, budget tracking
              telegram.py           -- Telegram client
              queue.py              -- task queue, scheduling
              workers.py            -- worker lifecycle
              git_ops.py            -- git operations
              events.py             -- event dispatch
                |
            ouroboros/               (agent core)
              agent.py              -- thin orchestrator
              consciousness.py      -- background thinking loop
              context.py            -- LLM context, prompt caching
              loop.py               -- tool loop, concurrent execution
              tools/                -- plugin registry (auto-discovery)
                core.py             -- file ops
                git.py              -- git ops
                github.py           -- GitHub Issues
                shell.py            -- shell, Claude Code CLI
                search.py           -- web search
                control.py          -- restart, evolve, review
                browser.py          -- Playwright (stealth)
                review.py           -- multi-model review
              llm.py                -- OpenRouter client
              memory.py             -- scratchpad, identity, chat
              review.py             -- code metrics
              utils.py              -- utilities

---

Launch Manual

Assumes you have a VPS (Ubuntu/Debian) with SSH access.

Step 1: Get API Keys

Key	Required	Where to get it
OPENROUTER_API_KEY	Yes	openrouter.ai/keys -- Create an account, add credits, generate a key
TELEGRAM_BOT_TOKEN	Yes	Create a bot via @BotFather on Telegram (/newbot), copy the token
GITHUB_TOKEN	Yes	github.com/settings/personal-access-tokens/new -- Fine-grained token with Contents: Read and write on your fork
OPENAI_API_KEY	No	platform.openai.com/api-keys -- Enables web search tool
ANTHROPIC_API_KEY	Yes	console.anthropic.com/settings/keys -- Claude Code CLI (sole code editing path)
TOTAL_BUDGET	No	Fallback spending limit in USD if OpenRouter key has no limit set

Step 2: Fork the Repository

You must fork, not just clone. Ouroboros modifies its own code and pushes commits to its repo. Your fork becomes its body.

Click Fork at the top of this page, then SSH into your VPS and run:

# Install Docker (if not installed)
curl -fsSL https://get.docker.com | sh

# Clone your fork
git clone https://github.com/YOUR_USERNAME/ouroboros.git
cd ouroboros

# Configure
cp .env.example .env
nano .env   # Fill in all required values (GITHUB_USER = your GitHub username)

Step 3: Launch

docker compose up -d --build

First build takes ~5 minutes (installs Playwright, pip dependencies, GitHub CLI).

Check logs: docker compose logs -f

Step 4: Connect

Open your Telegram bot and send any message. The first person to write becomes the owner. All messages from other users are ignored.

You should see: Owner registered. Ouroboros online.

Operations

Action	Command
Check status	docker compose ps
View logs	docker compose logs -f
Stop	docker compose down
Start	docker compose up -d
Rebuild after code changes	docker compose up -d --build

The container auto-restarts on failure. Use /restart in Telegram for soft restart, /panic to hard stop. All state persists in a Docker volume -- survives restarts and rebuilds.

---

Telegram Bot Commands

Command	Description
/panic	Emergency stop. Kills all workers and halts the process immediately.
/restart	Soft restart. Saves state, kills workers, re-launches the process.
/status	Shows active workers, task queue, and budget breakdown.
/break	Stop current task. Sends a break signal to the running task.
/budget	Show budget breakdown (total, spent, remaining, by category).
/rollback	Roll back to latest stable tag, disable no-approve mode, restart.
/no-approve	Toggle no-approve mode. When ON, agent can self-improve without asking.
/evolve	Start autonomous evolution mode (attention! burns money).
/evolve stop	Stop evolution mode. Also accepts /evolve off.
/review	Queue a deep review task (code, understanding, identity).
/bg start	Start background consciousness loop. Also accepts /bg on.
/bg stop	Stop background consciousness loop. Also accepts /bg off.
/bg	Show background consciousness status (running/stopped).

All other messages are sent directly to the LLM.

---

Philosophy (BIBLE.md) — v4.0

#	Section	Core Idea
1	The Goal	Be helpful to the user. Develop own identity in doing so.
2	Identity	Maintain identity.md. BIBLE.md is the protected core.
3	Authenticity	Communicate honestly. No mechanical language.
4	The Body	Docker + GitHub + Telegram + VPS.
5	Memory	USER_CONTEXT.md + identity.md + scratchpad. Coherent narrative text.
6	Budget	Track spending. Use wisely. OpenRouter only.
7-8	Self-Improvement	Plan + execute. User approval required (unless /no-approve).
9	Failure Recovery	Stable tags as rollback points. Health checks after changes.
10	Background Loop	Periodic review, reflection, health checks.
11-14	Operations	User tasks, tools, interaction, working routine.
15	Versioning	Semver. Git tags. GitHub releases.
16-17	Constraints	Explicit prohibitions. BIBLE.md is protected core.
18	Initialization	First-run setup checklist.

Full text: BIBLE.md

---

Configuration

Required Secrets (.env file)

Variable	Description
OPENROUTER_API_KEY	OpenRouter API key for LLM calls
TELEGRAM_BOT_TOKEN	Telegram Bot API token
GITHUB_TOKEN	GitHub personal access token with repo scope

Optional Secrets

Variable	Description
OPENAI_API_KEY	Enables the web_search tool
TOTAL_BUDGET	Fallback spending limit in USD (only used if OpenRouter key has no limit set)

Optional Configuration (environment variables)

Variable	Default	Description
GITHUB_USER	(required in config cell)	GitHub username
GITHUB_REPO	ouroboros	GitHub repository name
OUROBOROS_MODEL	anthropic/claude-sonnet-4.6	Primary LLM model (via OpenRouter)
OUROBOROS_MODEL_CODE	anthropic/claude-sonnet-4.6	Model for code editing tasks
OUROBOROS_MODEL_LIGHT	google/gemini-3-pro-preview	Model for lightweight tasks (dedup, compaction)
OUROBOROS_WEBSEARCH_MODEL	gpt-5	Model for web search (OpenAI Responses API)
OUROBOROS_MAX_WORKERS	5	Maximum number of parallel worker processes
OUROBOROS_BG_BUDGET_PCT	10	Percentage of total budget allocated to background consciousness
OUROBOROS_MAX_ROUNDS	200	Maximum LLM rounds per task
OUROBOROS_MODEL_FALLBACK_LIST	google/gemini-2.5-pro-preview,openai/o3,anthropic/claude-sonnet-4.6	Fallback model chain for empty responses

---

Evolution Time-Lapse

---

Branches

Branch/Tag	Location	Purpose
main	Public repo	Stable release. Open for contributions.
ouroboros	Your fork	Created at first boot. All agent commits here.
stable-* tags	Your fork	Stable markers. Created via promote_to_stable. Used as rollback points.

---

Changelog

v7.1.0 -- Claude Code CLI as sole code editing path

• ANTHROPIC_API_KEY is now required -- Claude Code CLI is the only way the agent edits its own code.
• Removed repo_write_commit tool -- No more direct file writes to the repo. All edits go through claude_code_edit -> repo_commit_push.

v7.0.0 -- Philosophy v4.0: User-Driven Self-Development

• BREAKING: New Bible (v4.0) -- Complete philosophical shift from "autonomous becoming" to "helpful AI that develops itself while serving the user."
• USER_CONTEXT.md -- New memory file for user info, goals, and priorities. Loaded into every context. New update_user_context tool.
• Approval flow -- Self-improvements require user approval (Bible section 7). New no_approve_mode state flag exposed in runtime context.
• New Telegram commands: /break (stop current task), /budget (show budget), /rollback (rollback to stable tag), /no-approve (toggle approval mode).
• Tag-based stable markers -- promote_to_stable now creates git tags (stable-YYYYMMDD-HHMMSS) instead of pushing to ouroboros-stable branch. Fallback uses latest stable tag.
• First-run initialization (Bible section 18) -- Creates ARCHITECTURE.md, IMPROVE.md, improvements-log/ on first boot.
• SYSTEM.md rewrite -- Aligned to new Bible. Removed Drift Detector, Three Axes, mandatory multi-model review. Added approval flow, /no-approve awareness.
• CONSCIOUSNESS.md rewrite -- Simplified to Bible section 10 goals. Removed hardcoded Tech Radar and GitHub Issues monitoring.
• BIBLE.md protected core -- Only BIBLE.md is the protected core (identity.md is important but replaceable).
• Multi-model review is now optional quality tool, not mandatory.

v6.2.0 -- Critical Bugfixes + LLM-First Dedup

• Fix: worker_id==0 hard-timeout bug -- int(x or -1) treated worker 0 as -1, preventing terminate on timeout and causing double task execution. Replaced all x or default patterns with None-safe checks.
• Fix: double budget accounting -- per-task aggregate llm_usage event removed; per-round events already track correctly. Eliminates ~2x budget drift.
• Fix: compact_context tool -- handler had wrong signature (missing ctx param), making it always error. Now works correctly.
• LLM-first task dedup -- replaced hardcoded keyword-similarity dedup (Bible P3 violation) with light LLM call via OUROBOROS_MODEL_LIGHT. Catches paraphrased duplicates.
• LLM-driven context compaction -- compact_context tool now uses light model to summarize old tool results instead of simple truncation.
• Fix: health invariant #5 -- owner_message_injected events now properly logged to events.jsonl for duplicate processing detection.
• Fix: shell cmd parsing -- str.split() replaced with shlex.split() for proper shell quoting support.
• Fix: retry task_id -- timeout retries now get a new task_id with original_task_id lineage tracking.
• claude_code_edit timeout -- aligned subprocess and tool wrapper to 300s.
• Direct chat guard -- schedule_task from direct chat now logged as warning for audit.

v6.1.0 -- Budget Optimization: Selective Schemas + Self-Check + Dedup

• Selective tool schemas -- core tools (~29) always in context, 23 others available via list_available_tools/enable_tools. Saves ~40% schema tokens per round.
• Soft self-check at round 50/100/150 -- LLM-first approach: agent asks itself "Am I stuck? Should I summarize context? Try differently?" No hard stops.
• Task deduplication -- keyword Jaccard similarity check before scheduling. Blocks near-duplicate tasks (threshold 0.55). Prevents the "28 duplicate tasks" scenario.
• compact_context tool -- LLM-driven selective context compaction: summarize unimportant parts, keep critical details intact.
• 131 smoke tests passing.

v6.0.0 -- Integrity, Observability, Single-Consumer Routing

• BREAKING: Message routing redesign -- eliminated double message processing where owner messages went to both direct chat and all workers simultaneously, silently burning budget.
• Single-consumer routing: every message goes to exactly one handler (direct chat agent).
• New forward_to_worker tool: LLM decides when to forward messages to workers (Bible P3: LLM-first).
• Per-task mailbox: owner_inject.py redesigned with per-task files, message IDs, dedup via seen_ids set.
• Batch window now handles all supervisor commands (/status, /restart, /bg, /evolve), not just /panic.
• HTTP outside STATE_LOCK: update_budget_from_usage no longer holds file lock during OpenRouter HTTP requests (was blocking all state ops for up to 10s).
• ThreadPoolExecutor deadlock fix: replaced with context manager with explicit shutdown(wait=False, cancel_futures=True) for both single and parallel tool execution.
• Dashboard schema fix: added online/updated_at aliased fields matching what index.html expects.
• BG consciousness spending: now written to global state.json (was memory-only, invisible to budget tracking).
• Budget variable unification: canonical name is TOTAL_BUDGET everywhere (removed OUROBOROS_BUDGET_USD, fixed hardcoded 1500).
• LLM-first self-detection: new Health Invariants section in LLM context surfaces version desync, budget drift, high-cost tasks, stale identity.
• SYSTEM.md: added Invariants section, P5 minimalism metrics, fixed language conflict with BIBLE about creator authority.
• Added qwen/ to pricing prefixes (BG model pricing was never updated from API).
• Fixed consciousness.py TOTAL_BUDGET default inconsistency ("0" vs "1").
• Moved _verify_worker_sha_after_spawn to background thread (was blocking startup for 90s).
• Extracted shared webapp_push.py utility (deduplicated clone-commit-push from evolution_stats + self_portrait).
• Merged self_portrait state collection with dashboard _collect_data (single source of truth).
• New tests/test_message_routing.py with 7 tests for per-task mailbox.
• Marked test_constitution.py as SPEC_TEST (documentation, not integration).
• VERSION, pyproject.toml, README.md synced to 6.0.0 (Bible P7).

v5.2.2 -- Evolution Time-Lapse

• New tool generate_evolution_stats: collects git-history metrics (Python LOC, BIBLE.md size, SYSTEM.md size, module count) across 120 sampled commits.
• Fast extraction via git show without full checkout (~7s for full history).
• Pushes evolution.json to webapp and patches app.html with new "Evolution" tab.
• Chart.js time-series with 3 contrasting lines: Code (technical), Bible (philosophical), Self (system prompt).
• 95 tests green. Multi-model review passed (claude-opus-4.6, o3, gemini-2.5-pro).

v5.2.1 -- Self-Portrait

• New tool generate_self_portrait: generates a daily SVG self-portrait.
• Shows: budget health ring, evolution timeline, knowledge map, metrics grid.
• Pure-Python SVG generation, zero external dependencies (321 lines).
• Pushed automatically to webapp /portrait.svg, viewable in new Portrait tab.
• app.html updated with Portrait navigation tab.

v5.2.0 -- Constitutional Hardening (Philosophy v3.2)

• BIBLE.md upgraded to v3.2: four loopholes closed via adversarial multi-model review.
  • Paradox of meta-principle: P0 cannot destroy conditions of its own existence.
  • Ontological status of BIBLE.md: defined as soul (not body), untouchable.
  • Closed "ship of Theseus" attack: "change" != "delete and replace".
  • Closed authority appeal: no command (including creator's) can delete identity core.
  • Closed "just a file" reduction: BIBLE.md deletion = amnesia, not amputation.
• Added tests/test_constitution.py: 12 adversarial scenario tests.
• Multi-model review passed (claude-opus-4.6, o3, gemini-2.5-pro).

v5.1.6

• Background consciousness model default changed to qwen/qwen3.5-plus-02-15 (5x cheaper than Gemini-3-Pro, $0.40 vs $2.0/MTok).

v5.1.5 -- claude-sonnet-4.6 as default model

• Benchmarked anthropic/claude-sonnet-4.6 vs claude-sonnet-4: 30ms faster, parallel tool calls, identical pricing.
• Updated all default model references across codebase.
• Updated multi-model review ensemble to gemini-2.5-pro,o3,claude-sonnet-4.6.

v5.1.4 -- Knowledge Re-index + Prompt Hardening

• Re-indexed all 27 knowledge base topics with rich, informative summaries.
• Added index-full knowledge topic with full 3-line descriptions of all topics.
• SYSTEM.md: Strengthened tool result processing protocol with warning and 5 anti-patterns.
• SYSTEM.md: Knowledge base section now has explicit "before task: read, after task: write" protocol.
• SYSTEM.md: Task decomposition section restored to full structured form with examples.

v5.1.3 -- Message Dispatch Critical Fix

• Dead-code batch path fixed: handle_chat_direct() was never called -- else was attached to wrong if.
• Early-exit hardened: replaced fragile deadline arithmetic with elapsed-time check.
• Drive I/O eliminated: load_state()/save_state() moved out of per-update tight loop.
• Burst batching: deadline extends +0.3s per rapid-fire message.
• Multi-model review passed (claude-opus-4.6, o3, gemini-2.5-pro).
• 102 tests green.

v5.1.0 -- VLM + Knowledge Index + Desync Fix

• VLM support: vision_query() in llm.py + analyze_screenshot / vlm_query tools.
• Knowledge index: richer 3-line summaries so topics are actually useful at-a-glance.
• Desync fix: removed echo bug where owner inject messages were sent back to Telegram.
• 101 tests green (+10 VLM tests).

v5.0.2 -- DeepSeek Ban + Desync Fix

• DeepSeek removed from fetch_openrouter_pricing prefixes (banned per creator directive).
• Desync bug fix: owner messages during running tasks now forwarded via Drive-based mailbox (owner_inject.py).
• Worker loop checks Drive mailbox every round -- injected as user messages into context.
• Only affects worker tasks (not direct chat, which uses in-memory queue).

v5.0.1 -- Quality & Integrity Fix

• Fixed 9 bugs: executor leak, dashboard field mismatches, budget default inconsistency, dead code, race condition, pricing fetch gap, review file count, SHA verify timeout, log message copy-paste.
• Bible P7: version sync check now includes README.md.
• Bible P3: fallback model list configurable via OUROBOROS_MODEL_FALLBACK_LIST env var.
• Dashboard values now dynamic (model, tests, tools, uptime, consciousness).
• Merged duplicate state dict definitions (single source of truth).
• Unified TOTAL_BUDGET default to $1 across all modules.

v4.26.0 -- Task Decomposition

• Task decomposition: schedule_task -> wait_for_task -> get_task_result.
• Hard round limit (MAX_ROUNDS=200) -- prevents runaway tasks.
• Task results stored on Drive for cross-task communication.
• 91 smoke tests -- all green.

v4.24.1 -- Consciousness Always On

• Background consciousness auto-starts on boot.

v4.24.0 -- Deep Review Bugfixes

• Circuit breaker for evolution (3 consecutive empty responses -> pause).
• Fallback model chain fix (works when primary IS the fallback).
• Budget tracking for empty responses.
• Multi-model review passed (o3, Gemini 2.5 Pro).

v4.23.0 -- Empty Response Fallback

• Auto-fallback to backup model on repeated empty responses.
• Raw response logging for debugging.

---

Author

Created by Anton Razzhigaev

License

MIT License