The Problem

Developers who want an autonomous coding assistant that can modify its own source, persist identity, and manage a budget of LLM usage have no open‑source reference implementation that ties together git‑based self‑modification, multi‑model review, and Telegram/Colab front‑ends. Maintaining such a system manually is error‑prone and hard to audit.

What This Does

The repository implements a self‑modifying AI agent (“Ouroboros”) that reads, edits, and commits its own Python files. Core orchestration lives in ouroboros/agent.py and ouroboros/loop.py; the tool plug‑in system is under ouroboros/tools/ with a dynamic registry (ouroboros/tools/registry.py). Supervision (state tracking, queueing, Telegram bot, git helpers) is in the supervisor/ package. The web UI is a static docs/index.html, while Colab users start the agent via colab_launcher.py.

How It Is Wired

Execution begins with colab_launcher.py (or the Telegram bot entry in supervisor/telegram.py). The launcher imports supervisor/git_ops.py (function init) which sets up a repository clone and calls ouroboros/agent.py.__init__. The agent creates a Loop (ouroboros/loop.py.__init__) that repeatedly invokes get_tools → ToolEntry (48 calls) and runs each tool in ouroboros/tools/.

Key shared utilities live in ouroboros/utils.py (16 functions, 23 callers). Functions with the widest blast radius are:

  • read_text – called from 40 locations, used for loading prompts, state files, and tool code.
  • append_jsonl – called from 38 locations, writes logs and task snapshots.
  • utc_now_iso – called from 35 locations, timestamps every persisted artifact.

These utilities are invoked by many modules (ouroboros/context.py, supervisor/state.py, ouroboros/memory.py, etc.) and also perform external effects: file I/O (57 functions), shell commands (20 functions), network calls (10 functions), and LLM inference (4 functions).

The import graph shows 41 internal modules with 88 edges; ouroboros/tools/registry.py and ouroboros/tools/__init__.py form a circular dependency, making any change to the registry risky. ouroboros/tools/registry.py is a hub (21 incoming imports), so churn here propagates widely.

External touch points:

  • Git commands (run_cmd) – 5 call sites.
  • OpenRouter LLM client (LLMClient) – 10 call sites.
  • Telegram API – via supervisor/telegram.py.

No CI pipeline or lockfile is present, so the current wiring is only verified by the local test suite (tests/).

How To Use It

# Clone the repo
git clone https://github.com/moses-y/ouroboros
cd ouroboros

# Install dependencies (Python 3.11 recommended)
pip install -r requirements.txt   # or: pip install .  (uses pyproject.toml)

# Set required environment variables (Telegram bot token, OpenRouter key, etc.)
# The README expects TELEGRAM_BOT_TOKEN and OPENROUTER_API_KEY in the environment.

# Launch via Colab helper (or run directly)
python colab_launcher.py

If you prefer the Telegram front‑end, start the supervisor:

python -m supervisor.telegram

Both entry points ultimately instantiate ouroboros.agent.Agent, which creates the Loop and begins tool execution.

Real‑World Use

A DevOps team can run Ouroboros in a dedicated VM, give it a GitHub repository token, and let it continuously refactor internal tooling. The agent reads its own source (ouroboros/utils.py → read_text), proposes a change, runs a multi‑model review (ouroboros/tools/review.py → LLM calls), and pushes the commit via supervisor/git_ops.py. The Telegram bot can be used to approve or reject commits on demand.

Code Health & Issues

Static analysis reports 61 findings (9 high, 52 medium, 0 low). The health audit highlights three actionable items:

  • HIGH – No lockfile (pyproject.toml lacks a poetry.lock/uv.lock).
  • HIGH – No CI workflow (41 source files, no .github/ CI config).
  • MEDIUM – No Dependabot/Renovate (no automated dependency updates).

Additional high‑severity patterns detected:

  • Circular import between ouroboros/tools/registry.py and ouroboros/tools/__init__.py.
  • Deep nesting (up to 6 levels) in registry.py, utils.py, and supervisor/state.py.
  • Broad except: clauses in several core modules, swallowing errors silently.

The repository includes a license, a test suite (tests/), and documentation (docs/), but lacks reproducible builds and automated quality gates.

The Bottom Line

Ouroboros provides a complete, open‑source reference for self‑modifying AI agents, with a clear separation between core agent logic and supervisory services. However, the codebase suffers from maintainability risks (import cycles, deep nesting) and production‑readiness gaps (no lockfile, CI, or automated dependency updates). It is suitable for research or prototype deployments where rapid iteration outweighs the need for strict release hygiene.