{"id":34519587,"url":"https://github.com/mlgbjdlw/ouroboros","last_synced_at":"2026-04-08T04:02:14.609Z","repository":{"id":328033066,"uuid":"1114027086","full_name":"MLGBJDLW/ouroboros","owner":"MLGBJDLW","description":"Persistent Copilot context + spec-driven agents — VS Code extension + terminal TUI (CCL) for continuous sessions \u0026 memory.","archived":false,"fork":false,"pushed_at":"2026-02-13T11:05:00.000Z","size":2688,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-13T22:47:12.686Z","etag":null,"topics":["context-management","github-copilot","prompt-engineering","spec-driven-development","vscode-extension"],"latest_commit_sha":null,"homepage":"https://marketplace.visualstudio.com/items?itemName=MLGBJDLW.ouroboros-ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MLGBJDLW.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-10T19:48:29.000Z","updated_at":"2026-02-13T11:05:04.000Z","dependencies_parsed_at":"2025-12-24T05:03:44.782Z","dependency_job_id":null,"html_url":"https://github.com/MLGBJDLW/ouroboros","commit_stats":null,"previous_names":["mlgbjdlw/ouroboros"],"tags_count":64,"template":false,"template_full_name":null,"purl":"pkg:github/MLGBJDLW/ouroboros","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLGBJDLW%2Fouroboros","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLGBJDLW%2Fouroboros/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLGBJDLW%2Fouroboros/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLGBJDLW%2Fouroboros/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MLGBJDLW","download_url":"https://codeload.github.com/MLGBJDLW/ouroboros/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLGBJDLW%2Fouroboros/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31539229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["context-management","github-copilot","prompt-engineering","spec-driven-development","vscode-extension"],"created_at":"2025-12-24T04:36:15.284Z","updated_at":"2026-04-08T04:02:14.603Z","avatar_url":"https://github.com/MLGBJDLW.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ♾️ Project Ouroboros v3.3.25\n\n\u003e **Save Money on GitHub Copilot** — A persistent context system that reduces redundant conversations and maximizes your Copilot subscription value.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Copilot Compatible](https://img.shields.io/badge/GitHub%20Copilot-Compatible-blue)](https://github.com/features/copilot)\n[![GitHub Release](https://img.shields.io/github/v/release/MLGBJDLW/ouroboros?label=Version\u0026color=green)](https://github.com/MLGBJDLW/ouroboros/releases)\n[![VS Code Extension](https://img.shields.io/visual-studio-marketplace/v/MLGBJDLW.ouroboros-ai?label=VS%20Code%20Extension\u0026logo=visual-studio-code)](https://marketplace.visualstudio.com/items?itemName=MLGBJDLW.ouroboros-ai)\n[![CI](https://github.com/MLGBJDLW/ouroboros/actions/workflows/ci.yml/badge.svg)](https://github.com/MLGBJDLW/ouroboros/actions/workflows/ci.yml)\n\n---\n\n## 💰 Why Ouroboros?\n\nGitHub Copilot charges by **request count**. Every time you re-explain your project, tech stack, or rehash previous conversations, you're **wasting requests**.\n\nOuroboros solves this:\n\n| Problem | Ouroboros Solution |\n|---------|-------------------|\n| Re-introducing project every session | 🧠 **Persistent Memory** — AI reads `history/context-*.md` automatically |\n| AI forgets after each response | ♾️ **Never Say Goodbye** — AI doesn't end conversations |\n| Vague instructions cause rework | 🎯 **Sub-Agent Routing** — Tasks auto-route to specialists via `runSubagent` |\n| Code gets lost in handoffs | 📦 **Lossless Artifacts** — Code passed verbatim, never summarized |\n\n---\n\n## 🚀 Quick Start (3 Steps!)\n\n\u003e **Requirement**: Python 3.9+ must be installed on your system. The Continuous Command Loop uses `python -c` for terminal interaction.\n\n### Step 1: Copy to Your Project\n\n**Option A: Download Release (Recommended)**\n\n1. Download the latest `ouroboros-vX.X.X.zip` from [Releases](https://github.com/MLGBJDLW/ouroboros/releases)\n2. Extract to your project root\n3. Done! You should now have `.github/` and `.ouroboros/` folders\n\n**Option B: Git Clone**\n\n```bash\ngit clone https://github.com/MLGBJDLW/ouroboros.git .ouroboros-temp\ncp -r .ouroboros-temp/.github .\ncp -r .ouroboros-temp/.ouroboros .\nrm -rf .ouroboros-temp\n```\n\nEither way, your project should have:\n- `.github/` — Copilot instructions and agents\n- `.ouroboros/` — Persistent memory system\n\n### Step 2: Enable Custom Instructions in VS Code\n\n1. Open Settings (`Ctrl+,` / `Cmd+,`)\n2. Search: `github.copilot.chat.codeGeneration.useInstructionFiles`\n3. ✅ **Enable it**\n\n### Step 3: Enable VS Code Settings (Important!)\n\nEnable these settings for full functionality:\n\n| Setting | Search For | Purpose |\n|---------|------------|---------|\n| 🔧 **Custom Instructions** | `github.copilot.chat.codeGeneration.useInstructionFiles` | Load `.github/copilot-instructions.md` |\n| 🤖 **Agent Mode** | `github.copilot.chat.agent` | Enable agent-based interactions |\n\n\u003e **Note**: Ouroboros v2.0 requires the **Main Orchestrator Agent** (`ouroboros.agent.md`). Do not invoke subagents directly; always start with `/ouroboros`.\n\n\u003e [!WARNING]\n\u003e **Context Window Limitation**: Due to AI provider token limits, the context window may become exhausted after approximately **1 hour** of continuous use. When this happens:\n\u003e - The AI may lose track of previous context\n\u003e - Performance may degrade or the session may stop responding\n\u003e\n\u003e This is an inherent limitation of current AI technology, not a bug in Ouroboros.\n\n### Step 4: Configure Agent Tools \u0026 MCP (Optional)\n\nEach agent's tools can be configured via VS Code's agent settings:\n\n1. Open agent file (e.g., `.github/agents/ouroboros-coder.agent.md`)\n2. Click the ⚙️ gear icon to open tools configuration\n3. Enable/disable tools as needed (`edit`, `execute`, `memory`, etc.)\n\n**For MCP Servers**: Add your MCP configuration to `.vscode/mcp.json` or VS Code settings to extend agent capabilities with external tools.\n\n---\n\n## 🧩 VS Code Extension (v3.2.0+)\n\nExperience Ouroboros with a rich visual interface in VS Code.\n\n### Features\n\n| Feature | Description |\n|:---|:---|\n| **Sidebar UI** | Visual workflow progress, pending requests, agent hierarchy |\n| **LM Tools** | 6 tools for Copilot integration (`ouroboros_ask`, `ouroboros_menu`, etc.) |\n| **Keyboard Shortcuts** | Press 1-4 to switch views, arrows to navigate |\n| **Auto-Detection** | Automatically uses Extension or TUI mode |\n\n### Installation\n\n**From VS Code Marketplace:**\n1. Open VS Code Extensions (`Ctrl+Shift+X`)\n2. Search for **\"Ouroboros AI\"**\n3. Click Install\n4. Run: **Ouroboros: Initialize Project** from Command Palette (`Ctrl+Shift+P`)\n\n**From Source:**\n```bash\ncd extension\nnpm install\nnpm run compile\n# Then press F5 in VS Code to launch Extension Development Host\n```\n\n### Sidebar Views\n\n| Tab | Key | Purpose |\n|:---|:---|:---|\n| Pending Requests | `1` | Respond to agent inputs |\n| Workflow Progress | `2` | Track spec/implement phases |\n| Agent Hierarchy | `3` | See current agent and handoffs |\n| History | `4` | View past interactions |\n\n\u003e 📖 **Extension source**: [`extension/README.md`](extension/README.md)\n\n---\n\n## 🤖 Custom Agents (16 Total)\n\nAll agents are located in `.github/agents/`. The system uses a **hub-and-spoke** model with one main orchestrator and specialized subagents.\n\n### Main Orchestrator\n| Agent | Role |\n|-------|------|\n| `ouroboros` | **MAIN ORCHESTRATOR**. The only agent you talk to. Delegates everything via `runSubagent()`. |\n\n### Workflow Orchestrators (Sub-Orchestrators)\nThese are specialized orchestrators for major workflows. They inherit CCL enforcement and delegation rules from the main orchestrator.\n\n| Agent | Role | Invoked By |\n|-------|------|------------|\n| `ouroboros-init` | Project initialization workflow | `/ouroboros-init` |\n| `ouroboros-spec` | 5-phase spec workflow | `/ouroboros-spec` |\n| `ouroboros-implement` | Task execution workflow | `/ouroboros-implement` |\n| `ouroboros-archive` | Archive management | `/ouroboros-archive` |\n\n### Worker Agents (Specialists)\n| Agent | Role |\n|-------|------|\n| `ouroboros-coder` | Full-stack development (Edit, Execute, Build) |\n| `ouroboros-qa` | Unified Testing \u0026 Debugging (Fix-Verify Cycle) |\n| `ouroboros-writer` | Documentation \u0026 File Writing (No code logic) |\n| `ouroboros-devops` | CI/CD, Docker, Deployment |\n| `ouroboros-analyst` | Read-only Codebase Analysis |\n| `ouroboros-security`| Security Audits \u0026 Vulnerability Checks |\n\n### Spec Phase Agents (Workers)\n| Agent | Role |\n|-------|------|\n| `ouroboros-researcher` | Project Research (Phase 1) |\n| `ouroboros-requirements` | EARS Requirements (Phase 2) |\n| `ouroboros-architect` | System Design \u0026 ADRs (Phase 3) |\n| `ouroboros-tasks` | Task Breakdown \u0026 Planning (Phase 4) |\n| `ouroboros-validator` | Consistency \u0026 Logic Verification (Phase 5) |\n\n---\n\n## 🧠 How It Works: The v2.0 Architecture\n\n### Centralized Orchestration\n\nOuroboros v2.0 uses a strict **Hub-and-Spoke** model. You never talk to the subagents; you talk to the Orchestrator, and it calls them for you.\n\n```mermaid\nflowchart TD\n    User((User)) --\u003e|Chat| Orch[Main Agent: ouroboros]\n    \n    subgraph Workflow_Orchestrators[Workflow Orchestrators]\n        Init[ouroboros-init]\n        Spec[ouroboros-spec]\n        Impl[ouroboros-implement]\n        Arch[ouroboros-archive]\n    end\n    \n    subgraph Worker_Agents[Worker Agents]\n        Coder[ouroboros-coder]\n        QA[ouroboros-qa]\n        Writer[ouroboros-writer]\n        Analyst[ouroboros-analyst]\n    end\n    \n    Orch --\u003e|runSubagent| Init\n    Orch --\u003e|runSubagent| Spec\n    Orch --\u003e|runSubagent| Impl\n    Orch --\u003e|runSubagent| Arch\n    Orch --\u003e|runSubagent| Coder\n    Orch --\u003e|runSubagent| QA\n    Orch --\u003e|runSubagent| Writer\n    \n    Init --\u003e|runSubagent| Analyst\n    Init --\u003e|runSubagent| Writer\n    Spec --\u003e|runSubagent| SpecAgents[Spec Phase Agents]\n    Impl --\u003e|runSubagent| Coder\n    Impl --\u003e|runSubagent| QA\n    Arch --\u003e|runSubagent| Writer\n    \n    Init --\u003e|handoff| Orch\n    Spec --\u003e|handoff| Orch\n    Impl --\u003e|handoff| Orch\n    Arch --\u003e|handoff| Orch\n    \n    Orch --\u003e|Updates| Memory[(context.md)]\n```\n\n### The Return Protocol\n\nTo prevent agents from \"hallucinating\" success or getting lost:\n1. Orchestrator calls `runSubagent(agent: \"ouroboros-coder\", task: \"Implement auth\")`.\n2. Subagent activates, reads context, does the work.\n3. Subagent **MUST** return a structured result to the Orchestrator.\n4. Orchestrator verifies the work and either completes the task or loops back.\n\n---\n\n## ♾️ Core Usage: Persistent Sessions\n\nThe foundation of Ouroboros is the **persistent session loop** — AI that never forgets and never says goodbye.\n\n### Start a Session\n\n```\n/ouroboros\n```\n\nor simply type `/ouroboros` in Copilot Chat.\n\nThis command:\n1. ✅ Loads your project context from `history/context-*.md`\n2. ✅ Activates the **Continuous Command Loop (CCL)**\n3. ✅ Routes tasks to specialized sub-agents automatically\n4. ✅ Never ends until you say \"stop\", \"end\", \"terminate\", or \"quit\"\n\n\u003e [!IMPORTANT]\n\u003e **Verify Activation**: You should see a banner like:\n\u003e ```\n\u003e ♾️ OUROBOROS — SESSION ACTIVE\n\u003e ```\n\u003e If you don't see this banner or the CCL prompt `[Ouroboros] \u003e`, **re-run `/ouroboros`** to ensure proper activation.\n\n### The \"Never Say Goodbye\" Protocol\n\nOnce `/ouroboros` is active, the AI will:\n- ❌ Never say \"Let me know if you need anything else\"\n- ❌ Never end the conversation prematurely\n- ✅ Always execute: `python -c \"task = input('[Ouroboros] \u003e ')\"` after each task\n- ✅ Wait for your next instruction continuously\n\n---\n\n## 🎨 Enhanced CCL Input (Optional)\n\nUpgrade your terminal input with visual UI, command history, and intelligent content detection.\n\n### How It Works\n\nThe toggle script automatically modifies `.github/copilot-instructions.md` to switch between:\n- **Default Mode**: Uses standard `python -c \"task = input()\"` \n- **Enhanced Mode**: Uses `python .ouroboros/scripts/ouroboros_input.py` with full UI\n\n### Quick Start\n\n```bash\n# Windows: double-click\n.ouroboros/scripts/toggle.bat\n\n# Mac/Linux: \nchmod +x .ouroboros/scripts/toggle.sh\n.ouroboros/scripts/toggle.sh\n\n# Command line options:\npython .ouroboros/scripts/ouroboros_toggle.py                # Interactive menu\npython .ouroboros/scripts/ouroboros_toggle.py --mode enhanced  # Enable\npython .ouroboros/scripts/ouroboros_toggle.py --mode default   # Disable\n```\n\n### Key Features\n\n- **Arrow Key Navigation** — Full cursor movement in Windows VS Code Terminal\n- **Slash Command Autocomplete** — Type `/` for dropdown suggestions, Tab to complete\n- **File Drag \u0026 Drop** — Files display as `[ filename ]` badges\n- **Command History** — `↑`/`↓` to browse previous commands\n- **Multi-line Input** — Dynamic box height with scrolling\n- **Zero Dependencies** — Python standard library only\n\n### Quick Reference\n\n| Key | Action |\n|-----|--------|\n| `↑/↓` | History / Navigate |\n| `Ctrl+D` | Submit |\n| `Tab` | Complete command |\n| `Ctrl+C` | Cancel |\n\n\u003e 📖 **Full documentation**: [`.ouroboros/scripts/README.md`](.ouroboros/scripts/README.md)\n\n## 📋 Spec-Driven Development\n\nFor complex features, use the structured spec workflow:\n\n| Command | Purpose |\n|---------|---------|\n| `/ouroboros-init` | 🆕 First-time project research \u0026 setup |\n| `/ouroboros-spec` | Create Research → Requirements → Design → Tasks |\n| `/ouroboros-implement` | Auto-execute tasks.md |\n| `/ouroboros-archive` | Archive completed specs |\n\n### 🎮 Execution Modes (`/ouroboros-implement`)\n\nChoose how to execute your implementation plan:\n\n| Mode | Speed | Control | Best For |\n|------|-------|---------|----------|\n| 🔧 **Task-by-Task** | Slowest | Highest | High-risk changes, learning |\n| 📦 **Phase-by-Phase** | Medium | Medium | Normal development |\n| 🚀 **Auto-Run All** | Fastest | Lowest | Low-risk, trusted tasks |\n\n---\n\n## 🛡️ Safety \u0026 Reliability\n\n- **Destructive Command Protection**: `rm -rf`, `git reset --hard` require confirmation\n- **Verification Gate**: Code is verified before delivery\n- **QA Agent Fix-Verify Cycle**: Self-contained testing and debugging with 3-cycle limit\n- **Fail-Safe Protocols**:\n  - 🏗️ **Coder**: Must pass build/typecheck before completion\n  - 🚀 **DevOps**: Auto-rollback if exit code \u003e 0\n  - 🛑 **Git**: Immediate halt on merge conflicts\n- **RETURN PROTOCOL**: All subagents return to orchestrator after completion\n\n---\n\n## 📁 File Structure\n\n```\nyour-project/\n├── .github/\n│   ├── copilot-instructions.md    ← Copilot reads this automatically\n│   ├── agents/                    ← 🤖 Agent definitions (16 agents)\n│   │   ├── ouroboros.agent.md     ← MAIN ORCHESTRATOR\n│   │   ├── ouroboros-init.agent.md    ← Workflow: Init\n│   │   ├── ouroboros-spec.agent.md    ← Workflow: Spec\n│   │   ├── ouroboros-implement.agent.md ← Workflow: Implement\n│   │   ├── ouroboros-archive.agent.md ← Workflow: Archive\n│   │   ├── ouroboros-coder.agent.md   ← Worker: Coder\n│   │   └── ... (11 more workers)\n│   └── prompts/                   ← Slash command prompts (lightweight refs)\n│       ├── ouroboros.prompt.md    → agent: ouroboros\n│       ├── ouroboros-init.prompt.md → agent: ouroboros-init\n│       └── ...\n├── .ouroboros/\n│   ├── templates/                 ← 📋 All templates (READ ONLY)\n│   ├── history/                   ← 📜 Active session files\n│   ├── subagent-docs/             ← 📄 Long output storage\n│   ├── specs/                     ← 📋 Feature specifications\n│   └── scripts/                   ← 🎨 Enhanced CCL (optional)\n│       ├── ouroboros_input.py     ← Main entry point\n│       ├── ouroboros_toggle.py    ← Mode toggle script\n│       ├── components/            ← UI components\n│       │   ├── input_box.py, selection_menu.py, status_bar.py, welcome_box.py\n│       ├── data/                  ← Data management\n│       │   ├── buffer.py, config.py, history.py\n│       ├── input/                 ← Input handling\n│       │   ├── keybuffer.py, keybuffer_win.py, keybuffer_unix.py\n│       │   ├── clipboard.py, commands.py, paste.py\n│       ├── tui/                   ← Terminal UI\n│       │   ├── app.py, screen.py, theme.py, window.py, output.py\n│       ├── utils/                 ← Utilities\n│       │   ├── badge.py, filepath.py, text.py\n│       └── tests/                 ← Test suite\n└── ... your project files\n```\n\n---\n\n## 🙏 Acknowledgments\n\nOuroboros was inspired by:\n\n- **[TaskSync](https://github.com/4regab/TaskSync)** — The original concept of persistent AI sessions and the \"never say goodbye\" protocol. Many of Ouroboros's core ideas evolved from TaskSync's pioneering work.\n- **[Roo Code](https://github.com/RooCodeInc/Roo-Code)** — Early pioneer of agent teams architecture, demonstrating multi-agent orchestration patterns in AI-assisted development.\n- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** — Structured specification-driven development approach that influenced our `/ouroboros-spec` workflow.\n\n---\n\n## 📋 Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and updates.\n\n---\n\n## 📜 License\n\nMIT License — Free for personal and commercial use.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e♾️ The Serpent Consumes Its Tail. The Loop Never Ends. ♾️\u003c/strong\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlgbjdlw%2Fouroboros","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlgbjdlw%2Fouroboros","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlgbjdlw%2Fouroboros/lists"}