ouroboros
Sits in front of Claude Code and fixes the brief before the code. An interview scores how vague your request is, and a score above the bar blocks spec generation until you pass force explicitly. When an acceptance criterion defines a verify command or an expected-output assertion, those values are omitted from the worker's contract block, with no flag to put them back, so the worker is asked for the outcome rather than handed the assertion. Redaction of those values elsewhere is literal over five encodings, so a reshaped copy can still get through; that gap is tracked in a public issue.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Q00/ouroboros with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Q00/ouroboros'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/q00--ouroboros)HTML
<a href="/listings/q00--ouroboros"><img src="/api/listings/q00--ouroboros/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
# macOS / Linux / WSL 2 curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | OUROBOROS_INSTALL_REF=readme bash
# Windows (PowerShell) — no Python needed; installs Git and uv for you irm https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.ps1 | iex
When installation finishes, the Ouroboros console opens in your browser and walks you through connecting your agent tools. Reopen it any time with `ouroboros gui`.
The installer finds the agent tools you already have and connects Ouroboros to them. Native Windows is experimental, and Codex CLI needs WSL 2; see [platform support](./docs/platform-support.md).
**Other ways to install.** These don't open the console for you; run `ouroboros gui` once the `ouroboros` command is installed.
# Claude Code plugin only (then run /ouroboros:setup inside Claude Code) claude plugin marketplace add Q00/ouroboros && claude plugin install ouroboros@ouroboros # pip / uv / pipx (Python 3.12+) pip install 'ouroboros-ai[mcp,tui]' && ouroboros setup --runtime claude-cli # Homebrew (macOS / Linux) brew tap q00/tap && brew install ouroboros-ai && ouroboros setup
Every install path, profile and host is in [Getting Started](./docs/getting-started.md). `ouroboros uninstall` removes Ouroboros's configuration, MCP registrations and data directory (`~/.ouroboros/`). It leaves the Python package and the Claude Code plugin installed; finish with the steps in [UNINSTALL.md](./UNINSTALL.md).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 40 lines
- {
- "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
- "name": "ouroboros",
- "description": "Sits in front of Claude Code and fixes the brief before the code. An interview scores how vague your request is, and a score above the bar blocks spec generation until you pass force explicitly. When an acceptance criterion defines a verify command or an expected-output assertion, those values are omitted from the worker's contract block, with no flag to put them back, so the worker is asked for the outcome rather than handed the assertion. Redaction of those values elsewhere is literal over five encodings, so a reshaped copy can still get through; that gap is tracked in a public issue.",
- "owner": {
- "name": "Q00",
- "email": "jqyu.lee@gmail.com"
- },
- "plugins": [
- {
- "name": "ouroboros",
- "description": "Sits in front of Claude Code and fixes the brief before the code. An interview scores how vague your request is, and a score above the bar blocks spec generation until you pass force explicitly. When an acceptance criterion defines a verify command or an expected-output assertion, those values are omitted from the worker's contract block, with no flag to put them back, so the worker is asked for the outcome rather than handed the assertion. Redaction of those values elsewhere is literal over five encodings, so a reshaped copy can still get through; that gap is tracked in a public issue.",
- "version": "0.61.1",
- "author": {
- "name": "Q00",
- "email": "jqyu.lee@gmail.com"
- },
- "source": "./",
- "category": "development",
- "homepage": "https://github.com/Q00/ouroboros",
- "repository": "https://github.com/Q00/ouroboros",
- "license": "MIT",
- "keywords": [
- "workflow",
- "requirements",
- "socratic",
- "interview",
- "seed",
- "evaluation",
- "agentic-loop",
- "loop-engineering"
- ],
- "tags": [
- "requirement-engineering",
- "self-improving",
- "crystallization"
- ]
- }
- ]
- }
README.md · README · 206 lines · 1 finding marked
- <!-- mcp-name: io.github.Q00/ouroboros -->
- <p align="right">
- <strong>English</strong> | <a href="./README.ko.md">한국어</a> | <a href="./README.zh-CN.md">简体中文</a>
- </p>
- <p align="center">
- <br/>
- ◯ ─────────── ◯
- <br/><br/>
- <img src="./docs/images/ouroboros.png" width="420" alt="Ouroboros">
- <br/><br/>
- <strong>O U R O B O R O S</strong>
- <br/><br/>
- ◯ ─────────── ◯
- <br/>
- </p>
- <p align="center">
- <strong>It gets smarter on its own. We just hold the line.</strong>
- <br/>
- <sub>Ask first, build second, check always: spec-first AI coding for the agents you already use.</sub>
- </p>
- <p align="center">
- <a href="https://github.com/Q00/ouroboros"><img src="https://img.shields.io/github/stars/Q00/ouroboros?color=yellow&logo=github&label=stars" alt="GitHub stars"></a>
- <a href="https://pypi.org/project/ouroboros-ai/"><img src="https://img.shields.io/pypi/v/ouroboros-ai?color=blue" alt="PyPI"></a>
- <a href="https://github.com/Q00/ouroboros/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/Q00/ouroboros/test.yml?branch=main" alt="Tests"></a>
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
- <a href="https://github.com/sponsors/Q00"><img src="https://img.shields.io/github/sponsors/Q00?logo=githubsponsors&color=EA4AAA&label=sponsors" alt="GitHub Sponsors"></a>
- </p>
- <p align="center">
- <a href="https://trendshift.io/repositories/26008?utm_source=repository-badge&utm_medium=badge&utm_campaign=badge-repository-26008" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/26008" alt="Q00%2Fouroboros | Trendshift" width="250" height="55"/></a>
- </p>
- <p align="center">
- <a href="#install">Install</a> ·
- <a href="#first-steps">First steps</a> ·
- <a href="#works-with">Works with</a> ·
- <a href="#learn-more">Learn more</a> ·
- <a href="https://ouroboros.page/learn/en/">Guide</a>
- </p>
- Ouroboros helps your AI coding agent build the right thing. It asks you
- questions until the goal is clear, writes the answer down as a spec with
- checkable acceptance criteria, hands that spec to the coding agent you already
- use, and then checks the result against the spec.
- <p align="center">
- <img src="./docs/images/console-tour-en.gif" width="900" alt="Screen recording of the Ouroboros console in a browser. On the Chat page in Auto mode, the request Please make a todo cli tool starts an ouroboros auto run whose output streams into the chat; the tour then visits the Runs, Connect, Agents and models, Providers, Shared MCP and Health pages.">
- </p>
- <p align="center">
- <sub>The Ouroboros console: type what you want in Chat, and it runs the interview, the spec, the build and the checks for you.</sub>
- </p>
- ## Install
- ```bash
- # macOS / Linux / WSL 2
- curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | OUROBOROS_INSTALL_REF=readme bash
- ```
- ```powershell
- # Windows (PowerShell) — no Python needed; installs Git and uv for you
- irm https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 67 on GitHub
- ```
- When installation finishes, the Ouroboros console opens in your browser and
- walks you through connecting your agent tools. Reopen it any time with
- `ouroboros gui`.
- The installer finds the agent tools you already have and connects Ouroboros to
- them. Native Windows is experimental, and Codex CLI needs WSL 2; see
- [platform support](./docs/platform-support.md).
- **Other ways to install.** These don't open the console for you; run
- `ouroboros gui` once the `ouroboros` command is installed.
- ```bash
- # Claude Code plugin only (then run /ouroboros:setup inside Claude Code)
- claude plugin marketplace add Q00/ouroboros && claude plugin install ouroboros@ouroboros
- # pip / uv / pipx (Python 3.12+)
- pip install 'ouroboros-ai[mcp,tui]' && ouroboros setup --runtime claude-cli
- # Homebrew (macOS / Linux)
- brew tap q00/tap && brew install ouroboros-ai && ouroboros setup
- ```
- Every install path, profile and host is in
- [Getting Started](./docs/getting-started.md). `ouroboros uninstall` removes
- Ouroboros's configuration, MCP registrations and data directory
- (`~/.ouroboros/`). It leaves the Python package and the Claude Code plugin
- installed; finish with the steps in [UNINSTALL.md](./UNINSTALL.md).
- ## First steps
- Describe what you want in plain words. Four good places to start:
- - **Console Chat**: type a goal and pick **Interview** (it asks until the goal is clear) or **Auto** (it fills the gaps itself), then hand the spec to your agents and watch the run.
- - **`ooo interview "a todo CLI with due dates"`** in your agent: questions until the goal is clear, then a spec (a *Seed*).
- - **`ooo auto "a todo CLI with due dates"`**: asks only what is missing, writes the spec, runs it, and checks it.
- - **`ooo run`**: builds an existing Seed and checks every acceptance criterion.
- In Claude Code, run `/ouroboros:setup` once and finish its questions, then send
- your first `ooo` command as a separate message. From a plain terminal,
- `ouroboros init start "..."` and `ouroboros auto "..."` do the same without an
- agent host. The full command list is in
- [Getting Started](./docs/getting-started.md#commands).
- > Ouroboros runs coding agents that can change files and run commands in your
- > project. Read [permission scope](./skills/help/TROUBLESHOOTING.md#permission-scope)
- > before using it on a project you don't trust.
- ## Works with
- [Claude Code](./docs/runtime-guides/claude-code.md) ·
- [Codex CLI](./docs/runtime-guides/codex.md) ·
- [GitHub Copilot CLI](./docs/runtime-guides/copilot.md) ·
- [OpenCode](./docs/runtime-guides/opencode.md) ·
- [Hermes](./docs/runtime-guides/hermes.md) ·
- [Gemini CLI](./docs/runtime-guides/gemini.md) ·
- [Kiro CLI](./docs/runtime-guides/kiro.md) ·
- [Pi](./docs/runtime-guides/pi.md) ·
- [OMP](./docs/runtime-guides/omp.md) ·
- [Zcode](./docs/runtime-guides/zcode.md) ·
- [Goose](./docs/runtime-guides/goose.md) ·
- [GJC](./docs/runtime-guides/gjc.md) ·
- [Antigravity CLI](./docs/runtime-guides/antigravity.md) ·
- [Grok Build CLI](./docs/runtime-guides/grok.md) ·
- [DeepSeek Harness](./docs/guides/deepseek-harness.md)
- The installer connects the ones you have; the console's **Connect** page
- installs and connects the rest. Want to see it first?
- [Watch the interview run on seven different hosts](./docs/how-ouroboros-works.md#see-it-on-each-host).
- ## Learn more
- - [Getting Started](./docs/getting-started.md): every install path, host-by-host setup, your first workflow, and all commands.
- - [Console guide](./docs/guides/console.md): what each console page does, the shared MCP server, and starting the console at login.
- - [How Ouroboros works](./docs/how-ouroboros-works.md): the loop, the agents, the ambiguity gate, the Agent OS stack, architecture, and philosophy.
- - [CLI reference](./docs/cli-reference.md) · [Configuration](./docs/config-reference.md) · [Platform support](./docs/platform-support.md) · [All docs](./docs/README.md)
- - [Interactive guide](https://ouroboros.page/learn/en/)
- <p align="center">
- <sub>Most people find out they were unclear about three files into the review.<br/>
- If that feels familiar, star <a href="https://github.com/Q00/ouroboros"><strong>Q00/ouroboros on GitHub</strong></a> so the next person it could save can find it.</sub>
- </p>
- ## Contributing
- ```bash
- git clone https://github.com/Q00/ouroboros
- cd ouroboros
- uv sync --python 3.13 --all-groups
- uv run --python 3.13 --no-sync pytest
- ```
- [Issues](https://github.com/Q00/ouroboros/issues) · [Discussions](https://github.com/Q00/ouroboros/discussions) · [Contributing Guide](./CONTRIBUTING.md)
- ## Sponsors
- Ouroboros is MIT-licensed and built in the open. If it saves you rework, consider
- sponsoring: it funds maintenance, new runtime integrations, and sponsor-only
- deep-dive content.
- <p align="center">
- <a href="https://github.com/sponsors/Q00"><img src="https://img.shields.io/badge/%E2%9D%A4%EF%B8%8E%20Sponsor%20on%20GitHub-EA4AAA?style=for-the-badge&logo=githubsponsors&logoColor=white" alt="Sponsor Q00 on GitHub"></a>
- </p>
- ## Activity
- These numbers are generated from GitHub data and refreshed automatically; caching may delay updates.
- <p align="center">
- <a href="https://github.com/Q00/ouroboros/graphs/contributors"><img src="https://img.shields.io/github/contributors/Q00/ouroboros?color=orange" alt="Contributors"></a>
- <a href="https://github.com/Q00/ouroboros/commits/main"><img src="https://img.shields.io/github/commit-activity/m/Q00/ouroboros?color=orange" alt="Commit activity"></a>
- <a href="https://github.com/Q00/ouroboros/pulls?q=is%3Apr+is%3Aclosed"><img src="https://img.shields.io/github/issues-pr-closed/Q00/ouroboros?color=orange" alt="Closed pull requests"></a>
- <a href="https://github.com/Q00/ouroboros/commits/main"><img src="https://img.shields.io/github/last-commit/Q00/ouroboros?color=orange" alt="Last commit"></a>
- </p>
- ## Disclaimer
- > The Ouroboros project and community are **not affiliated with any
- > cryptocurrency, token, memecoin, or trading community** — including, but not
- > limited to, any "ouroboros" tickers on pump.fun or other launchpads. This is
- > an open-source developer tool. We do not issue, endorse, or hold any coins.
- > Any token claiming association with this project is unauthorized.
- > **Naming note.** A separate, unaffiliated open-source project also uses the
- > name "Ouroboros" — Anton Razzhigaev's self-modifying, autonomous-memory agent
- > at `github.com/razzant/ouroboros`. No shared code, no relationship. This
- > project locks a specification before executing rather than rewriting its own
- > architecture; if you're looking for the latter, that's the other one.
- ---
- <p align="center">
- <em>"The beginning is the end, and the end is the beginning."</em>
- <br/><br/>
- <strong>The serpent does not repeat -- it evolves.</strong>
- <br/><br/>
- <code>MIT License</code>
- </p>
scripts/install.ps1 · Bundled script · 628 lines · 1 finding marked
- # Ouroboros installer for native Windows (PowerShell 5.1+ / pwsh 7+).
- #
- # Usage (no Python, no uv, no Git needed beforehand):
- # irm https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 4 on GitHub
- #
- # With options (the pipe form cannot take parameters, so bind the script first):
- # & ([scriptblock]::Create((irm https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.ps1))) -Runtime codex
- #
- # Environment variables mirror scripts/install.sh and work with the pipe form:
- # OUROBOROS_INSTALL_RUNTIME claude|claude-sdk|claude-cli|codex|opencode|hermes|gemini|goose|kiro|copilot|pi|gjc|all
- # OUROBOROS_INSTALL_RECONFIGURE set to 1 to ignore the runtime saved in ~/.ouroboros/config.yaml
- # OUROBOROS_INSTALL_PRE set to 1 to allow pre-release versions
- # OUROBOROS_NO_CONSOLE set to 1 to skip starting the Ouroboros console (same as -NoConsole)
- #
- # Parameters: -Runtime <name>, -Reconfigure, -Pre, -NoConsole
- #
- # What it does, in order:
- # 1. Git >= 2.36 and uv: installed through winget when missing (uv falls back
- # to the astral.sh installer). uv downloads its own Python, so the machine
- # does not need one.
- # 2. Picks a backend the same way install.sh does: explicit > saved config >
- # single detected CLI > prompt.
- # 3. `uv tool install` with the selected distribution's own extras, like install.sh.
- # 4. `ouroboros setup --runtime <backend> --non-interactive`, `setup refresh`,
- # and the Claude Code plugin when `claude` is on PATH.
- # 5. When the installed release ships `ouroboros gui` and this is an
- # interactive desktop session (no CI variable, console input not
- # redirected, not an SSH session), starts the Ouroboros console in a
- # hidden background process, which opens it in the browser. Otherwise it
- # only prints the command. -NoConsole / OUROBOROS_NO_CONSOLE=1 skip this.
- #
- # This installer emits no installer events of its own (no install_started /
- # install_completed). The `ouroboros` CLI it invokes for setup follows the normal
- # telemetry controls in TELEMETRY.md, exactly as it does under install.sh.
- # Native Windows support is experimental; Codex CLI is only supported under WSL 2 (docs/platform-support.md).
- [CmdletBinding()]
- param(
- [string]$Runtime = $env:OUROBOROS_INSTALL_RUNTIME,
- [switch]$Reconfigure,
- [switch]$Pre,
- [switch]$NoConsole
- )
- $ErrorActionPreference = 'Stop'
- Set-StrictMode -Version 2.0
- # Dependency versions belong to the selected distribution's extras. Do not
- # override an older PyPI release with optional pins from this installer.
- $PackageName = 'ouroboros-ai'
- $ClickSpec = 'click>=8.1.0,<9.0.0'
- $DefaultPythonSpec = '>=3.12'
- $LiteLLMPythonSpec = '>=3.12,<3.14'
- $MinGitVersion = [version]'2.36.0'
- $MinPython = [version]'3.12'
- $HookPythonVersion = '3.13'
- $AllRuntimes = @('claude', 'claude-sdk', 'claude-cli', 'codex', 'opencode', 'hermes', 'gemini', 'goose', 'kiro', 'copilot', 'pi', 'gjc')
- if ([string]::IsNullOrWhiteSpace($Runtime)) { $Runtime = '' }
- if (-not $Reconfigure -and $env:OUROBOROS_INSTALL_RECONFIGURE) { $Reconfigure = $true }
- if (-not $Pre -and $env:OUROBOROS_INSTALL_PRE) { $Pre = $true }
- # --- output helpers -----------------------------------------------------------
- function Write-Step([string]$Title, [string]$Detail) {
- Write-Host ''
- Write-Host "== $Title" -ForegroundColor Cyan
- if ($Detail) { Write-Host " $Detail" -ForegroundColor DarkGray }
- }
- function Write-Ok([string]$Message) { Write-Host " [ok] $Message" -ForegroundColor Green }
- function Write-Info([string]$Message) { Write-Host " - $Message" -ForegroundColor DarkGray }
- function Write-Warn([string]$Message) { Write-Host " [!] $Message" -ForegroundColor Yellow }
- function Write-Err([string]$Message) { Write-Host " [x] $Message" -ForegroundColor Red }
- function Test-Interactive {
- try { return -not [Console]::IsInputRedirected } catch { return $false }
- }
- # Installers register their directories in the user/machine PATH, but the
- # current session keeps the PATH it started with. Merge the registry PATH in so
- # a tool installed a moment ago is visible without opening a new terminal.
- function Sync-SessionPath {
- $parts = New-Object System.Collections.Generic.List[string]
- $seen = @{}
- foreach ($scope in @('Process', 'User', 'Machine')) {
- $value = [Environment]::GetEnvironmentVariable('Path', $scope)
- if (-not $value) { continue }
- foreach ($entry in $value.Split(';')) {
- $trimmed = $entry.Trim()
- if (-not $trimmed) { continue }
- $key = $trimmed.TrimEnd('\').ToLowerInvariant()
- if ($seen.ContainsKey($key)) { continue }
- $seen[$key] = $true
- $parts.Add($trimmed)
- }
- }
- $env:Path = ($parts -join ';')
- }
- function Add-SessionPathFront([string]$Directory) {
- if (-not $Directory) { return }
- $current = $env:Path.Split(';') | ForEach-Object { $_.TrimEnd('\').ToLowerInvariant() }
- if ($current -contains $Directory.TrimEnd('\').ToLowerInvariant()) { return }
- $env:Path = "$Directory;$env:Path"
- }
- function Get-CommandPath([string]$Name) {
- $found = Get-Command $Name -ErrorAction SilentlyContinue
- if ($found) { return $found.Source }
- return $null
- }
- # Native commands do not throw on Windows PowerShell 5.1; check the exit code.
- function Invoke-Native([string]$Command, [string[]]$Arguments) {
- $global:LASTEXITCODE = 0
- # Output goes straight to the host so the function returns only the bool.
- & $Command @Arguments | Out-Host
- return ($LASTEXITCODE -eq 0)
- }
- function Test-Winget {
- return [bool](Get-CommandPath 'winget')
- }
- function Install-WithWinget([string]$Id, [string]$Label) {
- if (-not (Test-Winget)) { return $false }
- Write-Info "Installing $Label with winget ($Id)..."
- $ok = Invoke-Native 'winget' @('install', '--id', $Id, '-e', '--silent', '--accept-source-agreements', '--accept-package-agreements')
- Sync-SessionPath
- return $ok
- }
- # --- banner -------------------------------------------------------------------
- Write-Host ''
- Write-Host ' Ouroboros installer (Windows)' -ForegroundColor Magenta
- Write-Host ' Specification-first AI development' -ForegroundColor DarkGray
- Write-Host ''
- Write-Warn 'Native Windows support is experimental. Codex CLI needs WSL 2; for the fully supported path run scripts/install.sh inside WSL 2.'
- # --- 1/4 prerequisites: Git and uv -------------------------------------------
- Write-Step '1/4 Checking Git and uv' 'Both are installed automatically when missing. No Python is required.'
- Sync-SessionPath
- $gitPath = Get-CommandPath 'git'
- if (-not $gitPath) {
- Write-Warn 'Git not found.'
- if (-not (Install-WithWinget 'Git.Git' 'Git')) {
- Write-Err 'Git >= 2.36 is required and could not be installed automatically.'
- Write-Info 'Install it from https://git-scm.com/download/win, open a new PowerShell window, and run this installer again.'
- exit 1
- }
- $gitPath = Get-CommandPath 'git'
- if (-not $gitPath) {
- Write-Err 'Git was installed but is not on PATH yet. Open a new PowerShell window and run this installer again.'
- exit 1
- }
- }
- $gitVersionText = (& git --version 2>$null) -join ' '
- $gitMatch = [regex]::Match($gitVersionText, '(\d+)\.(\d+)\.(\d+)')
- if ($gitMatch.Success) {
- $gitVersion = [version]("{0}.{1}.{2}" -f $gitMatch.Groups[1].Value, $gitMatch.Groups[2].Value, $gitMatch.Groups[3].Value)
- if ($gitVersion -lt $MinGitVersion) {
- Write-Err "Git $gitVersion found, but Ouroboros needs Git >= $MinGitVersion."
- Write-Info 'Upgrade with: winget upgrade --id Git.Git -e'
- exit 1
- }
- Write-Ok "Git found: $gitVersionText"
- } else {
- Write-Warn "Could not parse the Git version from '$gitVersionText'; continuing."
- }
- $uvPath = Get-CommandPath 'uv'
- if (-not $uvPath) {
- Write-Warn 'uv not found.'
- if (-not (Install-WithWinget 'astral-sh.uv' 'uv')) {
- Write-Info 'winget unavailable or failed; using the astral.sh installer...'
- try {
- [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
- $uvInstaller = Invoke-RestMethod -Uri 'https://astral.sh/uv/install.ps1' -UseBasicParsing
- Invoke-Expression $uvInstaller
- } catch {
- Write-Err "uv could not be installed: $($_.Exception.Message)"
- Write-Info 'Install it manually: winget install --id astral-sh.uv -e (or see https://docs.astral.sh/uv/getting-started/installation/)'
- exit 1
- }
- Sync-SessionPath
- }
- $uvPath = Get-CommandPath 'uv'
- if (-not $uvPath) {
- $fallbackBin = Join-Path $env:USERPROFILE '.local\bin'
- if (Test-Path (Join-Path $fallbackBin 'uv.exe')) {
- Add-SessionPathFront $fallbackBin
- $uvPath = Get-CommandPath 'uv'
- }
- }
- if (-not $uvPath) {
- Write-Err 'uv was installed but is not on PATH yet. Open a new PowerShell window and run this installer again.'
- exit 1
- }
- }
- Write-Ok "uv found: $((& uv --version 2>$null) -join ' ')"
- # --- 2/4 backend selection ------------------------------------------------------
- Write-Step '2/4 Choosing an agent backend' 'Claude, Codex, Hermes, OpenCode, Gemini, Goose, Kiro, Copilot, Pi, and GJC are supported.'
- $detected = @{}
- foreach ($pair in @(
- @('claude', 'claude'), @('codex', 'codex'), @('hermes', 'hermes'), @('opencode', 'opencode'),
- @('gemini', 'gemini'), @('goose', 'goose'), @('kiro', 'kiro-cli'), @('copilot', 'copilot'),
- @('pi', 'pi'), @('gjc', 'gjc'))) {
- $key = $pair[0]
- $exe = $pair[1]
- $found = Get-CommandPath $exe
- if ($found) {
- $detected[$key] = $found
- Write-Ok "$key found: $found"
- }
- }
- # Read the previously configured runtime so upgrades keep the user's choice.
- function Get-SavedRuntime {
- $config = Join-Path $env:USERPROFILE '.ouroboros\config.yaml'
- if (-not (Test-Path $config)) { return '' }
- $supported = @('claude', 'claude_mcp', 'codex', 'opencode', 'hermes', 'gemini', 'goose', 'kiro', 'copilot', 'pi', 'gjc')
- $inOrchestrator = $false
- foreach ($line in (Get-Content $config -ErrorAction SilentlyContinue)) {
- if ($line -match '^orchestrator:\s*(#.*)?$') { $inOrchestrator = $true; continue }
- if ($inOrchestrator -and $line -and -not [char]::IsWhiteSpace($line[0])) { break }
- if ($inOrchestrator) {
- $m = [regex]::Match($line, '^\s+runtime_backend:\s*["'']?([^"''\s#]+)')
- if ($m.Success -and ($supported -contains $m.Groups[1].Value)) {
- # claude is the SDK/MCP 1 profile; claude_mcp is the CLI/MCP 2 worker profile.
- if ($m.Groups[1].Value -eq 'claude_mcp') { return 'claude-cli' }
- return $m.Groups[1].Value
- }
- }
- }
- return ''
- }
- function Read-Choice([string]$Prompt, [string]$Default) {
- $answer = Read-Host $Prompt
- if ([string]::IsNullOrWhiteSpace($answer)) { return $Default }
- return $answer.Trim()
- }
- function Select-RuntimeInteractive([bool]$AllowNone) {
- $menu = @(
- @('1', 'claude', "Claude SDK (MCP 1.x) + skills; MCP 2 server is isolated ($PackageName[claude,tui])"),
- @('2', 'codex', "Codex plugin artifacts ($PackageName[tui]) -- native Windows: WSL 2 recommended"),
- @('3', 'hermes', "Hermes agent guides + MCP server ($PackageName[mcp,tui])"),
- @('4', 'opencode', "OpenCode commands and agent files ($PackageName[tui])"),
- @('5', 'gemini', "Gemini CLI integration ($PackageName[tui])"),
- @('6', 'goose', "Goose CLI integration ($PackageName[tui])"),
- @('7', 'kiro', "Kiro CLI integration ($PackageName[tui])"),
- @('8', 'copilot', "GitHub Copilot integration ($PackageName[tui])"),
- @('9', 'pi', "Pi CLI bridge and instruction artifacts ($PackageName[tui])"),
- @('10', 'gjc', "GJC CLI bridge and instruction artifacts ($PackageName[tui])"),
- @('11', 'all', "Install every optional integration ($PackageName[all])")
- )
- foreach ($item in $menu) { Write-Host (" {0,2}) {1,-9} {2}" -f $item[0], $item[1], $item[2]) }
- if ($AllowNone) { Write-Host (" {0,2}) {1,-9} {2}" -f '0', 'none', 'Base CLI only; choose a backend later') }
- $choice = Read-Choice 'Select [1]' '1'
- if ($AllowNone -and $choice -eq '0') { return '' }
- foreach ($item in $menu) { if ($item[0] -eq $choice) { return $item[1] } }
- return 'claude'
- }
- $selected = ''
- if ($Runtime) {
- if ($AllRuntimes -notcontains $Runtime -and $Runtime -ne 'all') {
- Write-Err "unsupported runtime '$Runtime'"
- Write-Info "Expected one of: $($AllRuntimes -join ', '), all"
- exit 1
- }
- $selected = $Runtime
- Write-Ok "Runtime: $selected (from -Runtime / OUROBOROS_INSTALL_RUNTIME)"
- } else {
- $saved = ''
- if (-not $Reconfigure) { $saved = Get-SavedRuntime }
- if ($saved) {
- $selected = $saved
- Write-Ok "Runtime: $selected (preserved from ~/.ouroboros/config.yaml)"
- Write-Info 'Re-run with -Reconfigure (or OUROBOROS_INSTALL_RECONFIGURE=1) to choose again.'
- } elseif ($detected.Count -gt 1) {
- if (Test-Interactive) {
- Write-Host ''
- Write-Host 'Multiple runtimes detected. Pick where Ouroboros should appear first:'
- $selected = Select-RuntimeInteractive $false
- } else {
- Write-Warn 'Multiple runtimes detected in non-interactive mode; defaulting to Claude.'
- $selected = 'claude'
- }
- } elseif ($detected.Count -eq 1) {
- $selected = @($detected.Keys)[0]
- } else {
- if (Test-Interactive) {
- Write-Host ''
- Write-Host 'No runtime CLI detected yet. Choose the agent you plan to use:'
- $selected = Select-RuntimeInteractive $true
- } else {
- Write-Warn 'No runtime detected in non-interactive mode; installing the base package.'
- Write-Info "Pick a backend afterwards with: ouroboros setup --runtime <$($AllRuntimes -join '|')>"
- $selected = ''
- }
- }
- }
- if ($selected -eq 'codex') {
- Write-Warn 'Codex CLI is not supported on native Windows. Setup will not register a persistent MCP server here; use WSL 2 for Codex.'
- }
- # Map the backend to the target distribution's extras. `tui` ships with every selection so
- # `ouroboros config` works out of the box; `[all]` stays on the MCP 1.x bundle.
- $extrasLabel = '[tui]'
- $setupRuntime = $selected
- $pythonSpec = $DefaultPythonSpec
- switch ($selected) {
- 'claude' { $extrasLabel = '[claude,tui]' }
- 'claude-sdk' { $extrasLabel = '[claude-sdk,tui]' }
- 'claude-cli' { $extrasLabel = '[claude-cli,tui]' }
- 'hermes' { $extrasLabel = '[mcp,tui]' }
- 'all' {
- $extrasLabel = '[all]'
- $pythonSpec = $LiteLLMPythonSpec
- $setupRuntime = ''
- }
- default { }
- }
- if ($setupRuntime) { Write-Ok "Selected backend: $setupRuntime" }
- elseif ($selected -eq 'all') { Write-Ok 'Selected backend: all' }
- else { Write-Info 'Selected backend: none yet' }
- # --- 3/4 install ------------------------------------------------------------------
- Write-Step '3/4 Installing Ouroboros' "Package: $PackageName$extrasLabel via uv tool install (uv downloads Python $pythonSpec itself)"
- $uvArgs = @('tool', 'install', '--upgrade', '--python', $pythonSpec, "$PackageName$extrasLabel", '--with', $ClickSpec)
- if ($Pre) { $uvArgs += '--prerelease=allow' }
- Write-Info "Running: uv $($uvArgs -join ' ')"
- if (-not (Invoke-Native 'uv' $uvArgs)) {
- Write-Err 'uv tool install failed. Fix the error above and run the installer again.'
- exit 1
- }
- # Put the tool bin directory on PATH: persistently (uv edits the user PATH) and
- # for this session, so setup below runs the binary that was just installed.
- $toolBin = ((& uv tool dir --bin 2>$null) -join '').Trim()
- if (-not (Invoke-Native 'uv' @('tool', 'update-shell'))) {
- Write-Warn "Could not update the user PATH automatically. Add this directory to PATH: $toolBin"
- }
- if ($toolBin) { Add-SessionPathFront $toolBin }
- $ouroborosExe = $null
- if ($toolBin -and (Test-Path (Join-Path $toolBin 'ouroboros.exe'))) {
- $ouroborosExe = Join-Path $toolBin 'ouroboros.exe'
- } else {
- $ouroborosExe = Get-CommandPath 'ouroboros'
- }
- if (-not $ouroborosExe) {
- Write-Err "Ouroboros was installed but 'ouroboros' is not on PATH. Add $toolBin to PATH, open a new window, and run: ouroboros setup --runtime <backend>"
- exit 1
- }
- Write-Ok "Installed: $((& $ouroborosExe --version 2>$null) -join ' ')"
- # Optional: the Claude Code plugin hooks look for python3/python on PATH and
- # skip themselves when none is found. Skills fall back to uv on their own, so
- # this is a convenience, not a requirement, and its failure is not fatal.
- function Test-PythonAtLeast([string]$Exe) {
- $found = Get-CommandPath $Exe
- if (-not $found) { return $false }
- # Windows ships Microsoft Store execution aliases in WindowsApps. They
- # print a diagnostic instead of running Python; skip them before invoking
- # the native command so Windows PowerShell does not surface NativeCommandError.
- if ($found -match '\\WindowsApps\\(?:python|python3)(?:\.exe)?$') { return $false }
- # Avoid embedded quotes: Windows PowerShell 5.1 strips them from native arguments.
- # This optional probe may emit stderr, which 5.1 turns into NativeCommandError
- # under Stop even with 2>$null. Judge the exit code and stdout instead.
- $previousErrorActionPreference = $ErrorActionPreference
- try {
- $ErrorActionPreference = 'Continue'
- $out = (& $found -c 'import sys; print(*sys.version_info[:2], sep=chr(46))' 2>$null) -join ''
- } catch {
- return $false
- } finally {
- $ErrorActionPreference = $previousErrorActionPreference
- }
- if ($LASTEXITCODE -ne 0 -or -not ($out -match '^\d+\.\d+$')) { return $false }
- $parsedVersion = $null
- if (-not [version]::TryParse($out, [ref]$parsedVersion)) { return $false }
- return ($parsedVersion -ge $MinPython)
- }
- if ((Test-PythonAtLeast 'python3') -or (Test-PythonAtLeast 'python')) {
- Write-Ok "Python >= $MinPython found on PATH (used by the Claude Code plugin hooks)"
- } else {
- Write-Info "No Python >= $MinPython on PATH; installing a uv-managed Python $HookPythonVersion for the plugin hooks..."
- if (Invoke-Native 'uv' @('python', 'install', '--default', $HookPythonVersion)) {
- Write-Ok "Python $HookPythonVersion installed (python/python3 in $((& uv python dir --bin 2>$null) -join ''))"
- Write-Info 'If `python` still opens the Microsoft Store, turn off its App execution alias in Settings > Apps > Advanced app settings.'
- } else {
- Write-Warn 'Could not install a default Python; plugin hooks will skip themselves until one is on PATH. Skills keep working through uv.'
- }
- }
- # --- 4/4 setup ------------------------------------------------------------------
- Write-Step '4/4 Wiring local integrations' 'Creates config and runtime-specific files when a backend was selected.'
- if ($setupRuntime) {
- Write-Info "Running: ouroboros setup --runtime $setupRuntime --non-interactive"
- if (-not (Invoke-Native $ouroborosExe @('setup', '--runtime', $setupRuntime, '--non-interactive'))) {
- Write-Warn 'Runtime setup failed; installation is incomplete. Fix the error above and re-run setup.'
- exit $LASTEXITCODE
- }
- } else {
- Write-Info 'No backend selected; skipping runtime setup.'
- }
- # Refresh artifacts for every detected runtime (presence-gated, never touches
- # MCP registrations or config), so upgrades do not leave other hosts stale.
- Write-Info 'Refreshing runtime artifacts for detected runtimes'
- if (-not (Invoke-Native $ouroborosExe @('setup', 'refresh'))) {
- Write-Warn 'Artifact refresh skipped; run: ouroboros setup refresh'
- }
- if ($detected.ContainsKey('claude')) {
- Write-Host ''
- Write-Host ' Claude Code skills' -ForegroundColor Blue
- Write-Info 'Installing Ouroboros skills via Claude plugin marketplace...'
- Invoke-Native 'claude' @('plugin', 'marketplace', 'add', 'Q00/ouroboros') | Out-Null
- Invoke-Native 'claude' @('plugin', 'marketplace', 'update', 'ouroboros') | Out-Null
- if (Invoke-Native 'claude' @('plugin', 'install', 'ouroboros@ouroboros')) {
- # `install` is a no-op for an already-installed plugin; `update` moves it to the latest version.
- Invoke-Native 'claude' @('plugin', 'update', 'ouroboros@ouroboros') | Out-Null
- Write-Ok 'Skills installed'
- } else {
- Write-Warn 'Skills skipped. Manual install: claude plugin marketplace add Q00/ouroboros; claude plugin install ouroboros@ouroboros'
- }
- }
- Write-Host ''
- Write-Host 'Done! Ouroboros is ready.' -ForegroundColor Green
- Write-Host ''
- Write-Host 'Get started'
- Write-Info 'Open a NEW PowerShell window (PATH changes apply there), then in your AI coding agent run: > ooo interview "your idea here"'
- Write-Info 'Or from the terminal: ouroboros init start "your idea here"'
- if ($setupRuntime) { Write-Info "Current backend: $setupRuntime" }
- Write-Info "Switch backend later: ouroboros setup --runtime <$($AllRuntimes -join '|')>"
- Write-Host 'Model settings'
- Write-Info 'Inside your AI agent: > ooo config (opens in your browser)'
- Write-Info 'From this terminal: ouroboros config (full-screen TUI; use Windows Terminal, not cmd.exe)'
- Write-Host ''
- Write-Host 'Like Ouroboros? Star the repo: https://github.com/Q00/ouroboros'
- # --- Ouroboros console ------------------------------------------------------------
- # Once the install is done, start the browser console so a new user lands in a
- # guided UI. It runs in a hidden background process: the installer returns,
- # never waits on it beyond a bounded readiness check, and never fails because
- # of it. Releases without `ouroboros gui` get no console output at all.
- # Mirrors the same step at the end of scripts/install.sh.
- # -NoConsole or OUROBOROS_NO_CONSOLE=1 skips this step. The variable takes a
- # closed set of values; anything else is reported and treated as an opt-out,
- # because not starting a background server is the safe reading.
- function Test-ConsoleOptOut([bool]$Flag, [string]$Value) {
- if ($Flag) { return $true }
- $normalized = ''
- if ($Value) { $normalized = $Value.Trim().ToLowerInvariant() }
- if (@('', '0', 'false', 'no', 'off') -contains $normalized) { return $false }
- if (@('1', 'true', 'yes', 'on') -contains $normalized) { return $true }
- Write-Warn 'OUROBOROS_NO_CONSOLE has an unrecognized value (expected 1 or 0); not starting the console.'
- return $true
- }
- # `ouroboros gui --help` exits 0 only on a release that ships the console; older
- # ones fail with "No such command". Telemetry is off for the probe since it is
- # not a real use. A probe that outlives the timeout is killed and counts as no.
- function Test-ConsoleCommand([string]$Exe, [int]$TimeoutMs) {
- try {
- $info = New-Object System.Diagnostics.ProcessStartInfo
- $info.FileName = $Exe
- $info.Arguments = 'gui --help'
- $info.UseShellExecute = $false
- $info.CreateNoWindow = $true
- $info.RedirectStandardInput = $true
- $info.RedirectStandardOutput = $true
- $info.RedirectStandardError = $true
- $info.EnvironmentVariables['OUROBOROS_TELEMETRY'] = '0'
- $info.EnvironmentVariables['DO_NOT_TRACK'] = '1'
- $probe = [System.Diagnostics.Process]::Start($info)
- $probe.StandardInput.Close()
- # Drain both pipes so a chatty help screen cannot block the child.
- $null = $probe.StandardOutput.ReadToEndAsync()
- $null = $probe.StandardError.ReadToEndAsync()
- if (-not $probe.WaitForExit($TimeoutMs)) {
- # Kill is SIGKILL / TerminateProcess, which a child cannot ignore;
- # reaping it is bounded too, so the probe returns within the
- # timeout plus 2 s.
- try { $probe.Kill() } catch { }
- try { $null = $probe.WaitForExit(2000) } catch { }
- return $false
- }
- return ($probe.ExitCode -eq 0)
- } catch {
- return $false
- }
- }
- # A logon session with a desktop: services are not user-interactive, and an SSH
- # session's browser would open on this machine, not for the person connected.
- function Test-ConsoleDesktop {
- if (-not [Environment]::UserInteractive) { return $false }
- if ($env:SSH_CONNECTION -or $env:SSH_CLIENT -or $env:SSH_TTY) { return $false }
- return $true
- }
- # Turn the console's state file (~/.ouroboros/gui/server.json, written by
- # `ouroboros gui` once it listens) into the loopback URL it serves. Only a
- # well-formed JSON object counts (ConvertFrom-Json rejects trailing text), and
- # only its own top-level `host` (a loopback name) and `port` (an integer in
- # 1-65535) are read. Returns $null otherwise.
- function ConvertTo-ConsoleUrl([string]$Text) {
- if ([string]::IsNullOrWhiteSpace($Text)) { return $null }
- # ConvertFrom-Json unrolls a one-element array into its element; the
- # state must be an object itself.
- if (-not $Text.TrimStart(" `t`r`n".ToCharArray()).StartsWith('{')) { return $null }
- try { $state = ConvertFrom-Json -InputObject $Text } catch { return $null }
- if ($null -eq $state) { return $null }
- $names = @($state.PSObject.Properties | ForEach-Object { $_.Name })
- if (($names -notcontains 'port') -or ($names -notcontains 'host')) { return $null }
- $port = $state.port
- if (-not (($port -is [int]) -or ($port -is [long]))) { return $null }
- if ($port -lt 1 -or $port -gt 65535) { return $null }
- if (@('127.0.0.1', 'localhost', '0.0.0.0') -cnotcontains [string]$state.host) { return $null }
- return "http://localhost:$port/"
- }
- function Read-ConsoleState([string]$Path) {
- try { return [System.IO.File]::ReadAllText($Path) } catch { return '' }
- }
- # Start `ouroboros gui` hidden and wait at most $WaitMs for it to report its
- # address; every check in the wait is in-process, so the deadline holds. A
- # console that is already running is reused by `ouroboros gui`, which then only
- # opens the browser and exits 0. The logs get no explicit ACL: they inherit the
- # per-user %USERPROFILE%\.ouroboros\gui directory's permissions.
- function Start-ConsoleDetached([string]$Exe, [int]$WaitMs) {
- $dir = Join-Path (Join-Path $env:USERPROFILE '.ouroboros') 'gui'
- $statePath = Join-Path $dir 'server.json'
- $log = Join-Path $dir 'console.log'
- $errLog = Join-Path $dir 'console.err.log'
- try {
- New-Item -ItemType Directory -Force -Path $dir | Out-Null
- $before = Read-ConsoleState $statePath
- $process = Start-Process -FilePath $Exe -ArgumentList 'gui' -WindowStyle Hidden `
- -RedirectStandardOutput $log -RedirectStandardError $errLog -PassThru
- # Windows PowerShell 5.1 reports no ExitCode unless the handle was taken.
- $null = $process.Handle
- } catch {
- Write-Warn "The Ouroboros console did not start: $($_.Exception.Message). The installation itself is complete."
- Write-Info 'Start it any time with: ouroboros gui'
- return
- }
- $url = $null
- $exitCode = $null
- $last = $before
- $deadline = [DateTime]::UtcNow.AddMilliseconds($WaitMs)
- while ($true) {
- if ($process.HasExited) { $exitCode = $process.ExitCode; break }
- $current = Read-ConsoleState $statePath
- if ($current -and ($current -ne $last)) {
- $last = $current
- $url = ConvertTo-ConsoleUrl $current
- if ($url) { break }
- }
- if ([DateTime]::UtcNow -ge $deadline) { break }
- Start-Sleep -Milliseconds 100
- }
- if ($url) {
- Write-Ok "The Ouroboros console is running in the background at $url"
- Write-Info 'It opens in your browser. Stop it with "Stop console" at the bottom of its sidebar.'
- Write-Info 'Reopen it any time with: ouroboros gui'
- Write-Info "Log: $log"
- } elseif ($exitCode -eq 0) {
- $url = ConvertTo-ConsoleUrl (Read-ConsoleState $statePath)
- if ($url) {
- Write-Ok "The Ouroboros console is already running at $url; opened it in your browser."
- Write-Info 'Reopen it any time with: ouroboros gui'
- } else {
- Write-Warn 'Could not confirm that the Ouroboros console started.'
- Write-Info "Log: $log"
- Write-Info 'Start it any time with: ouroboros gui'
- }
- } elseif ($null -ne $exitCode) {
- Write-Warn "The Ouroboros console did not start (exit $exitCode). The installation itself is complete."
- Write-Info "Log: $errLog"
- Write-Info 'Start it any time with: ouroboros gui'
- } else {
- Write-Info 'The Ouroboros console is still starting in the background; it opens in your browser when ready.'
- Write-Info 'Stop it with "Stop console" at the bottom of its sidebar. Reopen it any time with: ouroboros gui'
- Write-Info "Log: $log"
- }
- }
- function Invoke-ConsoleAfterInstall([string]$Exe, [bool]$OptOut) {
- if ($OptOut -or -not $Exe) { return }
- if (-not (Test-ConsoleCommand $Exe 15000)) { return }
- if ((Test-Path Env:CI) -or -not (Test-Interactive) -or -not (Test-ConsoleDesktop)) {
- Write-Host ''
- Write-Host 'Next: open the Ouroboros console in your browser with: ouroboros gui'
- return
- }
- Write-Host ''
- Write-Host ' Ouroboros console' -ForegroundColor Blue
- Start-ConsoleDetached $Exe 20000
- }
- try {
- Invoke-ConsoleAfterInstall $ouroborosExe (Test-ConsoleOptOut ([bool]$NoConsole) $env:OUROBOROS_NO_CONSOLE)
- } catch {
- Write-Warn "Could not start the Ouroboros console: $($_.Exception.Message)"
- Write-Info 'Start it any time with: ouroboros gui'
- }
scripts/install.sh · Bundled script · 1,917 lines · 1 finding marked
- #!/bin/bash
- # Ouroboros installer — auto-detects runtime and installs accordingly.
- # Usage: curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 3 on GitHub
- #
- # Runtime selection (first match wins):
- # 1. OUROBOROS_INSTALL_RUNTIME env var
- # (claude|claude-sdk|claude-cli|codex|opencode|hermes|gemini|goose|kiro|copilot|pi|gjc|omp|all)
- # 2. Existing ~/.ouroboros/config.yaml runtime — preserved on upgrade
- # unless OUROBOROS_INSTALL_RECONFIGURE=1 (or --reconfigure flag) is set.
- # 3. Interactive prompt when stdin is a TTY.
- # 4. Auto-detect single CLI on PATH; default to claude in pipe mode.
- #
- # When no usable installer is present, uv is fetched from astral.sh because it
- # carries its own Python. Set OUROBOROS_INSTALL_BOOTSTRAP_UV=0 to decline that
- # and get installation instructions instead.
- #
- # Flags: --runtime <name>, --reconfigure, --no-console
- # (through a pipe: curl -fsSL <url> | bash -s -- --no-console)
- #
- # Console: when the installed release ships `ouroboros gui` and the install
- # finishes in an interactive desktop session (a reachable terminal, no CI
- # variable, macOS or a Linux/WSL display or WSL browser bridge, and not an
- # SSH session without a display), the Ouroboros console starts in the
- # background and opens in the browser. Otherwise only the command is printed.
- # Skip it with --no-console or OUROBOROS_NO_CONSOLE=1.
- set -euo pipefail
- PACKAGE_NAME="ouroboros-ai"
- CLICK_SPEC="click>=8.1.0,<9.0.0"
- MIN_PYTHON="3.12"
- DEFAULT_PYTHON_SPEC=">=3.12"
- LITELLM_PYTHON_SPEC=">=3.12,<3.14"
- IS_LOCAL=false
- RECONFIGURE="${OUROBOROS_INSTALL_RECONFIGURE:-}"
- EXPLICIT_RUNTIME="${OUROBOROS_INSTALL_RUNTIME:-}"
- BOOTSTRAP_UV="${OUROBOROS_INSTALL_BOOTSTRAP_UV:-1}"
- NO_CONSOLE_FLAG=""
- if [ -z "${NO_COLOR:-}" ] && { [ -t 1 ] || [ -n "${FORCE_COLOR:-}" ]; } && { [ "${TERM:-}" != "dumb" ] || [ -n "${FORCE_COLOR:-}" ]; }; then
- BOLD="$(printf '\033[1m')"
- DIM="$(printf '\033[2m')"
- GREEN="$(printf '\033[1;32m')"
- YELLOW="$(printf '\033[1;33m')"
- BLUE="$(printf '\033[1;34m')"
- CYAN="$(printf '\033[1;36m')"
- MAGENTA="$(printf '\033[1;35m')"
- RED="$(printf '\033[1;31m')"
- RESET="$(printf '\033[0m')"
- else
- BOLD=""
- DIM=""
- GREEN=""
- YELLOW=""
- BLUE=""
- CYAN=""
- MAGENTA=""
- RED=""
- RESET=""
- fi
- _say() {
- printf '%s\n' "$*"
- }
- _blank() {
- printf '\n'
- }
- _banner() {
- _say "${MAGENTA}╭────────────────────────────────────────────╮${RESET}"
- _say "${MAGENTA}│${RESET} ${BOLD}${CYAN}Ouroboros installer${RESET} ${MAGENTA}│${RESET}"
- _say "${MAGENTA}│${RESET} ${DIM}Specification-first AI development${RESET} ${MAGENTA}│${RESET}"
- _say "${MAGENTA}╰────────────────────────────────────────────╯${RESET}"
- _say "${DIM}Installs the CLI, chooses an agent backend, and wires up local skills.${RESET}"
- }
- _step() {
- _blank
- _say "${BLUE}◆${RESET} ${BOLD}$1${RESET}"
- if [ "${2:-}" != "" ]; then
- _say " ${DIM}$2${RESET}"
- fi
- }
- _ok() {
- _say " ${GREEN}✓${RESET} $1"
- }
- _warn() {
- _say " ${YELLOW}!${RESET} $1"
- }
- _err() {
- _say " ${RED}✗${RESET} $1"
- }
- _info() {
- _say " ${DIM}•${RESET} $1"
- }
- # Quote a string as one shell word using ASCII only, independent of the host
- # bash version. `printf %q` cannot be used here: bash 3.2 (the macOS system
- # bash) escapes only the bytes of a multibyte character that it happens to
- # consider unsafe, leaving the rest raw, which emits invalid UTF-8 and lets a
- # profile name smuggle RTL overrides or ANSI escapes into the terminal. This
- # escapes every byte outside a conservative safe set, so the output is always
- # printable ASCII and always re-reads as the original name.
- _shell_quote() {
- local _sq_in=$1 _sq_out='' _sq_char _sq_code _sq_i _sq_len
- local LC_ALL=C
- case $_sq_in in
- '') printf "\$''"; return ;;
- *[!A-Za-z0-9_.,:/@%+=-]*) ;;
- *) printf '%s' "$_sq_in"; return ;;
- esac
- _sq_len=${#_sq_in}
- _sq_i=0
- while [ "$_sq_i" -lt "$_sq_len" ]; do
- _sq_char=${_sq_in:_sq_i:1}
- case $_sq_char in
- [A-Za-z0-9_.,:/@%+=-]) _sq_out=$_sq_out$_sq_char ;;
- *)
- # `printf "'c"` yields a signed value, so bytes >= 0x80 arrive
- # negative; mask them back into the 0-255 range before formatting.
- printf -v _sq_code '%d' "'$_sq_char"
- printf -v _sq_code '%03o' "$((_sq_code & 255))"
- _sq_out=$_sq_out\\$_sq_code
- ;;
- esac
- _sq_i=$((_sq_i + 1))
- done
- printf '%s' "\$'$_sq_out'"
- }
- _choice() {
- printf ' %b[%s]%b %-8s %s\n' "$BOLD" "$1" "$RESET" "$2" "$3"
- }
- _prompt() {
- printf '%b' "${BOLD}$1${RESET}"
- }
- # --- Anonymous install telemetry (PostHog) ---------------------------------
- # Same privacy contract as the CLI (see TELEMETRY.md): random UUID, no PII,
- # no code/paths. Disable with DO_NOT_TRACK=1, OUROBOROS_TELEMETRY=0, or
- # telemetry.enabled: false in ~/.ouroboros/config.yaml.
- # The API key is a public write-only PostHog project key.
- # TELEMETRY.md declares ~/.ouroboros/.env a trusted persistent control
- # source; the application loader applies it at import via python-dotenv's
- # dotenv_values(), which resolves a key repeated in the file to its LAST
- # occurrence. This standalone installer must honor the same telemetry keys
- # before any notice or capture, so a persisted opt-out or destination
- # override there holds during install -- including matching that same
- # last-wins resolution for an internally-duplicated key, so the two loaders
- # never disagree about a single file's meaning. Only the four allowlisted
- # telemetry keys are read, and an already-set real process environment
- # value always wins over the file, no matter how many times a key repeats
- # in it (mirrors config/loader.py).
- #
- # Grammar covered exactly like dotenv_values(): bare/export-prefixed
- # bindings, single- and double-quoted values (with an inline `# comment`
- # after a closing quote), one layer of matching quotes around the KEY
- # itself, and last-wins on duplicate keys. Grammar this single-line shell
- # reader genuinely cannot follow -- a physically MULTILINE quoted value, or
- # an ESCAPE sequence inside a double-quoted value -- is never guessed at:
- # `_TELEMETRY_USER_ENV_AMBIGUOUS` is set instead, and `_telemetry_enabled`
- # treats that as an unconditional opt-out. A real parse error dotenv itself
- # also rejects (trailing garbage after a legitimate closing quote) stays a
- # plain skip -- both loaders already agree there's nothing to trust there.
- _telemetry_load_user_env() {
- local f="$HOME/.ouroboros/.env" line key value rest after trailing
- local preset_var parsed_var
- local preset_DO_NOT_TRACK preset_OUROBOROS_TELEMETRY
- local preset_OUROBOROS_POSTHOG_API_KEY preset_OUROBOROS_POSTHOG_HOST
- local parsed_DO_NOT_TRACK="" parsed_OUROBOROS_TELEMETRY=""
- local parsed_OUROBOROS_POSTHOG_API_KEY="" parsed_OUROBOROS_POSTHOG_HOST=""
- { [ -f "$f" ] && [ -r "$f" ]; } || return 0
- # Phase 1: snapshot which of the four allowlisted keys are already set in
- # the REAL process environment, before the trusted file is consulted at
- # all -- this is the one precedence check that must survive unchanged.
- for key in DO_NOT_TRACK OUROBOROS_TELEMETRY OUROBOROS_POSTHOG_API_KEY OUROBOROS_POSTHOG_HOST; do
- if eval "[ -n \"\${$key+x}\" ]"; then
- printf -v "preset_$key" '%s' true
- else
- printf -v "preset_$key" '%s' false
- fi
- done
- while IFS= read -r line || [ -n "$line" ]; do
- line="${line#"${line%%[![:space:]]*}"}"
- case "$line" in ''|'#'*) continue ;; esac
- case "$line" in
- export[[:space:]]*)
- line="${line#export}"
- line="${line#"${line%%[![:space:]]*}"}"
- ;;
- esac
- case "$line" in *=*) ;; *) continue ;; esac
- key="${line%%=*}"
- key="${key%"${key##*[![:space:]]}"}"
- # python-dotenv also accepts a key wrapped in one layer of matching
- # quotes (`'OUROBOROS_TELEMETRY'=0`, `"DO_NOT_TRACK"=1`) -- strip it
- # before the allowlist check so those parse identically to the bare
- # form. A key that only has ONE side quoted (no matching closing quote)
- # falls through unchanged and correctly misses the allowlist below,
- # same as today.
- case "$key" in
- \"*\")
- key="${key#\"}"
- key="${key%\"}"
- ;;
- \'*\')
- key="${key#\'}"
- key="${key%\'}"
- ;;
- esac
- case "$key" in
- DO_NOT_TRACK|OUROBOROS_TELEMETRY|OUROBOROS_POSTHOG_API_KEY|OUROBOROS_POSTHOG_HOST) ;;
- *) continue ;;
- esac
- value="${line#*=}"
- value="${value#"${value%%[![:space:]]*}"}"
- case "$value" in
- \"*)
- # A quoted value's content runs to the FIRST matching quote; only
- # trailing whitespace and/or a `# comment` may follow it (matches
- # python-dotenv). This is what makes a normal persisted opt-out like
- # `OUROBOROS_TELEMETRY="0" # persisted opt-out` parse to "0" instead
- # of falling into the unquoted branch below and keeping its quotes.
- # A missing closing quote and trailing garbage after a real closing
- # quote are NOT the same situation in dotenv, even though both look
- # like "unparseable" to a single-line shell reader:
- # - trailing garbage after a legitimate closing quote (e.g.
- # `OUROBOROS_TELEMETRY="0"x`) IS a parse error in python-dotenv
- # too -- both sides skip the binding, no disagreement possible.
- # - a MISSING closing quote is not an error to dotenv at all: it
- # is the start of a value that continues reading subsequent
- # PHYSICAL LINES until a closing quote is found (a genuinely
- # multiline value), which this single-line reader cannot
- # follow. Silently skipping here left telemetry ON while the
- # application resolved a real (stripped) value -- fail closed
- # instead, same posture as the escape-bearing case below.
- rest="${value#\"}"
- case "$rest" in
- *\"*) ;;
- *) _TELEMETRY_USER_ENV_AMBIGUOUS=1; continue ;;
- esac
- after="${rest#*\"}"
- trailing="${after#"${after%%[![:space:]]*}"}"
- case "$trailing" in
- ''|'#'*) ;;
- *) continue ;;
- esac
- value="${rest%%\"*}"
- # dotenv_values() decodes backslash escapes inside a double-quoted
- # value (e.g. the two source characters `\n` become an actual
- # newline); this shell parser copies them literally. A hand-rolled
- # parser will never chase python-dotenv's full escape grammar
- # (`\"` alone would need real state tracking), so rather than guess
- # and risk agreeing with neither interpretation, refuse to trust
- # THIS occurrence's value at all and force telemetry off for the
- # whole run: under-collecting on an ambiguous value is always safe,
- # over-collecting is the actual privacy violation. This is
- # deliberately asymmetric -- an ambiguous value that LOOKS like an
- # enable (e.g. `"1\n"`) also disables the installer run, diverging
- # from the application only in the safe direction.
- case "$value" in
- *\\*) _TELEMETRY_USER_ENV_AMBIGUOUS=1; continue ;;
- esac
- ;;
- \'*)
- # Single-quoted values are literal (no escape decoding, matching
- # today's handling already), but a missing closing quote has the
- # SAME multiline-continuation meaning in dotenv as the double-quote
- # case above -- fail closed for the same reason, not a plain skip.
- rest="${value#\'}"
- case "$rest" in
- *\'*) ;;
- *) _TELEMETRY_USER_ENV_AMBIGUOUS=1; continue ;;
- esac
- after="${rest#*\'}"
- trailing="${after#"${after%%[![:space:]]*}"}"
- case "$trailing" in
- ''|'#'*) ;;
- *) continue ;;
- esac
- value="${rest%%\'*}"
- ;;
- *)
- # Unquoted values follow dotenv grammar: an inline ` # comment` is
- # not part of the value. Dropping it here matters for opt-outs --
- # `OUROBOROS_TELEMETRY=0 # off` must parse as "0", not fail the
- # flag match and silently keep collection on.
- value="${value%%[[:space:]]#*}"
- value="${value%"${value##*[![:space:]]}"}"
- ;;
- esac
- [ -n "$value" ] || continue
- # Phase 2: accumulate into a per-key holding variable rather than
- # exporting immediately -- overwriting on every valid occurrence gives
- # LAST-wins semantics for a key duplicated WITHIN the trusted file,
- # matching dotenv_values(). The old per-line "export, then skip if
- # already set" approach silently flipped this to first-wins: once the
- # first occurrence exported the variable, the same `${key+x}` guard
- # would already be true for every later occurrence in THIS SAME file
- # too, blocking them even though none of them are the real process env
- # this guard exists to protect.
- printf -v "parsed_$key" '%s' "$value"
- done < "$f"
- # Phase 3: export each key's last-parsed-from-file value, but ONLY if it
- # was not already present in the real process environment (phase 1) --
- # preserving real process-env precedence while now resolving duplicates
- # inside the file itself with last-wins instead of first-wins. An empty
- # `parsed_*` here means no occurrence in the file ever produced a value
- # worth keeping (every occurrence, if any, failed to parse or was empty).
- for key in DO_NOT_TRACK OUROBOROS_TELEMETRY OUROBOROS_POSTHOG_API_KEY OUROBOROS_POSTHOG_HOST; do
- preset_var="preset_$key"
- parsed_var="parsed_$key"
- if [ "${!preset_var}" = false ] && [ -n "${!parsed_var}" ]; then
- export "$key=${!parsed_var}"
- fi
- done
- }
- _telemetry_load_user_env
- PH_API_KEY="${OUROBOROS_POSTHOG_API_KEY:-phc_mSoetD4ExLDDCi3vNua635NhwRTgHfRaCG9WYNKmrvv5}"
- PH_HOST="${OUROBOROS_POSTHOG_HOST:-https://us.i.posthog.com}"
- _telemetry_config_allows() {
- local f="$HOME/.ouroboros/config.yaml" script_path script_dir source_root=""
- local python_candidate ouroboros_cmd shebang status
- # `-e` is false for a dangling symlink. That is invalid persisted state,
- # not a genuinely absent config, so keep it on the fail-closed path.
- [ -e "$f" ] || [ -L "$f" ] || return 0
- [ -r "$f" ] || return 1
- # Match the application resolver: parse the complete YAML document and
- # validate every known field before trusting telemetry.enabled. A partial
- # text parser can accept telemetry.enabled=true while overlooking malformed
- # YAML or an invalid unrelated field. Existing configuration therefore
- # requires a Python environment with Ouroboros' real schema available;
- # otherwise collection fails closed. A genuinely absent config retains the
- # documented default-on behavior after the notice below.
- # `curl | bash` has no sourced file path; nounset must not break this
- # optional local-source optimization.
- script_path="${BASH_SOURCE[0]-}"
- script_dir=""
- if [ -n "$script_path" ]; then
- script_dir=$(CDPATH='' cd -- "$(dirname -- "$script_path")" 2>/dev/null && pwd) || true
- fi
- if [ -n "$script_dir" ] && [ -f "$script_dir/../src/ouroboros/config/models.py" ]; then
- source_root=$(CDPATH='' cd -- "$script_dir/../src" 2>/dev/null && pwd) || true
- fi
- _telemetry_validate_config_with_python() {
- local interpreter="$1"
- "$interpreter" -I - "$f" "$source_root" <<'PY'
- import sys
- config_path, source_root = sys.argv[1:]
- if source_root:
- sys.path.insert(0, source_root)
- try:
- import yaml
- from ouroboros.config.models import OuroborosConfig
- except Exception:
- raise SystemExit(2)
- try:
- with open(config_path, encoding="utf-8") as config_file:
- raw = yaml.safe_load(config_file)
- config = OuroborosConfig.model_validate({} if raw is None else raw)
- except Exception:
- raise SystemExit(1)
- # Older installed schemas may validate without a telemetry field. Fail closed
- # instead of dereferencing an attribute the schema does not have.
- enabled = getattr(getattr(config, "telemetry", None), "enabled", False)
- raise SystemExit(0 if enabled is True else 1)
- PY
- }
- for python_candidate in python3 python; do
- python_candidate=$(command -v "$python_candidate" 2>/dev/null || true)
- [ -n "$python_candidate" ] || continue
- if _telemetry_validate_config_with_python "$python_candidate"; then
- unset -f _telemetry_validate_config_with_python
- return 0
- else
- status=$?
- if [ "$status" -ne 2 ]; then
- unset -f _telemetry_validate_config_with_python
- return 1
- fi
- fi
- done
- # uv/pipx entry points carry their environment's Python interpreter in the
- # shebang. It may have the schema when the system Python does not.
- ouroboros_cmd=$(command -v ouroboros 2>/dev/null || true)
- if [ -n "$ouroboros_cmd" ] && [ -r "$ouroboros_cmd" ]; then
- shebang=$(head -n 1 "$ouroboros_cmd" 2>/dev/null || true)
- case "$shebang" in
- '#!'/*)
- python_candidate=${shebang#'#!'}
- case "$python_candidate" in
- *' '*) ;;
- *)
- if [ -x "$python_candidate" ]; then
- if _telemetry_validate_config_with_python "$python_candidate"; then
- unset -f _telemetry_validate_config_with_python
- return 0
- fi
- fi
- ;;
- esac
- ;;
- esac
- fi
- unset -f _telemetry_validate_config_with_python
- return 1
- }
- _telemetry_enabled() {
- [ -n "$PH_API_KEY" ] || return 1
- # Set by _telemetry_load_user_env when a trusted-file value couldn't be
- # parsed unambiguously (an escape-bearing double-quoted value) -- an
- # opt-out this installer cannot resolve is treated as an opt-out, not
- # ignored. Any one disabling control wins, matching every other flag here.
- [ -z "${_TELEMETRY_USER_ENV_AMBIGUOUS:-}" ] || return 1
- local dnt oel
- # Lowercase and trim each flag before matching so `OFF`, `Yes`, `TRUE`,
- # or values with stray whitespace are recognized the same as their
- # canonical lowercase forms (mirrors config/loader.py's `.strip().lower()`).
- dnt=$(printf '%s' "${DO_NOT_TRACK:-}" | tr '[:upper:]' '[:lower:]')
- dnt="${dnt#"${dnt%%[![:space:]]*}"}"
- dnt="${dnt%"${dnt##*[![:space:]]}"}"
- case "$dnt" in 1|true|on|yes) return 1 ;; esac
- oel=$(printf '%s' "${OUROBOROS_TELEMETRY:-}" | tr '[:upper:]' '[:lower:]')
- oel="${oel#"${oel%%[![:space:]]*}"}"
- oel="${oel%"${oel##*[![:space:]]}"}"
- case "$oel" in 0|false|off|no) return 1 ;; esac
- # OUROBOROS_TELEMETRY=1 is never an override: persisted opt-out and
- # malformed configuration stay authoritative (TELEMETRY.md: any one
- # disabling control wins), matching the application resolver.
- _telemetry_config_allows || return 1
- command -v curl &>/dev/null || return 1
- return 0
- }
- _telemetry_distinct_id() {
- local f="$HOME/.ouroboros/telemetry.json" id="" winner_id="" tmp file_existed=false lockdir wait_i
- local salvage_id=""
- local uuid_re='^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
- # Four nested helpers, all `unset -f` below so extracting just this outer
- # function's source -- e.g. for an isolated concurrency-test driver --
- # carries them along automatically instead of leaving a dangling
- # reference:
- #
- # _telemetry_extract_uuid -- LENIENT, TEXT-ONLY. Prints the id,
- # canonicalized to lowercase, whenever a sed match ANYWHERE in the raw
- # text looks UUID-shaped -- ignorant of JSON structure entirely. This is
- # only correct for genuinely unparseable text (telemetry.py salvages the
- # same way there, via a raw-text regex): once a document IS valid JSON,
- # a sed match found "anywhere" could be nested inside another object, or
- # the first of several duplicate top-level keys, and must NOT be trusted
- # -- see `_telemetry_read_state`.
- #
- # _telemetry_read_state -- the structural source of truth. Requires
- # python3 (a soft dependency elsewhere in this installer too). Parses
- # the file as JSON and looks at the TOP-LEVEL `distinct_id` field only
- # -- Python's own json.load naturally resolves duplicate keys to the
- # LAST occurrence, matching telemetry.py's loader exactly, and a value
- # nested inside another object is correctly invisible to a plain
- # `data.get(...)`. Prints one of: `CANONICAL:<id>` (top-level, pattern-
- # valid, already lowercase -- fully valid, no repair needed),
- # `REPAIR:<id>` (top-level, pattern-valid, wrong case -- a real identity
- # worth salvaging, canonicalized), `INVALID` (valid JSON, but no usable
- # top-level id -- missing, non-string, non-UUID, or only present nested
- # -- telemetry.py does NOT salvage from a valid-but-wrong-shaped
- # document, only from unparseable text, so this must NOT fall through to
- # the lenient text search), `MALFORMED` (not valid JSON at all -- the
- # lenient, text-only salvage path legitimately applies here), or
- # `NO_PYTHON3` when python3 isn't on PATH -- without a JSON parser, pure
- # shell cannot tell top-level from nested or resolve duplicate keys, so
- # this is a documented best-effort gap.
- #
- # _telemetry_canonical_id -- STRICT adopt-without-repair check ("has a
- # real repair already landed on disk"): CANONICAL only when python3 is
- # present; falls back to the old pattern+case-only sed check (no
- # structural awareness) when it is not.
- #
- # _telemetry_salvage_candidate -- the repair candidate getter: reuses a
- # REPAIR-state top-level id or a MALFORMED-text lenient match; withholds
- # entirely on INVALID (mirrors telemetry.py: no salvage from valid JSON
- # lacking a usable top-level id); falls back to the lenient text search
- # without python3.
- _telemetry_extract_uuid() {
- local r
- r=$(sed -n 's/.*"distinct_id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$1" 2>/dev/null | head -1)
- if [[ "$r" =~ $uuid_re ]]; then
- printf '%s' "$r" | tr '[:upper:]' '[:lower:]'
- fi
- }
- _telemetry_read_state() {
- local py
- py=$(command -v python3 2>/dev/null || true)
- if [ -z "$py" ]; then
- printf 'NO_PYTHON3'
- return 0
- fi
- "$py" -c '
- import json, re, sys
- uuid_re = re.compile(
- r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
- )
- try:
- with open(sys.argv[1], encoding="utf-8") as fh:
- data = json.load(fh)
- except Exception:
- print("MALFORMED")
- else:
- value = data.get("distinct_id") if isinstance(data, dict) else None
- if isinstance(value, str) and uuid_re.match(value):
- lowered = value.lower()
- print(("CANONICAL:" if lowered == value else "REPAIR:") + lowered)
- else:
- print("INVALID")
- ' "$1" 2>/dev/null
- }
- _telemetry_canonical_id() {
- local state r
- state=$(_telemetry_read_state "$1")
- case "$state" in
- CANONICAL:*)
- printf '%s' "${state#CANONICAL:}"
- ;;
- NO_PYTHON3)
- r=$(sed -n 's/.*"distinct_id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$1" 2>/dev/null | head -1)
- [[ "$r" =~ $uuid_re ]] || return 0
- [ "$r" = "$(printf '%s' "$r" | tr '[:upper:]' '[:lower:]')" ] || return 0
- printf '%s' "$r"
- ;;
- *) ;; # REPAIR / INVALID / MALFORMED: not yet fully valid
- esac
- }
- _telemetry_salvage_candidate() {
- local state
- state=$(_telemetry_read_state "$1")
- case "$state" in
- CANONICAL:*) printf '%s' "${state#CANONICAL:}" ;;
- REPAIR:*) printf '%s' "${state#REPAIR:}" ;;
- INVALID) ;; # valid JSON, no usable top-level id -- no salvage
- *) _telemetry_extract_uuid "$1" ;; # MALFORMED or NO_PYTHON3
- esac
- }
- if [ -f "$f" ]; then
- file_existed=true
- id=$(_telemetry_canonical_id "$f")
- if [ -z "$id" ]; then
- # Not already fully valid. Keep a real (top-level, or -- only for
- # genuinely unparseable text -- lenient-text) id as a SALVAGE
- # candidate rather than discarding it for a fresh mint; an id that
- # isn't usable at all (no field, a non-UUID value, or only nested
- # inside otherwise-valid JSON) leaves `salvage_id` empty and is
- # treated as fully corrupt below.
- salvage_id=$(_telemetry_salvage_candidate "$f")
- fi
- fi
- if [ -z "$id" ]; then
- if [ -n "$salvage_id" ]; then
- id="$salvage_id"
- elif command -v uuidgen &>/dev/null; then
- id=$(uuidgen | tr '[:upper:]' '[:lower:]')
- elif command -v python3 &>/dev/null; then
- id=$(python3 -c "import uuid; print(uuid.uuid4())" 2>/dev/null || true)
- fi
- if [ -z "$id" ]; then
- unset -f _telemetry_extract_uuid _telemetry_read_state _telemetry_canonical_id _telemetry_salvage_candidate
- return 1
- fi
- if ! mkdir -p "$HOME/.ouroboros" 2>/dev/null; then
- unset -f _telemetry_extract_uuid _telemetry_read_state _telemetry_canonical_id _telemetry_salvage_candidate
- return 1
- fi
- # Publish the (fresh or salvaged) identity via a same-directory temp
- # file, then re-read whatever actually landed on disk instead of
- # trusting our own candidate:
- # - `$f` absent: publish with `ln` (hard link) — atomic
- # create-if-not-exists, it fails if a concurrently-starting process
- # (e.g. `ouroboros setup` in step 4, or another MCP session) already
- # won, so nothing here is ever clobbered.
- # - `$f` present but invalid (unparseable, no distinct_id, a non-UUID
- # value, mismatched case, or malformed JSON around an otherwise
- # salvageable id): `ln`/an unconditional `mv` are not enough here —
- # every racing process would each mint or salvage independently and
- # the last `mv` would silently win, so processes that already
- # emitted events under their own reading would disagree with what
- # ends up persisted. Exactly one process must own the repair.
- # `$f.repair.lock` is the SAME lock name telemetry.py's
- # `_repair_state` uses (it creates the path with `O_CREAT|O_EXCL` as
- # a file; here `mkdir` is the atomic create-if-not-exists primitive).
- # Both primitives only check whether *something* already exists at
- # that path, regardless of type, so a shell `mkdir` and a Python
- # `O_EXCL` file open correctly exclude each other at the same path
- # (verified on macOS: whichever side creates the path first, the
- # other's create call fails with EEXIST).
- # Either way, every process then adopts whichever valid, canonical
- # distinct_id survives in `$f` (mirrors telemetry.py's
- # `_publish_new_state` / `_repair_state`, which apply the same
- # UUID-validate-canonicalize-and-salvage rules).
- tmp="$f.$$.tmp"
- # Grouped so an unwritable `$HOME/.ouroboros` (read-only dir, e.g.) is
- # silent: a shell redirection's own open failure prints to the *current*
- # stderr before the trailing `2>/dev/null` on this line ever takes
- # effect, unlike an external command's (mv/ln/mkdir below) own error
- # output, which a trailing `2>/dev/null` does catch.
- { printf '{"distinct_id": "%s", "created_at": "%s", "notice_shown": false}\n' \
- "$id" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$tmp"; } 2>/dev/null || true
- if [ "$file_existed" = true ]; then
- lockdir="$f.repair.lock"
- if mkdir "$lockdir" 2>/dev/null; then
- # WINNER: re-validate under the lock -- another process may have
- # repaired the file (to a valid id) between our first read and
- # acquiring it.
- winner_id=$(_telemetry_canonical_id "$f")
- [ -n "$winner_id" ] || mv "$tmp" "$f" 2>/dev/null || true
- rmdir "$lockdir" 2>/dev/null || true
- else
- # LOSER: someone else owns the repair (or a stale lock). Wait,
- # bounded, for a valid id to land.
- winner_id=""
- wait_i=0
- while [ "$wait_i" -lt 10 ]; do
- sleep 0.05
- winner_id=$(_telemetry_canonical_id "$f")
- [ -n "$winner_id" ] && break
- wait_i=$((wait_i + 1))
- done
- if [ -z "$winner_id" ]; then
- # Lock never cleared (stale, from a killed process) -- take over
- # the replace ourselves rather than waiting forever, accepting
- # the tiny remaining race.
- mv "$tmp" "$f" 2>/dev/null || true
- rmdir "$lockdir" 2>/dev/null || rm -f "$lockdir" 2>/dev/null || true
- fi
- fi
- else
- ln "$tmp" "$f" 2>/dev/null || true
- fi
- rm -f "$tmp" 2>/dev/null || true
- # Fail-closed reread: if neither our own publish/repair attempt nor
- # anyone else's landed a usable id on disk (e.g. `$HOME/.ouroboros` is
- # unwritable/read-only, so every `mv`/`ln` above silently failed),
- # printing the local candidate would emit under an ephemeral,
- # never-persisted identity that no other process -- or a later run of
- # this same one -- could ever reproduce, permanently fragmenting
- # identity instead of just skipping a run's telemetry. Drop instead
- # (callers already treat a nonzero return as "skip telemetry"), matching
- # telemetry.py's stable-identity contract. Deliberately
- # `_telemetry_salvage_candidate`, not the strict `_telemetry_canonical_id`:
- # this is a "is there now a real, reusable identity at all" check, not a
- # "was it perfectly repaired" check -- a top-level id already sitting in
- # a file we couldn't write to is still a stable value every future read
- # of that same file will keep finding, so it's the best available
- # anchor, not a reason to go fully ephemeral. It still withholds on a
- # valid-JSON `INVALID` state (no usable top-level id) exactly as the
- # top-of-function salvage check does, so this reread can never resurrect
- # a nested-only or otherwise-unusable value that was correctly rejected
- # earlier in this same call.
- winner_id=$(_telemetry_salvage_candidate "$f")
- if [ -z "$winner_id" ]; then
- unset -f _telemetry_extract_uuid _telemetry_read_state _telemetry_canonical_id _telemetry_salvage_candidate
- return 1
- fi
- id="$winner_id"
- fi
- unset -f _telemetry_extract_uuid _telemetry_read_state _telemetry_canonical_id _telemetry_salvage_candidate
- printf '%s' "$id"
- }
- _telemetry_notice() {
- _telemetry_enabled || return 0
- local f="$HOME/.ouroboros/telemetry.json" tmp id py already_shown
- # Skip only when the persisted state is valid JSON, a dict, and its
- # TOP-LEVEL `notice_shown` is the literal boolean `true` -- mirrors the
- # identity reader's structural approach above (and telemetry.py's own
- # check). Fail toward disclosure: missing, nested-only (e.g. a
- # `{"wrapper": {"notice_shown": true}}` sibling object), a string
- # "true"/"false", any other non-bool, or malformed JSON must all still
- # show the notice -- a duplicate notice is harmless, a suppressed one
- # breaks the privacy contract. Without python3 on PATH we cannot parse
- # JSON structure in pure shell, so this falls back to the old raw-text
- # grep (documented best-effort gap, matches the identity reader's
- # NO_PYTHON3 fallback).
- py=$(command -v python3 2>/dev/null || true)
- already_shown=false
- if [ -f "$f" ]; then
- if [ -n "$py" ]; then
- if "$py" -c '
- import json, sys
- try:
- with open(sys.argv[1], encoding="utf-8") as fh:
- data = json.load(fh)
- except Exception:
- sys.exit(1)
- sys.exit(0 if isinstance(data, dict) and data.get("notice_shown") is True else 1)
- ' "$f" 2>/dev/null; then
- already_shown=true
- fi
- elif grep -q '"notice_shown"[[:space:]]*:[[:space:]]*true' "$f" 2>/dev/null; then
- already_shown=true
- fi
- fi
- [ "$already_shown" = false ] || return 0
- _blank
- _say "${BOLD}Anonymous usage stats help improve Ouroboros.${RESET}"
- _info "Collects commands, versions, and success rates — never code, prompts, or paths."
- _info "Opt out: export OUROBOROS_TELEMETRY=0 | details: https://github.com/Q00/ouroboros/blob/main/TELEMETRY.md"
- # Persist the one-time notice before the first collection attempt. Failure
- # is harmless: this run was disclosed and a later run will disclose again.
- id=$(_telemetry_distinct_id) || return 0
- [ -n "$id" ] || return 0
- tmp="${f}.notice.$$"
- if [ -n "$py" ]; then
- # Structural set: parses the file, sets the TOP-LEVEL `notice_shown` to
- # the literal boolean `true`, and preserves every other field as-is.
- # Unlike the sed fallback below, this also covers a document whose
- # top-level `notice_shown` never existed in the first place (e.g. an
- # already-valid identity file that was never rewritten by the repair
- # path above) -- a blind "replace false with true" text substitution
- # has nothing to match there and would silently leave the field
- # missing forever, so a later run would show the notice again.
- if "$py" -c '
- import json, sys
- try:
- with open(sys.argv[1], encoding="utf-8") as fh:
- data = json.load(fh)
- if not isinstance(data, dict):
- raise ValueError("top-level JSON value is not an object")
- except Exception:
- sys.exit(1)
- data["notice_shown"] = True
- with open(sys.argv[2], "w", encoding="utf-8") as fh:
- json.dump(data, fh)
- fh.write("\n")
- ' "$f" "$tmp" 2>/dev/null; then
- mv "$tmp" "$f" 2>/dev/null || true
- fi
- elif sed 's/"notice_shown"[[:space:]]*:[[:space:]]*false/"notice_shown": true/' "$f" > "$tmp" 2>/dev/null; then
- mv "$tmp" "$f" 2>/dev/null || true
- fi
- rm -f "$tmp" 2>/dev/null || true
- }
- # _telemetry_ping <event> [key=value ...] — fire-and-forget, never fails.
- _telemetry_ping() {
- _telemetry_enabled || return 0
- local event="$1" id os py body kv k v props api_key_safe event_safe id_safe
- shift
- id=$(_telemetry_distinct_id) || return 0
- os=$(uname -s | tr '[:upper:]' '[:lower:]')
- [[ "$os" =~ ^[A-Za-z0-9._-]{1,32}$ ]] || os="unknown"
- py=$(command -v python3 2>/dev/null || true)
- body=""
- if [ -n "$py" ]; then
- # Structural encoding: every value is JSON-escaped by python3's real
- # encoder and passed in via argv -- never interpolated into the -c code
- # string itself -- so a hostile value (embedded quotes, backslashes,
- # control characters, an attempted `","injected":"...` payload) can
- # only ever become the STRING CONTENTS of its own declared property; it
- # can never alter the payload's structure or add an undeclared key.
- # Keys are call-site literals already, but are still whitelisted to
- # `[A-Za-z0-9_]+` defensively -- a key that fails that check is
- # dropped, never stringified into a place it could do damage.
- body=$("$py" -c '
- import json, re, sys
- key_re = re.compile(r"^[A-Za-z0-9_]+$")
- event, distinct_id, api_key, os_name = sys.argv[1:5]
- props = {"os": os_name}
- for kv in sys.argv[5:]:
- key, sep, value = kv.partition("=")
- if sep and key_re.match(key):
- props[key] = value
- print(json.dumps(
- {
- "api_key": api_key,
- "event": event,
- "distinct_id": distinct_id,
- "properties": props,
- },
- separators=(",", ":"),
- ))
- ' "$event" "$id" "$PH_API_KEY" "$os" "$@" 2>/dev/null)
- fi
- if [ -z "$body" ]; then
- # No python3 (or the structural encoder failed): sanitize every value
- # through a strict safe-token filter before string concatenation, so no
- # quote/backslash/control character can ever survive to mutate the JSON
- # structure. Every legitimate installer value (version numbers,
- # method/runtime names, yes/no flags, a canonical-lowercase distinct_id,
- # the os/arch tokens above) fits this charset losslessly; anything that
- # doesn't is stripped down to it (then length-capped) or falls back to
- # `unknown` -- best-effort, consistent with the identity/notice
- # readers' own NO_PYTHON3 fallback posture elsewhere in this file.
- props='"os":"'"$os"'"'
- for kv in "$@"; do
- k=$(printf '%s' "${kv%%=*}" | tr -cd 'A-Za-z0-9_')
- [ -n "$k" ] || continue
- v=$(printf '%s' "${kv#*=}" | tr -cd 'A-Za-z0-9._-')
- v="${v:0:64}"
- [ -n "$v" ] || v="unknown"
- props="$props,\"$k\":\"$v\""
- done
- api_key_safe=$(printf '%s' "$PH_API_KEY" | tr -cd 'A-Za-z0-9._-')
- event_safe=$(printf '%s' "$event" | tr -cd 'A-Za-z0-9._-')
- id_safe=$(printf '%s' "$id" | tr -cd 'A-Za-z0-9._-')
- body='{"api_key":"'"$api_key_safe"'","event":"'"$event_safe"'","distinct_id":"'"$id_safe"'","properties":{'"$props"'}}'
- fi
- curl -fsS -m 4 -X POST "$PH_HOST/capture/" -H 'Content-Type: application/json' \
- -d "$body" \
- >/dev/null 2>&1 &
- return 0
- }
- # ---------------------------------------------------------------------------
- # Parse simple flags: --reconfigure, --runtime <name>, --no-console
- while [ $# -gt 0 ]; do
- case "$1" in
- --reconfigure)
- RECONFIGURE="1"
- shift
- ;;
- --no-console)
- NO_CONSOLE_FLAG="1"
- shift
- ;;
- --runtime)
- EXPLICIT_RUNTIME="${2:-}"
- shift 2
- ;;
- --runtime=*)
- EXPLICIT_RUNTIME="${1#--runtime=}"
- shift
- ;;
- *)
- shift
- ;;
- esac
- done
- # Override PACKAGE_NAME if running inside the repository clone
- if [ -f "pyproject.toml" ] && grep -q "name = \"ouroboros-ai\"" pyproject.toml; then
- PACKAGE_NAME="."
- IS_LOCAL=true
- elif [ -f "$(dirname "$0")/../pyproject.toml" ] && grep -q "name = \"ouroboros-ai\"" "$(dirname "$0")/../pyproject.toml"; then
- PACKAGE_NAME="$(dirname "$0")/.."
- IS_LOCAL=true
- fi
- # Auto-detect: if PyPI's info.version response is a pre-release, allow
- # pre-releases. On lookup/parsing failure, stay stable-only.
- PRE_FLAG=""
- if [ "$IS_LOCAL" = false ] && command -v curl &>/dev/null; then
- LATEST=$(curl -fsSL "https://pypi.org/pypi/${PACKAGE_NAME}/json" 2>/dev/null \
- | python3 -c "import sys,json; print(json.load(sys.stdin)['info']['version'])" 2>/dev/null || true)
- if [ -n "$LATEST" ]; then
- if echo "$LATEST" | grep -qE '(a|b|rc|dev)'; then
- PRE_FLAG="yes"
- fi
- fi
- fi
- # Closed install-channel vocabulary. Unknown values may contain private slugs,
- # customer names, or account identifiers, so they always fold to `direct`.
- case "${OUROBOROS_INSTALL_REF:-direct}" in
- direct|readme|readme-hero|readme-ko|readme-hero-ko|readme-zh|readme-hero-zh|docs-getting-started)
- INSTALL_REF="${OUROBOROS_INSTALL_REF:-direct}"
- ;;
- *) INSTALL_REF="direct" ;;
- esac
- _banner
- _telemetry_notice
- # Installs are rare, so install_started needs no daily dedupe: paired with
- # install_completed it measures install drop-off by version and ref.
- _telemetry_ping install_started "version=${LATEST:-unknown}" "ref=$INSTALL_REF"
- # 1. Detect installer: uv > pipx > pip (determines Python requirement)
- HAS_UV=false
- HAS_PIPX=false
- PYTHON=""
- _step "1/4 Checking Python tooling" "Prefer uv, then pipx, then pip. uv is installed when none of them can run."
- if command -v uv &>/dev/null; then
- HAS_UV=true
- _ok "uv found: $(uv --version)"
- elif command -v pipx &>/dev/null; then
- HAS_PIPX=true
- _ok "pipx found: $(pipx --version)"
- fi
- # Helper: check whether a Python executable meets the selected profile's range.
- _python_ok() {
- local cmd="$1"
- local spec="${2:-$DEFAULT_PYTHON_SPEC}"
- local ver
- ver=$("$cmd" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>/dev/null || true)
- if [ -z "$ver" ]; then
- return 1
- fi
- if [ "$(printf '%s\n' "$MIN_PYTHON" "$ver" | sort -V | head -n1)" != "$MIN_PYTHON" ]; then
- return 1
- fi
- if [ "$spec" = "$LITELLM_PYTHON_SPEC" ] && [ "$(printf '%s\n' "3.14" "$ver" | sort -V | head -n1)" = "3.14" ]; then
- return 1
- fi
- return 0
- }
- _python_requirement_message() {
- if [ "${INSTALL_PYTHON_SPEC:-$DEFAULT_PYTHON_SPEC}" = "$LITELLM_PYTHON_SPEC" ]; then
- printf 'Python %s (Ouroboros LiteLLM profiles support Python 3.12-3.13; use Python 3.13)' "$LITELLM_PYTHON_SPEC"
- else
- printf 'Python %s' "$DEFAULT_PYTHON_SPEC"
- fi
- }
- _bootstrap_uv() {
- # uv carries its own Python, so installing uv is the single move that unblocks
- # a machine with no usable interpreter — the case that previously just exited.
- # install.ps1 does the same on Windows (winget, then this script as fallback);
- # here the script is the only path needing no package manager and no
- # privileges. Everything that already works — an existing uv, or pipx with a
- # supported Python — reaches its installer before this is ever called.
- if [ "$BOOTSTRAP_UV" = "0" ]; then
- # Fetching and running an installer from the network is the one thing here
- # a caller may reasonably refuse; declining returns to the instructions.
- return 1
- fi
- if ! command -v curl >/dev/null 2>&1; then
- _err "curl is required to install uv automatically."
- return 1
- fi
- _blank
- _say "${BOLD}Installing uv${RESET} — it provides its own Python, so none needs to be installed separately."
- _info "Source: https://astral.sh/uv/install.sh"
- if ! curl -LsSf https://astral.sh/uv/install.sh | sh; then
- _err "uv installation failed."
- return 1
- fi
- # The installer does not touch the running shell's PATH, so look where it
- # actually writes before deciding it failed.
- local candidate
- for candidate in "${XDG_BIN_HOME:-}" "${CARGO_HOME:-$HOME/.cargo}/bin" "$HOME/.local/bin"; do
- if [ -n "$candidate" ] && [ -x "$candidate/uv" ]; then
- PATH="$candidate:$PATH"
- export PATH
- break
- fi
- done
- if ! command -v uv >/dev/null 2>&1; then
- _err "uv was installed but is not on PATH yet."
- _info "Open a new shell and run this installer again."
- return 1
- fi
- _ok "uv installed: $(uv --version)"
- return 0
- }
- _print_python_install_remediation() {
- _say "${BOLD}Install one of these, then run the installer again:${RESET}"
- _info "uv: pipx install uv"
- _info "uv: pip install --user uv"
- _info "uv: brew install uv"
- _info "uv: curl -LsSf https://astral.sh/uv/install.sh | sh"
- if [ "${INSTALL_PYTHON_SPEC:-$DEFAULT_PYTHON_SPEC}" = "$LITELLM_PYTHON_SPEC" ]; then
- _info "Python 3.13: https://www.python.org/downloads/"
- else
- _info "Python ${MIN_PYTHON}+: https://www.python.org/downloads/"
- fi
- }
- # 2. Detect runtimes
- _step "2/4 Choosing an agent backend" "Codex, Claude, Hermes, OpenCode, Gemini, Goose, Kiro, Copilot, Pi, GJC, and OMP are supported."
- EXTRAS=""
- RUNTIME=""
- HAS_CODEX=false
- HAS_CLAUDE=false
- HAS_HERMES=false
- HAS_OPENCODE=false
- HAS_GEMINI=false
- HAS_GOOSE=false
- HAS_KIRO=false
- HAS_COPILOT=false
- HAS_PI=false
- HAS_OMP=false
- HAS_GJC=false
- HAS_DSH=false
- DSH_PLUGIN_SPEC="github:Q00/ouroboros#main&path:integrations/dsh-plugin"
- if command -v codex &>/dev/null; then
- _ok "Codex found: $(which codex)"
- HAS_CODEX=true
- fi
- if command -v claude &>/dev/null; then
- _ok "Claude found: $(which claude)"
- HAS_CLAUDE=true
- fi
- if command -v hermes &>/dev/null; then
- _ok "Hermes found: $(which hermes)"
- HAS_HERMES=true
- fi
- if command -v opencode &>/dev/null; then
- _ok "OpenCode found: $(which opencode)"
- HAS_OPENCODE=true
- fi
- if command -v gemini &>/dev/null; then
- _ok "Gemini found: $(which gemini)"
- HAS_GEMINI=true
- fi
- if command -v goose &>/dev/null; then
- _ok "Goose found: $(which goose)"
- HAS_GOOSE=true
- fi
- if command -v kiro-cli &>/dev/null; then
- _ok "Kiro found: $(which kiro-cli)"
- HAS_KIRO=true
- fi
- if command -v copilot &>/dev/null; then
- _ok "Copilot found: $(which copilot)"
- HAS_COPILOT=true
- fi
- if command -v pi &>/dev/null; then
- _ok "Pi: $(which pi)"
- HAS_PI=true
- fi
- if command -v gjc &>/dev/null; then
- _ok "GJC found: $(which gjc)"
- HAS_GJC=true
- fi
- if command -v omp &>/dev/null; then
- _ok "OMP found: $(which omp)"
- HAS_OMP=true
- fi
- if command -v dsh &>/dev/null; then
- _ok "DeepSeek Harness found: $(which dsh)"
- HAS_DSH=true
- fi
- RUNTIME_COUNT=0
- [ "$HAS_CLAUDE" = true ] && RUNTIME_COUNT=$((RUNTIME_COUNT + 1))
- [ "$HAS_CODEX" = true ] && RUNTIME_COUNT=$((RUNTIME_COUNT + 1))
- [ "$HAS_HERMES" = true ] && RUNTIME_COUNT=$((RUNTIME_COUNT + 1))
- [ "$HAS_OPENCODE" = true ] && RUNTIME_COUNT=$((RUNTIME_COUNT + 1))
- [ "$HAS_GEMINI" = true ] && RUNTIME_COUNT=$((RUNTIME_COUNT + 1))
- [ "$HAS_GOOSE" = true ] && RUNTIME_COUNT=$((RUNTIME_COUNT + 1))
- [ "$HAS_KIRO" = true ] && RUNTIME_COUNT=$((RUNTIME_COUNT + 1))
- [ "$HAS_COPILOT" = true ] && RUNTIME_COUNT=$((RUNTIME_COUNT + 1))
- [ "$HAS_PI" = true ] && RUNTIME_COUNT=$((RUNTIME_COUNT + 1))
- [ "$HAS_GJC" = true ] && RUNTIME_COUNT=$((RUNTIME_COUNT + 1))
- [ "$HAS_OMP" = true ] && RUNTIME_COUNT=$((RUNTIME_COUNT + 1))
- # Map a runtime name to (EXTRAS, RUNTIME) pair.
- # Used after explicit/preserved runtime resolution to derive install extras.
- # Keep this table boring and explicit: agents reading this installer should be
- # able to see why Claude's SDK runtime and the modern MCP server are installed
- # in different environments. Only the explicit Claude CLI path has no SDK deps.
- _runtime_to_extras() {
- # `tui` ships with every selection so the settings GUI
- # (`ouroboros config`) works out of the box (#1414).
- case "$1" in
- claude) EXTRAS="[claude,tui]"; RUNTIME="claude" ;;
- claude-sdk) EXTRAS="[claude-sdk,tui]"; RUNTIME="claude-sdk" ;;
- claude-cli) EXTRAS="[mcp,tui]"; RUNTIME="claude-cli" ;;
- codex) EXTRAS="[mcp,tui]"; RUNTIME="codex" ;;
- opencode) EXTRAS="[mcp,tui]"; RUNTIME="opencode" ;;
- hermes) EXTRAS="[mcp,tui]"; RUNTIME="hermes" ;;
- gemini) EXTRAS="[mcp,tui]"; RUNTIME="gemini" ;;
- goose) EXTRAS="[mcp,tui]"; RUNTIME="goose" ;;
- kiro) EXTRAS="[mcp,tui]"; RUNTIME="kiro" ;;
- copilot) EXTRAS="[mcp,tui]"; RUNTIME="copilot" ;;
- pi) EXTRAS="[mcp,tui]"; RUNTIME="pi" ;;
- gjc) EXTRAS="[mcp,tui]"; RUNTIME="gjc" ;;
- omp) EXTRAS="[mcp,tui]"; RUNTIME="omp" ;;
- all) EXTRAS="[all]"; RUNTIME="" ;;
- "") EXTRAS="[mcp,tui]"; RUNTIME="" ;;
- *)
- _err "unsupported runtime '$1'"
- _info "Expected one of: claude, claude-sdk, claude-cli, codex, opencode, hermes, gemini, goose, kiro, copilot, pi, gjc, omp, all"
- exit 1
- ;;
- esac
- }
- # Try to read the previously-configured runtime from ~/.ouroboros/config.yaml.
- # Preserves user choice across upgrades unless --reconfigure / --runtime is set.
- EXISTING_RUNTIME=""
- EXISTING_CONFIG="$HOME/.ouroboros/config.yaml"
- if [ -z "$EXPLICIT_RUNTIME" ] && [ -z "$RECONFIGURE" ] && [ -f "$EXISTING_CONFIG" ] && command -v python3 &>/dev/null; then
- EXISTING_RUNTIME=$(EXISTING_CONFIG="$EXISTING_CONFIG" python3 -c "
- import os, re
- supported = {'claude', 'claude_mcp', 'codex', 'opencode', 'hermes', 'gemini', 'goose', 'kiro', 'copilot', 'pi', 'gjc', 'omp'}
- try:
- lines = open(os.environ['EXISTING_CONFIG']).read().splitlines()
- in_orchestrator = False
- for line in lines:
- if re.match(r'^orchestrator:\s*(?:#.*)?$', line):
- in_orchestrator = True
- continue
- if in_orchestrator and line and not line[0].isspace():
- break
- if in_orchestrator:
- match = re.match(r'\s+runtime_backend:\s*[\"\']?([^\"\'\s#]+)', line)
- if match and match.group(1) in supported:
- # Preserve the transport identity on unattended upgrades:
- # claude is the SDK/MCP 1 profile; claude_mcp is the
- # explicit dependency-free CLI/MCP 2 worker profile.
- print('claude-cli' if match.group(1) == 'claude_mcp' else match.group(1))
- break
- except Exception:
- pass
- " 2>/dev/null || true)
- fi
- if [ -n "$EXPLICIT_RUNTIME" ]; then
- _blank
- _ok "Runtime: $EXPLICIT_RUNTIME (from --runtime / OUROBOROS_INSTALL_RUNTIME)"
- _runtime_to_extras "$EXPLICIT_RUNTIME"
- elif [ -n "$EXISTING_RUNTIME" ]; then
- _blank
- _ok "Runtime: $EXISTING_RUNTIME (preserved from $EXISTING_CONFIG)"
- _info "Re-run with --reconfigure to choose again."
- _runtime_to_extras "$EXISTING_RUNTIME"
- elif [ "$RUNTIME_COUNT" -gt 1 ]; then
- if [ -t 0 ]; then
- _blank
- _say "${BOLD}Multiple runtimes detected. Pick where Ouroboros should appear first:${RESET}"
- _choice 1 "Claude SDK" "MCP 1.x Agent SDK profile (${PACKAGE_NAME}[claude,tui]); choose Claude CLI for MCP 2"
- _choice 2 "Codex" "Codex plugin artifacts + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 3 "Hermes" "Hermes agent guides + MCP 2 server (${PACKAGE_NAME}[mcp,tui])"
- _choice 4 "OpenCode" "OpenCode commands + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 5 "Gemini" "Gemini CLI integration + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 6 "Goose" "Goose CLI integration + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 7 "Kiro" "Kiro CLI integration + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 8 "Copilot" "GitHub Copilot integration + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 9 "Pi" "Pi CLI bridge + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 10 "GJC" "GJC CLI bridge + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 11 "OMP" "Oh My Pi (omp) CLI bridge + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 12 "All" "Install every optional integration (${PACKAGE_NAME}[all])"
- _prompt "Select [1]: "
- read -r choice
- case "${choice:-1}" in
- 2) _runtime_to_extras "codex" ;;
- 3) _runtime_to_extras "hermes" ;;
- 4) _runtime_to_extras "opencode" ;;
- 5) _runtime_to_extras "gemini" ;;
- 6) _runtime_to_extras "goose" ;;
- 7) _runtime_to_extras "kiro" ;;
- 8) _runtime_to_extras "copilot" ;;
- 9) _runtime_to_extras "pi" ;;
- 10) _runtime_to_extras "gjc" ;;
- 11) _runtime_to_extras "omp" ;;
- 12) _runtime_to_extras "all" ;;
- *) _runtime_to_extras "claude" ;;
- esac
- else
- # Pipe mode: default to claude when multiple runtimes exist
- _warn "Multiple runtimes detected in non-interactive mode; defaulting to Claude."
- _runtime_to_extras "claude"
- fi
- elif [ "$HAS_CLAUDE" = true ] && [ "$RUNTIME_COUNT" -eq 1 ]; then
- _runtime_to_extras "claude"
- elif [ "$HAS_CODEX" = true ] && [ "$RUNTIME_COUNT" -eq 1 ]; then
- _runtime_to_extras "codex"
- elif [ "$HAS_HERMES" = true ] && [ "$RUNTIME_COUNT" -eq 1 ]; then
- _runtime_to_extras "hermes"
- elif [ "$HAS_OPENCODE" = true ] && [ "$RUNTIME_COUNT" -eq 1 ]; then
- _runtime_to_extras "opencode"
- elif [ "$HAS_GEMINI" = true ] && [ "$RUNTIME_COUNT" -eq 1 ]; then
- _runtime_to_extras "gemini"
- elif [ "$HAS_GOOSE" = true ] && [ "$RUNTIME_COUNT" -eq 1 ]; then
- _runtime_to_extras "goose"
- elif [ "$HAS_KIRO" = true ] && [ "$RUNTIME_COUNT" -eq 1 ]; then
- _runtime_to_extras "kiro"
- elif [ "$HAS_COPILOT" = true ] && [ "$RUNTIME_COUNT" -eq 1 ]; then
- _runtime_to_extras "copilot"
- elif [ "$HAS_PI" = true ] && [ "$RUNTIME_COUNT" -eq 1 ]; then
- _runtime_to_extras "pi"
- elif [ "$HAS_GJC" = true ] && [ "$RUNTIME_COUNT" -eq 1 ]; then
- _runtime_to_extras "gjc"
- elif [ "$HAS_OMP" = true ] && [ "$RUNTIME_COUNT" -eq 1 ]; then
- _runtime_to_extras "omp"
- else
- # No runtime CLI on PATH yet — first install. Always prompt when interactive
- # so the user picks deliberately rather than silently defaulting to claude.
- if [ -t 0 ]; then
- _blank
- _say "${BOLD}No runtime CLI detected yet. Choose the agent you plan to use:${RESET}"
- _choice 1 "Claude SDK" "MCP 1.x Agent SDK profile (${PACKAGE_NAME}[claude,tui]); choose Claude CLI for MCP 2"
- _choice 2 "Codex" "Codex plugin artifacts + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 3 "Hermes" "Hermes agent guides + MCP 2 server (${PACKAGE_NAME}[mcp,tui])"
- _choice 4 "OpenCode" "OpenCode commands + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 5 "Gemini" "Gemini CLI integration + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 6 "Goose" "Goose CLI integration + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 7 "Kiro" "Kiro CLI integration + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 8 "Copilot" "GitHub Copilot integration + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 9 "Pi" "Pi CLI bridge + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 10 "GJC" "GJC CLI bridge + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 11 "OMP" "Oh My Pi (omp) CLI bridge + MCP 2 (${PACKAGE_NAME}[mcp,tui])"
- _choice 12 "All" "Install every optional integration (${PACKAGE_NAME}[all])"
- _choice 0 "MCP 2 default" "Install MCP 2 + settings GUI; choose a compatible backend later"
- _prompt "Select [1]: "
- read -r choice
- case "${choice:-1}" in
- 0) _runtime_to_extras "" ;;
- 2) _runtime_to_extras "codex" ;;
- 3) _runtime_to_extras "hermes" ;;
- 4) _runtime_to_extras "opencode" ;;
- 5) _runtime_to_extras "gemini" ;;
- 6) _runtime_to_extras "goose" ;;
- 7) _runtime_to_extras "kiro" ;;
- 8) _runtime_to_extras "copilot" ;;
- 9) _runtime_to_extras "pi" ;;
- 10) _runtime_to_extras "gjc" ;;
- 11) _runtime_to_extras "omp" ;;
- 12) _runtime_to_extras "all" ;;
- *) _runtime_to_extras "claude" ;;
- esac
- else
- # Pipe mode (curl | bash): install the MCP v2 + settings GUI default profile.
- _blank
- _warn "No runtime detected in non-interactive mode; installing MCP v2 + settings GUI."
- _info "Pick an MCP v2-compatible backend afterwards with: ouroboros setup --runtime <claude-cli|codex|opencode|hermes|gemini|goose|kiro|copilot|pi|gjc|omp>"
- _runtime_to_extras ""
- fi
- fi
- if [ -n "$RUNTIME" ]; then
- _ok "Selected backend: $RUNTIME"
- elif [ "$EXTRAS" = "[all]" ]; then
- _ok "Selected backend: all"
- else
- _info "Selected backend: none yet"
- fi
- INSTALL_SPEC="${PACKAGE_NAME}${EXTRAS}"
- INSTALL_PYTHON_SPEC="$DEFAULT_PYTHON_SPEC"
- case "$EXTRAS" in
- "[all]" | "[litellm]" | *litellm*)
- INSTALL_PYTHON_SPEC="$LITELLM_PYTHON_SPEC"
- ;;
- esac
- # Python check: always required for pip; also needed by pipx to pick the right interpreter.
- if [ "$HAS_UV" = false ]; then
- if [ "$HAS_PIPX" = true ]; then
- # For pipx: probe versioned candidates first, then fall back to generic names.
- for cmd in python3.14 python3.13 python3.12 python3 python; do
- if command -v "$cmd" &>/dev/null && _python_ok "$cmd" "$INSTALL_PYTHON_SPEC"; then
- PYTHON="$(command -v "$cmd")"
- break
- fi
- done
- if [ -z "$PYTHON" ]; then
- _blank
- _warn "pipx requires $(_python_requirement_message), but none was found."
- if _bootstrap_uv; then
- HAS_UV=true
- HAS_PIPX=false
- else
- _blank
- _err "pipx requires $(_python_requirement_message), but none was found."
- _blank
- _print_python_install_remediation
- exit 1
- fi
- fi
- if [ "$HAS_UV" = false ]; then
- _ok "Python found: $($PYTHON --version)"
- fi
- else
- # pip fallback: prefer explicit compatible versions for constrained profiles.
- if [ "$INSTALL_PYTHON_SPEC" = "$LITELLM_PYTHON_SPEC" ]; then
- PYTHON_CANDIDATES="python3.13 python3.12 python3 python"
- else
- PYTHON_CANDIDATES="python3 python"
- fi
- for cmd in $PYTHON_CANDIDATES; do
- if command -v "$cmd" &>/dev/null && _python_ok "$cmd" "$INSTALL_PYTHON_SPEC"; then
- PYTHON="$cmd"
- break
- fi
- done
- if [ -z "$PYTHON" ]; then
- _blank
- _warn "No installer found: uv, pipx, or $(_python_requirement_message)."
- if _bootstrap_uv; then
- HAS_UV=true
- else
- _blank
- _err "No installer found: uv, pipx, or $(_python_requirement_message)."
- _blank
- _print_python_install_remediation
- exit 1
- fi
- fi
- if [ "$HAS_UV" = false ]; then
- _ok "Python found: $($PYTHON --version)"
- fi
- fi
- fi
- _step "3/4 Installing Ouroboros" "Package: ${INSTALL_SPEC}"
- _say "Installing ${INSTALL_SPEC} ..."
- # 3. Install (or upgrade if already installed).
- # Resolve optional dependencies from the selected distribution, not this
- # installer's checkout: PyPI may still serve an older compatible release.
- INSTALL_METHOD=""
- if [ "$HAS_UV" = true ]; then
- INSTALL_METHOD="uv"
- _info "Install method: uv tool install"
- # Keep the bounded Click repair for older wheels that omitted its metadata.
- # The target's extras own SDK/MCP/TUI pins and Python/platform markers.
- UV_ARGS=(tool install --upgrade --python "$INSTALL_PYTHON_SPEC" "$INSTALL_SPEC" --with "$CLICK_SPEC")
- if [ -n "$PRE_FLAG" ]; then
- UV_ARGS+=(--prerelease=allow)
- fi
- uv "${UV_ARGS[@]}"
- elif [ "$HAS_PIPX" = true ]; then
- INSTALL_METHOD="pipx"
- _info "Install method: pipx"
- if [ -n "$PRE_FLAG" ]; then
- pipx install --force --python "$PYTHON" --pip-args='--pre' "$INSTALL_SPEC"
- else
- pipx install --force --python "$PYTHON" "$INSTALL_SPEC"
- fi
- # The venv name is the distribution name even when installing from a local path.
- pipx inject "ouroboros-ai" "$CLICK_SPEC"
- else
- INSTALL_METHOD="pip"
- _info "Install method: pip --user"
- if [ -n "$PRE_FLAG" ]; then
- $PYTHON -m pip install --user --upgrade --pre "$INSTALL_SPEC" "$CLICK_SPEC"
- else
- $PYTHON -m pip install --user --upgrade "$INSTALL_SPEC" "$CLICK_SPEC"
- fi
- fi
- # Ensure setup runs the freshly-installed uv tool binary rather than a stale
- # command already on PATH. uv can install into UV_TOOL_BIN_DIR or its configured
- # tool bin directory without updating the current shell's PATH, so remember the
- # fresh executable and invoke that exact path below. For pipx/pip installs,
- # preserve the existing PATH command unless no ouroboros command is visible.
- OUROBOROS_BIN=""
- _prepend_path_if_ouroboros() {
- local candidate="$1"
- if [ -n "$candidate" ] && [ -x "$candidate/ouroboros" ]; then
- export PATH="$candidate:$PATH"
- if [ -z "$OUROBOROS_BIN" ]; then
- OUROBOROS_BIN="$candidate/ouroboros"
- fi
- return 0
- fi
- return 1
- }
- if [ "$INSTALL_METHOD" = "uv" ]; then
- _prepend_path_if_ouroboros "${UV_TOOL_BIN_DIR:-}" || true
- if command -v uv &>/dev/null; then
- UV_TOOL_BIN="$(uv tool dir --bin 2>/dev/null || true)"
- _prepend_path_if_ouroboros "$UV_TOOL_BIN" || true
- fi
- fi
- if [ -z "$OUROBOROS_BIN" ] && ! command -v ouroboros &>/dev/null; then
- for p in "$HOME/.local/bin" "$HOME/.cargo/bin" "$HOME/bin"; do
- _prepend_path_if_ouroboros "$p" || true
- done
- fi
- OUROBOROS_SETUP_CMD=""
- if [ -n "$OUROBOROS_BIN" ]; then
- OUROBOROS_SETUP_CMD="$OUROBOROS_BIN"
- elif command -v ouroboros &>/dev/null; then
- OUROBOROS_SETUP_CMD="ouroboros"
- fi
- # 4. Setup (ouroboros CLI configures runtime-specific integration)
- _step "4/4 Wiring local integrations" "Creates config and runtime-specific files when a backend was selected."
- if [ -n "$RUNTIME" ] && [ -n "$OUROBOROS_SETUP_CMD" ]; then
- _info "Running: $OUROBOROS_SETUP_CMD setup --runtime $RUNTIME --non-interactive"
- if "$OUROBOROS_SETUP_CMD" setup --runtime "$RUNTIME" --non-interactive; then
- :
- else
- setup_status=$?
- _warn "Runtime setup failed; installation is incomplete. Fix the error above and re-run setup."
- exit "$setup_status"
- fi
- elif [ -n "$RUNTIME" ]; then
- _warn "ouroboros command is not on PATH yet; run setup after your shell sees the installed binary."
- else
- _info "No backend selected; skipping runtime setup."
- fi
- # Refresh already-installed artifacts for every detected runtime, even those
- # that are not the preserved primary backend. Setup only wires the selected
- # runtime, so upgrades must not leave other runtimes' rules/skills/bridges
- # stale. `setup refresh` is presence-gated per artifact and never touches MCP
- # registrations or config.
- if [ -n "$OUROBOROS_SETUP_CMD" ]; then
- _info "Refreshing runtime artifacts for detected runtimes"
- "$OUROBOROS_SETUP_CMD" setup refresh || _warn "Artifact refresh skipped; run: ouroboros setup refresh"
- fi
- _decimal_at_least() {
- local left right
- left="${1#${1%%[!0]*}}"
- right="${2#${2%%[!0]*}}"
- [ -n "$left" ] || left=0
- [ -n "$right" ] || right=0
- if [ "${#left}" -ne "${#right}" ]; then
- [ "${#left}" -gt "${#right}" ]
- else
- [ "$left" = "$right" ] || [[ "$left" > "$right" ]]
- fi
- }
- _ensure_omp_tool_call_timeout() {
- local omp_bin current
- omp_bin="$(command -v omp 2>/dev/null || true)"
- if [ -z "$omp_bin" ]; then
- return 0
- fi
- current="$("$omp_bin" config get extensionHandlers.toolCallTimeoutMs 2>/dev/null || true)"
- case "$current" in
- ''|*[!0-9]*) ;;
- *)
- if _decimal_at_least "$current" 60000; then
- return 0
- fi
- ;;
- esac
- if "$omp_bin" config set extensionHandlers.toolCallTimeoutMs 60000 >/dev/null 2>&1; then
- _ok "OMP MCP tool timeout set to 60s"
- else
- _warn "Could not set OMP MCP tool timeout; run: omp config set extensionHandlers.toolCallTimeoutMs 60000"
- fi
- }
- _ensure_omp_tool_call_timeout
- # 5. Claude Code integration. The default Claude selection and its explicit
- # SDK alias stay on MCP 1.x. The plugin-owned MCP launcher starts MCP 2 in a
- # separate uvx environment and selects the dependency-free CLI worker.
- # Skill refresh is artifact-only and should happen whenever Claude is present;
- # otherwise a Codex-primary upgrade can leave Claude Code reading stale skills.
- if command -v claude &>/dev/null && { [ "$RUNTIME" = "claude" ] || [ "$RUNTIME" = "claude-sdk" ] || [ "$EXTRAS" = "[all]" ]; }; then
- _blank
- _say "${BLUE}◆${RESET} ${BOLD}Claude Code extras${RESET}"
- _warn "Claude SDK is isolated on MCP 1.x. The Claude plugin launches the Ouroboros MCP 2 server in a separate uvx environment with --runtime claude-cli."
- fi
- if command -v claude &>/dev/null; then
- if ! { [ "$RUNTIME" = "claude" ] || [ "$RUNTIME" = "claude-sdk" ] || [ "$EXTRAS" = "[all]" ]; }; then
- _blank
- _say "${BLUE}◆${RESET} ${BOLD}Claude Code skills${RESET}"
- fi
- # 5a. Install/update Ouroboros skills (claude plugin)
- _info "Installing Ouroboros skills via Claude plugin marketplace..."
- claude plugin marketplace add Q00/ouroboros 2>/dev/null || true
- claude plugin marketplace update ouroboros 2>/dev/null || true
- if claude plugin install ouroboros@ouroboros 2>/dev/null; then
- # `install` is a no-op for an already-installed plugin — `update` moves it to the latest version
- claude plugin update ouroboros@ouroboros >/dev/null 2>&1 || true
- _ok "Skills installed"
- else
- _warn "Skills skipped. Manual install: claude plugin marketplace add Q00/ouroboros && claude plugin install ouroboros@ouroboros"
- fi
- fi
- _telemetry_ping install_completed "runtime=${RUNTIME:-none}" \
- "version=${LATEST:-unknown}" "ref=$INSTALL_REF"
- _blank
- _say "${GREEN}${BOLD}Done! Ouroboros is ready.${RESET}"
- _blank
- _say "${BOLD}Get started${RESET}"
- _info 'Open your AI coding agent and run: > ooo interview "your idea here"'
- _info 'Or from the terminal: ouroboros init start "your idea here"'
- if [ -n "$RUNTIME" ]; then
- _info "Current backend: $RUNTIME"
- fi
- _info "Switch backend later: ouroboros setup --runtime <claude|claude-sdk|claude-cli|codex|opencode|hermes|gemini|goose|kiro|copilot|pi|gjc|omp>"
- _say "${BOLD}Model settings — use your default model or configure one directly${RESET}"
- _info 'Inside your AI agent: > ooo config (opens in your browser)'
- _info 'From this terminal: ouroboros config (full-screen TUI)'
- # 6. Optional direct model settings (interactive installs only).
- # install.sh always runs in a real terminal when interactive, so the
- # full-screen Textual settings app can open right here. curl|bash pipe
- # installs skip this automatically ([ -t 0 ] is false).
- if [ -t 0 ] && [ -z "${OUROBOROS_INSTALL_SKIP_CONFIG_GUI:-}" ]; then
- if [ "$RUNTIME" = "codex" ]; then
- GUI_MESSAGE="Codex's current default model is ready to use. Configure a model directly now?"
- else
- GUI_MESSAGE="Your selected runtime's default model is ready to use. Configure a model directly now?"
- fi
- # Most people should start with the runtime default. The settings UI is for
- # deliberate model pins, so it must remain an opt-in rather than a fresh
- # install speed bump.
- GUI_DEFAULT="n"
- GUI_HINT="[y/N]"
- _blank
- _say "${BOLD}${GUI_MESSAGE}${RESET}"
- _prompt "Open direct model settings $GUI_HINT: "
- read -r gui_choice
- case "${gui_choice:-$GUI_DEFAULT}" in
- y | Y | yes | YES)
- GUI_OK=false
- if [ -n "${OUROBOROS_SETUP_CMD:-}" ] && "$OUROBOROS_SETUP_CMD" config; then
- GUI_OK=true
- elif command -v uvx &>/dev/null; then
- # The selected extras may not include [tui]; run the GUI from an
- # ephemeral env with the tui extra instead of fattening the install.
- _info "Settings GUI needs the tui extra; running it via uvx..."
- if uvx --python "$DEFAULT_PYTHON_SPEC" --from "${PACKAGE_NAME}[tui]" ouroboros config; then
- GUI_OK=true
- fi
- fi
- if [ "$GUI_OK" = false ]; then
- _warn "Could not open the settings GUI."
- _info "Run it later with: uvx --python '>=3.12' --from '${PACKAGE_NAME}[tui]' ouroboros config"
- fi
- ;;
- *)
- _info "Using the runtime default model. You can change it anytime:"
- _info ' in your AI agent: > ooo config'
- _info ' in a terminal: ouroboros config'
- ;;
- esac
- fi
- # 6. DeepSeek Harness integration. Unlike the other hosts, dsh keeps its plugins
- # per profile, and `dsh plugin` requires --profile, so there is no single global
- # install to run. Cover the profile a dsh user actually boots (`web`, which
- # `dsh web` scaffolds) and refresh any other profile that already carries the
- # bundle, which is how an existing install picks up a new release.
- if [ "$HAS_DSH" = true ]; then
- _blank
- _say "${BLUE}◆${RESET} ${BOLD}DeepSeek Harness plugin${RESET}"
- DSH_PROFILE_ROOT="${DSH_HOME:-$HOME/.dsh}/profiles"
- DSH_TARGET_PROFILES=("web")
- _dsh_json_python="${PYTHON:-}"
- if [ -z "$_dsh_json_python" ]; then
- _dsh_json_python=$(command -v python3 2>/dev/null || true)
- fi
- if [ -z "$_dsh_json_python" ]; then
- _dsh_ouroboros_cmd=$(command -v ouroboros 2>/dev/null || true)
- if [ -n "$_dsh_ouroboros_cmd" ] && [ -r "$_dsh_ouroboros_cmd" ]; then
- _dsh_shebang=$(head -n 1 "$_dsh_ouroboros_cmd" 2>/dev/null || true)
- case "$_dsh_shebang" in
- '#!'/*)
- _dsh_json_python=${_dsh_shebang#'#!'}
- case "$_dsh_json_python" in
- *' '*) _dsh_json_python="" ;;
- esac
- [ -x "$_dsh_json_python" ] || _dsh_json_python=""
- ;;
- esac
- fi
- fi
- if [ -n "$_dsh_json_python" ] && [ -d "$DSH_PROFILE_ROOT" ]; then
- for _dsh_profile_dir in "$DSH_PROFILE_ROOT"/*/; do
- [ -d "$_dsh_profile_dir" ] || continue
- _dsh_profile=${_dsh_profile_dir#"$DSH_PROFILE_ROOT"/}
- _dsh_profile=${_dsh_profile%/}
- [ "$_dsh_profile" = "web" ] && continue
- # Only profiles that already opted in. Adding Ouroboros tools to an
- # unrelated profile because the installer ran is not an upgrade.
- if "$_dsh_json_python" -c 'import json, sys; data = json.load(open(sys.argv[1], encoding="utf-8")); dependencies = data.get("dependencies", {}) if isinstance(data, dict) else {}; sys.exit(0 if isinstance(dependencies, dict) and "dsh-ouroboros" in dependencies else 1)' "$_dsh_profile_dir/package.json" 2>/dev/null; then
- DSH_TARGET_PROFILES+=("$_dsh_profile")
- fi
- done
- fi
- for _dsh_profile in "${DSH_TARGET_PROFILES[@]}"; do
- _dsh_profile_q=$(_shell_quote "$_dsh_profile")
- if dsh plugin --profile "$_dsh_profile" add "$DSH_PLUGIN_SPEC" >/dev/null 2>&1; then
- _ok "dsh profile $_dsh_profile_q: Ouroboros tools installed"
- else
- _warn "dsh profile $_dsh_profile_q: install skipped"
- _info "Manual install: dsh plugin --profile $_dsh_profile_q add \"$DSH_PLUGIN_SPEC\""
- fi
- done
- _info "Type 'ooo interview <goal>' in a dsh chat to use them."
- fi
- _blank
- _say "${BOLD}Like Ouroboros?${RESET}"
- _info "Give the repo a star on GitHub: https://github.com/Q00/ouroboros"
- # 7. Ouroboros console. Once the install is done, start the browser console so
- # a new user lands in a guided UI. It runs detached: the installer returns the
- # terminal, never waits on it beyond bounded checks, and never fails because of
- # it. Releases without `ouroboros gui` get no console output at all.
- # --no-console or OUROBOROS_NO_CONSOLE=1 skips this step. The variable takes a
- # closed set of values; anything else is reported and treated as an opt-out,
- # because not starting a background server is the safe reading.
- _console_opted_out() {
- local value
- [ -z "$NO_CONSOLE_FLAG" ] || return 0
- value=$(printf '%s' "${OUROBOROS_NO_CONSOLE:-}" | tr '[:upper:]' '[:lower:]')
- value="${value#"${value%%[![:space:]]*}"}"
- value="${value%"${value##*[![:space:]]}"}"
- case "$value" in
- '' | 0 | false | no | off) return 1 ;;
- 1 | true | yes | on) return 0 ;;
- *)
- _warn "OUROBOROS_NO_CONSOLE has an unrecognized value (expected 1 or 0); not starting the console."
- return 0
- ;;
- esac
- }
- # Stop a background child within a fixed bound: SIGTERM, up to 1 s to exit,
- # then SIGKILL and up to 1 s more. Its status is collected only once it is
- # gone, so this never blocks on a child that refuses to die.
- _console_stop_child() {
- local pid="$1" ticks=10
- kill -TERM "$pid" 2>/dev/null || true
- while [ "$ticks" -gt 0 ] && kill -0 "$pid" 2>/dev/null; do
- ticks=$((ticks - 1))
- sleep 0.1
- done
- if kill -0 "$pid" 2>/dev/null; then
- kill -KILL "$pid" 2>/dev/null || true
- ticks=10
- while [ "$ticks" -gt 0 ] && kill -0 "$pid" 2>/dev/null; do
- ticks=$((ticks - 1))
- sleep 0.1
- done
- fi
- if ! kill -0 "$pid" 2>/dev/null; then
- wait "$pid" 2>/dev/null || true
- fi
- }
- # Run a command with stdin closed and stderr discarded (stdout is the
- # caller's), giving it <ticks> tenths of a second. On timeout it is stopped
- # with _console_stop_child and the status is 124, so the whole call returns
- # within its limit plus 2 s.
- _console_run_bounded() {
- local ticks="$1" pid
- shift
- "$@" </dev/null 2>/dev/null &
- pid=$!
- while kill -0 "$pid" 2>/dev/null; do
- if [ "$ticks" -le 0 ]; then
- _console_stop_child "$pid"
- return 124
- fi
- ticks=$((ticks - 1))
- sleep 0.1
- done
- wait "$pid"
- }
- # `ouroboros gui --help` exits 0 only on a release that ships the console;
- # older ones fail with "No such command". Telemetry is off for the probe since
- # it is not a real use.
- _console_supported() {
- _console_run_bounded "$2" env OUROBOROS_TELEMETRY=0 DO_NOT_TRACK=1 "$1" gui --help >/dev/null
- }
- # Under `curl | bash` stdin is the pipe carrying this script, so a terminal is
- # reached through /dev/tty rather than fd 0.
- _console_has_terminal() {
- { : </dev/tty; } 2>/dev/null
- }
- _console_is_wsl() {
- if [ -n "${WSL_DISTRO_NAME:-}" ] || [ -n "${WSL_INTEROP:-}" ]; then
- return 0
- fi
- grep -qi microsoft /proc/sys/kernel/osrelease 2>/dev/null
- }
- # A browser can only be opened on this machine's screen: macOS, or Linux/WSL
- # with an X11/Wayland display, or WSL with a bridge to the Windows browser
- # (wslview, or BROWSER set). An SSH session without a display has none of these
- # for the person at the other end; on macOS the browser would open on the
- # remote Mac's screen even with X11 forwarding.
- _console_has_desktop() {
- local ssh=false
- if [ -n "${SSH_CONNECTION:-}${SSH_CLIENT:-}${SSH_TTY:-}" ]; then
- ssh=true
- fi
- if [ "$(uname -s 2>/dev/null || true)" = "Darwin" ]; then
- [ "$ssh" = false ]
- return
- fi
- if [ -n "${DISPLAY:-}" ] || [ -n "${WAYLAND_DISPLAY:-}" ]; then
- return 0
- fi
- [ "$ssh" = false ] || return 1
- _console_is_wsl || return 1
- [ -n "${BROWSER:-}" ] || command -v wslview >/dev/null 2>&1
- }
- # A Python to parse the console's JSON state with: the interpreter `ouroboros`
- # itself runs on (an absolute `#!/.../python*` shebang, as uv, pipx and pip
- # entry points have), else python3 on PATH. Nothing but a python-named
- # interpreter is ever run with the check, and a candidate counts only if it
- # imports json in isolated mode within the bound. Prints nothing and fails when
- # there is none.
- _console_json_python() {
- local cmd="$1" path shebang candidate
- path=$(command -v "$cmd" 2>/dev/null || true)
- if [ -n "$path" ] && [ -f "$path" ] && [ -r "$path" ]; then
- shebang=$(head -n 1 "$path" 2>/dev/null || true)
- case "$shebang" in
- '#!'/*)
- candidate=${shebang#'#!'}
- case "$candidate" in
- *[[:space:]]*) ;;
- */python | */python3 | */python3.[0-9]*)
- if [ -x "$candidate" ] && _console_run_bounded 50 "$candidate" -I -c 'import json' >/dev/null; then
- printf '%s' "$candidate"
- return 0
- fi
- ;;
- esac
- ;;
- esac
- fi
- candidate=$(command -v python3 2>/dev/null || true)
- if [ -n "$candidate" ] && _console_run_bounded 50 "$candidate" -I -c 'import json' >/dev/null; then
- printf '%s' "$candidate"
- return 0
- fi
- return 1
- }
- # Reads ~/.ouroboros/gui/server.json, written by `ouroboros gui` once it
- # listens, as JSON: only a well-formed top-level object whose own `host` is a
- # loopback name and whose own `port` is an integer in 1-65535 yields a URL.
- _CONSOLE_STATE_PARSER='
- import json, sys
- try:
- with open(sys.argv[1], encoding="utf-8") as fh:
- state = json.load(fh)
- except Exception:
- sys.exit(1)
- if not isinstance(state, dict):
- sys.exit(1)
- port = state.get("port")
- if state.get("host") not in ("127.0.0.1", "localhost", "0.0.0.0"):
- sys.exit(1)
- if type(port) is not int or not 1 <= port <= 65535:
- sys.exit(1)
- print("http://localhost:%d/" % port)
- '
- # Print the console URL from <state file> using <python>; fail closed (print
- # nothing) without a parser, for a file that is not a regular file, or for
- # anything the parser rejects. Bounded like every other child here.
- _console_state_url() {
- local py="$1" state="$2"
- [ -n "$py" ] || return 1
- [ -f "$state" ] || return 1
- _console_run_bounded 30 "$py" -I -c "$_CONSOLE_STATE_PARSER" "$state"
- }
- _console_next_hint() {
- _blank
- _say "${BOLD}Next:${RESET} open the Ouroboros console in your browser with: ouroboros gui"
- }
- _console_log_hint() {
- [ "$1" = /dev/null ] || _info "Log: $1"
- }
- # Start `ouroboros gui` detached and wait until <seconds> have passed for it to
- # report its address (each check is itself bounded, so the wait ends within
- # <seconds> plus one parser bound). Ignoring SIGHUP (what nohup does) and,
- # where available, setsid keep it alive after this terminal closes. A console
- # that is already running is reused by `ouroboros gui`, which then only opens
- # the browser and exits 0.
- _console_start() {
- local cmd="$1" seconds="$2" dir="$HOME/.ouroboros/gui" state log py before current last url="" pid status="" deadline
- state="$dir/server.json"
- log="$dir/console.log"
- if ! mkdir -p "$dir" 2>/dev/null; then
- log=/dev/null
- elif [ -L "$log" ] || { [ -e "$log" ] && [ ! -f "$log" ]; }; then
- log=/dev/null # never follow a link or write into a FIFO or device
- elif [ -e "$log" ] && ! chmod 600 "$log" 2>/dev/null; then
- log=/dev/null # an existing log stays private, or is not used at all
- fi
- py=$(_console_json_python "$cmd" || true)
- if [ -z "$py" ]; then
- # Without a parser the URL cannot be confirmed; only watch for an
- # immediate failure, then hand over to the reopen hint.
- [ "$seconds" -le 3 ] || seconds=3
- fi
- before=""
- if [ -f "$state" ]; then
- before=$(cat "$state" 2>/dev/null || true)
- fi
- last="$before"
- (
- trap '' HUP
- umask 077
- # Python's webbrowser does not know wslview; point it there when WSL has
- # no browser configured, which is the bridge _console_has_desktop found.
- if _console_is_wsl && [ -z "${BROWSER:-}" ] && command -v wslview >/dev/null 2>&1; then
- export BROWSER=wslview
- fi
- if command -v setsid >/dev/null 2>&1; then
- exec setsid "$cmd" gui </dev/null >>"$log" 2>&1
- fi
- exec "$cmd" gui </dev/null >>"$log" 2>&1
- ) &
- pid=$!
- deadline=$((SECONDS + seconds))
- while :; do
- if ! kill -0 "$pid" 2>/dev/null; then
- if wait "$pid" 2>/dev/null; then status=0; else status=$?; fi
- break
- fi
- if [ -f "$state" ]; then
- current=$(cat "$state" 2>/dev/null || true)
- if [ -n "$current" ] && [ "$current" != "$last" ]; then
- last="$current"
- url=$(_console_state_url "$py" "$state" || true)
- [ -z "$url" ] || break
- fi
- fi
- [ "$SECONDS" -lt "$deadline" ] || break
- sleep 0.1
- done
- if [ -n "$url" ]; then
- _ok "The Ouroboros console is running in the background at $url"
- _info "It opens in your browser. Stop it with \"Stop console\" at the bottom of its sidebar."
- _info "Reopen it any time with: ouroboros gui"
- _console_log_hint "$log"
- elif [ "$status" = 0 ]; then
- url=$(_console_state_url "$py" "$state" || true)
- if [ -n "$url" ]; then
- _ok "The Ouroboros console is already running at $url; opened it in your browser."
- _info "Reopen it any time with: ouroboros gui"
- else
- _warn "Could not confirm that the Ouroboros console started."
- _console_log_hint "$log"
- _info "Start it any time with: ouroboros gui"
- fi
- elif [ -n "$status" ]; then
- _warn "The Ouroboros console did not start (exit $status). The installation itself is complete."
- _console_log_hint "$log"
- _info "Start it any time with: ouroboros gui"
- else
- _info "The Ouroboros console is still starting in the background; it opens in your browser when ready."
- _info "Stop it with \"Stop console\" at the bottom of its sidebar. Reopen it any time with: ouroboros gui"
- _console_log_hint "$log"
- fi
- }
- _console_after_install() {
- local cmd="$1"
- if _console_opted_out; then
- return 0
- fi
- [ -n "$cmd" ] || return 0
- _console_supported "$cmd" 150 || return 0
- if [ -n "${CI+x}" ] || ! _console_has_terminal || ! _console_has_desktop; then
- _console_next_hint
- return 0
- fi
- _blank
- _say "${BLUE}◆${RESET} ${BOLD}Ouroboros console${RESET}"
- _console_start "$cmd" 20
- }
- _console_after_install "${OUROBOROS_SETUP_CMD:-}" || true
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.