{"id":50893943,"url":"https://github.com/escotilha/oxison","last_synced_at":"2026-06-15T23:00:45.002Z","repository":{"id":365059837,"uuid":"1270336763","full_name":"escotilha/oxison","owner":"escotilha","description":"Reads any repo and writes its product docs (PRODUCT/MANUAL/STACK), plans a roadmap, and builds the work — powered by Claude Code. Read-only by default, sandboxed when it writes.","archived":false,"fork":false,"pushed_at":"2026-06-15T18:22:11.000Z","size":297,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T18:24:47.702Z","etag":null,"topics":["ai-agents","anthropic","autonomous-agents","claude","claude-code","cli","code-comprehension","code-documentation","developer-tools","documentation-generator","llm","python"],"latest_commit_sha":null,"homepage":"https://github.com/escotilha/oxison","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/escotilha.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-15T16:02:15.000Z","updated_at":"2026-06-15T18:09:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/escotilha/oxison","commit_stats":null,"previous_names":["escotilha/oxison"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/escotilha/oxison","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/escotilha%2Foxison","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/escotilha%2Foxison/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/escotilha%2Foxison/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/escotilha%2Foxison/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/escotilha","download_url":"https://codeload.github.com/escotilha/oxison/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/escotilha%2Foxison/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34383468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","anthropic","autonomous-agents","claude","claude-code","cli","code-comprehension","code-documentation","developer-tools","documentation-generator","llm","python"],"created_at":"2026-06-15T23:00:33.264Z","updated_at":"2026-06-15T23:00:44.992Z","avatar_url":"https://github.com/escotilha.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# oxison\n\n[![CI](https://github.com/escotilha/oxison/actions/workflows/ci.yml/badge.svg)](https://github.com/escotilha/oxison/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/github/license/escotilha/oxison)](LICENSE)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n**Reads any repo and writes its product docs (PRODUCT/MANUAL/STACK), plans a roadmap, and builds the work — powered by Claude Code. Read-only by default, sandboxed when it writes.**\n\n`oxison` reads a repository, understands it by driving the\n[Claude Code](https://claude.com/claude-code) CLI as a **read-only**\nsubprocess, and writes product artifacts into its own output directory.\nIt never modifies the repo it analyzes.\n\n```bash\noxison run /path/to/repo\n# → ./oxison-output/{PRODUCT,MANUAL,STACK}.md\n#   + ROADMAP-ANALYSIS.md (if the repo has a roadmap) or SECURITY-NOTES.md (if not)\n#   + COMPREHENSION.md + repomap.json + .oxison-run.json\n```\n\n## Requirements\n\n- **Python ≥ 3.11**\n- The **[Claude Code](https://claude.com/claude-code) CLI**, installed and signed in\n  (oxison drives it as a subprocess; by default it uses your existing Claude Code login —\n  see [Auth](#auth))\n\n## Safety model\n\n`oxison run` and `oxison plan` **never modify the target repo.** Two invariants\nenforce it:\n\n1. **The AI worker is *structurally* read-only** — launched with\n   `--allowedTools Read,Glob,Grep`: no shell, no write tools. It physically\n   cannot modify, create, delete, or execute anything — not just \"told not to.\"\n   (`Bash` is deliberately **excluded**: under `--permission-mode\n   bypassPermissions` a shell is a full write/exec primitive, so it belongs to\n   the build tier, not here.) A unit test asserts the exclusion against the\n   built command line, so it can't silently regress.\n2. **oxison owns every write**, exclusively into `./oxison-output/`.\n   Workers return markdown; oxison writes the files.\n\nAfter a `run`/`plan`, the target repo's git working tree is byte-for-byte\nunchanged (`git status` clean, `HEAD` unmoved).\n\n### `oxison build` is different — it writes code, by design\n\nThe Oxfaz build worker (`oxison build`) is the one stage that **writes**: it has\nfull read/write tools (`Bash` included) so it can implement a task and run the\nproject's tests. It is contained by three layers:\n\n1. **A filesystem + network sandbox (`srt`), on by default.** Each worker is\n   wrapped in Anthropic's [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime)\n   (`sandbox-exec` on macOS, `bubblewrap` on Linux). Writes are confined to the\n   worker's **worktree** + the scoped parts of `.git` it needs to commit (NOT\n   `.git/config` or `.git/hooks`) + Claude's own state; egress is limited to an\n   allowlist (the Anthropic API + package registries + your git host); and\n   credentials (`~/.ssh`, `~/.aws`, …) are unreadable. So even a\n   prompt-injected worker cannot escape the worktree, install a git hook, or\n   exfiltrate. **Requires Node + `npm i -g @anthropic-ai/sandbox-runtime`**\n   (verified against `srt` 1.0.0); if it's missing, `oxison build` fails at\n   preflight with an install hint. `--no-sandbox` disables it (loud stderr\n   warning) for trusted local runs.\n\n   \u003e **Why the sandbox is the default — and what `--no-sandbox` gives up.** A\n   \u003e build worker's prompt is assembled from the roadmap, which derives from\n   \u003e repository and (in greenfield) web-fetched content — i.e. **untrusted\n   \u003e input**. A malicious README or page could attempt prompt injection to steer\n   \u003e the write-capable worker. The srt sandbox is what contains that: an injected\n   \u003e worker still can't escape the worktree, read credentials, or exfiltrate.\n   \u003e `--no-sandbox` removes that containment, so only use it on repos and sources\n   \u003e you fully trust. (The grader in step 3 is a backstop, not a substitute — it\n   \u003e inspects the *diff*, not the worker's runtime behavior.)\n2. **Worktree isolation** — each worker runs in its own git worktree under\n   `oxison-build/worktrees/`, so the repo's main working tree is never edited.\n3. **A grader** — rejects any diff that touches a protected path\n   (`.github/workflows`, `.env`, lockfiles, `.git/`, `oxison-build/`).\n\nWith the srt sandbox on, build mode is safe to point at repos you don't fully\ntrust.\n\n#### Stronger filesystem isolation: the container sandbox (`--sandbox-layer container`)\n\nFor CI, or to isolate a worker more strongly than srt's allowlist, run each\nworker **inside a rootless container**. This is the stronger *filesystem*\nboundary; note the container currently keeps **default network egress** (see the\ncaveat below), so for a fully-hostile repo also narrow egress — that tightening\nis tracked, not yet shipped.\n\n```bash\n# one-time: a container runtime + the worker image\nbrew install podman \u0026\u0026 podman machine init \u0026\u0026 podman machine start   # or docker\npodman build -t localhost/oxfaz-worker:latest docker/oxfaz-worker\n\n# then build with Layer 2 (needs an API key — see auth note)\nANTHROPIC_API_KEY=… oxison build ./oxison-output --repo ~/code/myrepo --sandbox-layer container\n```\n\nHow it's stronger than srt: the worker runs in a container whose **only\nbind-mount is its workspace**, so the host filesystem — `~/.ssh`, the main repo,\nevery credential — is **physically absent**, not merely denied (mount-namespace\nisolation, `--cap-drop ALL`, `--security-opt no-new-privileges`). The worker\nbuilds + commits in a self-contained **clone** mounted at `/work` (a linked\nworktree's `.git` would point outside the mount), and oxison reads the diff from\nthat clone afterwards.\n\nTwo requirements:\n- **Auth is bare-mode.** The macOS Keychain / OAuth store isn't reachable inside\n  a Linux container, so the worker authenticates with an `ANTHROPIC_API_KEY`\n  (forwarded by name into the container, never baked into the image). `oxison\n  build --sandbox-layer container` fails at preflight if no key is set.\n- **macOS: the repo must live under `$HOME`.** A path only mounts into the\n  podman VM if it's on a shared host dir; `$HOME` is shared by default, `/tmp`\n  is not. Repos under `~/code` work; repos under `/tmp` or external volumes\n  won't mount.\n\nVerified end-to-end (macOS, podman): a real worker clones the target, builds +\ncommits its task inside the container, and the host grades + records it — with\n`/Users`, `~/.ssh`, and out-of-`/work` writes all confirmed inaccessible from\ninside. Egress narrowing (the container currently keeps default egress; srt's\ndomain proxy can run inside it as a follow-up) is the remaining tightening,\ntracked in `docs/superpowers/specs/2026-06-15-oxfaz-worker-sandbox-design.md`.\n\n## What it produces\n\n| File | Contents |\n|---|---|\n| `PRODUCT.md` | What the software is, who it's for, core features, mental model |\n| `MANUAL.md` | Prerequisites, install, configuration, usage, workflows |\n| `STACK.md` | Languages, dependencies + versions, runtime, infra/services (grounded in the manifests) |\n| `ROADMAP-ANALYSIS.md` | *(if a roadmap exists)* Analysis of planned work, feasibility vs. current code, sequencing, recommended next items |\n| `SECURITY-NOTES.md` | *(if no roadmap)* Lightweight read-only security surface scan + a nudge to add a roadmap |\n| `COMPREHENSION.md` | The intermediate whole-repo understanding the docs are built from |\n| `repomap.json` | The deterministic repo map (languages, deps, entry points, services) |\n| `.oxison-run.json` | Per-step status + cost; enables `--resume` |\n\n**See it for real:** [`examples/oxison-self/`](examples/oxison-self/) is oxison's\nown docs, generated by running oxison on this repo — real, unedited output.\n\n## How it works\n\n```\nmap (deterministic, no AI)          → repomap.json\n  └─ language histogram, dependency manifests, entry points, services\ncomprehend (read-only AI)           → COMPREHENSION.md\n  └─ single-pass for small repos; map-reduce (slice by top-level dir\n     + synthesis) when the estimated token surface exceeds the threshold\ngenerate (read-only AI, parallel)   → PRODUCT.md, MANUAL.md, STACK.md\nbranch (read-only AI)               → ROADMAP-ANALYSIS.md or SECURITY-NOTES.md\n```\n\nThe risky part — the `claude -p` subprocess wrapper — is hardened:\nprocess-group isolation, concurrent stdout/stderr drain, a 1 MB stream\nlimit, an env whitelist, a wall-clock timeout, and cost extraction, all\nusing argv-form spawning (a prompt can never be shell-interpreted).\n\n## Multi-source ingestion (Oxicome)\n\noxison can comprehend a repo **plus additional non-repo sources** — PDFs,\npresentations, Word documents, plain markdown, and audio/video recordings —\nmerging them into one provenance-tagged comprehension pass.\n\n```bash\n# Feed individual files alongside the repo\noxison run /path/to/repo --add spec.pdf --add deck.pptx --add notes.md\n\n# Or ingest a whole folder at once\noxison run /path/to/repo --sources ./inputs/\n\n# Opt-in OCR for scanned/image-heavy PDFs\noxison run /path/to/repo --add scanned.pdf --ocr\n\n# Transcribe an audio/video recording via a cloud STT API\noxison run /path/to/repo --add demo.mp4 --stt-key $KEY --stt-provider deepgram\n```\n\n`--add PATH` is repeatable; `--sources DIR` ingests every supported file in the\ndirectory. Source types are detected by extension (`.pdf`, `.pptx`, `.ppt`,\n`.docx`, `.doc`, `.md`, `.txt`, `.mp3`, `.mp4`, `.wav`, …).\n\n### The `comprehension.json` artifact\n\nWhen any source is added, oxison emits a `comprehension.json` alongside the\nusual markdown outputs. It is a structured, provenance-tagged envelope — schema\nversion `1.0` — containing:\n\n- the human-readable PRODUCT / MANUAL / STACK comprehension;\n- a machine-readable ledger of every source ingested (path, type, byte size,\n  whether it was extracted successfully).\n\n`comprehension.json` is the stable contract for downstream tooling (CI\npipelines, dashboards, other agents) that need to consume oxison's output\nprogrammatically.\n\n### Installing the source adapters\n\n```bash\npip install 'oxi-son[sources]'   # adds PDF, pptx, and docx support\n```\n\nThe `sources` extra bundles `pypdf`, `python-pptx`, and `python-docx`. Without\nit, those adapters degrade gracefully (the file is logged as skipped-with-reason\nrather than raising an error).\n\n### Caveats\n\n- **OCR** (`--ocr`) requires an optional, unpublished `document_extraction`\n  package to be importable — it brings the heavy PaddleOCR stack. It is **not**\n  an oxison dependency; scanned PDFs fall back to skip-with-reason if the\n  package is absent.\n- **Recordings** (`--stt-key`) upload audio/video to a third-party cloud STT\n  API (e.g. Deepgram). This is the **one path that sends data off-host** — it\n  is entirely opt-in and requires an explicit key. All other adapters process\n  files locally.\n\n### Safety invariant\n\noxison's read-only guarantee extends to every source adapter: oxison reads the\nfiles you point it at and never modifies them. No adapter writes back to any\ninput path.\n\n## Start from an idea — `oxison ideate` (greenfield)\n\nYou don't need a repo at all. **`oxison ideate`** starts from **zero** — a\nplain-text project idea plus any non-repo inputs (slide decks, recordings,\nPDFs, markdown, and **website links**) — and produces a reviewable plan for a\nproduct that doesn't exist yet: a comprehension, a `PRODUCT.md` vision/spec, and\nan initial **`ROADMAP`**.\n\n```bash\n# from just an idea\noxison ideate --brief \"a CLI that turns a folder of Markdown notes into a daily Slack standup\"\n\n# idea + supporting material (decks, recordings, and links you want it to read)\noxison ideate \\\n  --brief-file ./pitch.md \\\n  --add deck.pptx --add call-recording.m4a \\\n  --url https://a-competitor.example --url https://some-reference.example\n```\n\nWhat you get in `./oxison-output/`: `COMPREHENSION.md` + `comprehension.json`\n(the synthesized understanding, provenance-tagged by source — `brief:idea`,\n`web:host`, `pptx:deck#slide-4`), `PRODUCT.md` (the product to build), and\n`ROADMAP.md` / `roadmap.json` (a sequenced, from-scratch build plan whose tasks\ncarry observable acceptance criteria — the same gated contract `oxison plan`\nproduces, ready for `oxison build`).\n\nIt needs **at least one input** (`--brief`/`--brief-file`, `--add`, `--sources`,\nor `--url`). To refine the plan, re-run with `--answers-file notes.txt` (your\nguidance steers the roadmap). See [`examples/ideate-standup/`](examples/ideate-standup/)\nfor real output.\n\n**\"Research\" in v1 means synthesis of what you give it** — including the content\nof the `--url` links it fetches — not open-web search. Fetching a URL is the one\nextra thing greenfield does over the read-only flows: it issues an HTTP GET to\nthe links **you** provide (http/https only, with size/time caps). There is no\nmodel-initiated browsing; the AI workers stay read-only (`Read,Glob,Grep`).\n\n\u003e Greenfield is **plan-only** today — it stops at the roadmap. Scaffolding a repo\n\u003e and running the build loop (`oxison build`) from that roadmap is the documented\n\u003e next step.\n\n## Planning (Oxipensa)\n\n`comprehension.json` answers *\"what is this and where is it at?\"*. **Oxipensa**\nturns that into *\"what should we build next?\"* — it reads a `comprehension.json`\nand emits a prioritized, gated **`roadmap.json`** plus a human-readable\n**`ROADMAP.md`**.\n\n```bash\n# plan from a comprehension produced by `oxison run`\noxison plan ./oxison-output\n\n# ground the planner in the actual repo (read-only), and refine with guidance\noxison plan ./oxison-output --repo /path/to/repo --answers-file notes.txt\n```\n\nWhat you get (`roadmap.json`, schema `1.0` — the Oxipensa→Oxfaz contract):\n\n- a prioritized task list, each task carrying a **deterministic identifier**\n  (stable across re-plans, so a builder can dedup), **provenance** (the\n  comprehension locators it traces to), **dependency sequencing**, and at least\n  one **observable acceptance criterion** (a checkable end-state, not \"works\n  well\");\n- the planner's `summary` and any `open_questions` (merged with the\n  comprehension's, the hook for refining the plan with `--answers-file`).\n\nHow it stays trustworthy: every proposed roadmap passes a deterministic\n**plan-gate** before it is written — non-empty titles, valid kinds, real\nacceptance criteria, no dependency cycles or dangling links, and **no task may\ntarget a protected path** (CI config, `.env`, lockfiles, `.git/`). A roadmap\nthat fails the gate is fed back to the planner for one self-correcting pass; a\nroadmap that still fails is never written. The planner worker is **read-only**\nlike every other oxison AI call — it reasons and returns JSON; oxison owns the\nwrites.\n\n## Building (Oxfaz)\n\n**Oxfaz** is the third stage: it consumes an Oxipensa `roadmap.json` and runs an\nautonomous build loop, dispatching one write-worker per task **in an isolated\ngit worktree** and recording every outcome in a durable taskstore.\n\n```bash\n# see what would be built — ingest the roadmap, spawn NO workers\noxison build ./oxison-output --repo /path/to/repo --dry-run\n\n# run the build loop with explicit guardrails\noxison build ./oxison-output --repo /path/to/repo \\\n  --max-ticks 20 --budget-ceiling-usd 50 --no-progress-ticks 5\n```\n\n\u003e ⚠️ **Build mode writes code.** Unlike `run`/`plan` (read-only), Oxfaz workers\n\u003e have full read/write tools. Each runs in its own worktree under\n\u003e `oxison-build/worktrees/`; the repo's main working tree is never touched\n\u003e directly. Start with `--dry-run`.\n\nHow it stays safe and bounded:\n\n- **The spine** (`oxison-build/state.db`) is the durable source of truth — a\n  2-table SQLite store (task + lock) with crash-safe, idempotent writes. A task\n  is marked dispatched **before** its worker spawns and the transition is guarded\n  (`WHERE status='planned'`), so a crash or a double-tick can never re-dispatch\n  in-flight work.\n- **The grader** re-runs the protected-path matcher on each worker's *actual\n  diff* — a worker that touches CI config, `.env`, lockfiles, `.git/`, or\n  `oxison-build/` fails the grade even if the plan looked clean.\n- **Three guardrails** bound every run on a different axis: an **iteration cap**\n  (`--max-ticks`), a **no-progress halt** (`--no-progress-ticks` consecutive\n  ticks with nothing advancing), and a **budget ceiling** (`--budget-ceiling-usd`;\n  a timed-out worker is charged its per-worker cap as a floor, so the meter is\n  honest). An unset ceiling is simply inactive — it never reads as infinite.\n\nThe full production-grade build stack (AI critics, GitHub PR + CI integration,\nauto-merge, deploy-green gating, the three-layer dead-worker reaper) is the\ndocumented follow-on; this is the contract-driven core that takes a roadmap from\n`planned` to a graded build.\n\n## Install\n\nInstall straight from this repo — no PyPI needed:\n\n```bash\n# zero-install, always-latest (recommended)\nuvx --from git+https://github.com/escotilha/oxison oxison run /path/to/repo\n# pin to a release\npip install \"git+https://github.com/escotilha/oxison.git@v0.3.0\"\n```\n\nOr from a local clone:\n\n```bash\nuvx --from . oxison run /path/to/repo      # zero-install, from a clone\n# or\npip install -e . \u0026\u0026 oxison run /path/to/repo\n```\n\nRequires **Python ≥ 3.11** and the **Claude Code CLI** installed and signed in.\n\n## Auth\n\nBy default oxison uses your existing Claude Code login (OAuth) — nothing\nto configure. For CI, use `--bare` with `OXISON_API_KEY` or\n`ANTHROPIC_API_KEY`.\n\n## Model providers (Kimi, Grok)\n\noxison drives `claude -p`, which speaks the Anthropic Messages API — so any\nmodel with an **Anthropic-compatible endpoint** can run the whole pipeline.\nTwo are built in via `--provider`:\n\n```bash\nexport KIMI_API_KEY=...        # or MOONSHOT_API_KEY\noxison run /path/to/repo --provider kimi      # Kimi K2 (default model: kimi-k2.7-code)\n\nexport XAI_API_KEY=...          # or GROK_API_KEY\noxison run /path/to/repo --provider grok      # Grok (default model: grok-4.3)\noxison run /path/to/repo --provider grok --model grok-build-0.1   # agentic-build model\n```\n\n`--provider` works on every command — `run`, `plan`, `ideate`, and `build`. It\nreads the provider key from the env var shown (or `--api-key`), points the\nworker at the provider's endpoint via `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN`,\nand defaults the model to the provider's (override with `--model`). oxison never\nreads `ANTHROPIC_*` from your ambient environment — the provider overlay is\nconstructed only from your explicit `--provider` choice, so it can't silently\noverride a normal Anthropic run. For sandboxed `oxison build`, the provider's API\nhost is added to the worker egress allowlist automatically.\n\n## Usage\n\n```bash\noxison run /path/to/repo\noxison run /path/to/repo --output-dir ./docs\noxison run /path/to/repo --model claude-sonnet-4-6   # cheaper than the Opus default\noxison run /path/to/repo --max-budget-usd 5          # cap spend per AI call\noxison run /path/to/repo --resume                    # skip steps already completed\noxison run /path/to/repo --chunk-threshold 60000     # tune map-reduce cutover\n```\n\nRun `oxison run --help` for the full flag list.\n\n## Cost\n\noxison makes 5 AI calls for a small repo (comprehend + 3 docs + branch),\nmore for large repos (one comprehension worker per top-level directory +\na synthesis pass). It uses your Claude Code default model, which is\n**Opus** — powerful but pricey (~$1–2 per call). For routine runs, pass\n`--model claude-sonnet-4-6` and/or `--max-budget-usd` to cap spend. Every\ncall's cost is reported and recorded in `.oxison-run.json`.\n\n## Resume\n\nIf a run is interrupted (or you want to regenerate only part of it),\n`--resume` reads `.oxison-run.json` and skips steps already marked done.\nThe deterministic map always re-runs (it's free); cached AI steps are\nskipped.\n\n## Exit codes\n\n| Code | Meaning |\n|---|---|\n| 0 | success |\n| 2 | config error (bad target path, bad flag) |\n| 3 | preflight failed (Claude CLI missing / not authed) |\n| 4 | comprehension failed |\n| 5 | artifact generation failed |\n| 6 | branch (roadmap/security) failed |\n\n## Optional roadmap-parser enrichment\n\nIf a private `oxi_core` roadmap-parser package happens to be importable,\noxison opportunistically uses it to add structure to `ROADMAP-ANALYSIS.md`.\nIt is **not** a dependency and is not published; the roadmap analysis works\non any roadmap format via the AI pass regardless of whether it's present.\n\n## Run it from Claude Code (no terminal needed)\n\noxison ships as a [Claude Code](https://claude.com/claude-code) **plugin**, so\nyou can install and run it entirely from inside Claude Code — no shell, no\n`pip`, no `cp`. From any Claude Code session:\n\n```text\n/plugin marketplace add escotilha/oxison    # one time\n/plugin install oxison@oxison               # or pick it from the /plugin menu\n```\n\nThen just point it at a repo:\n\n```text\n/oxison /path/to/repo\n```\n\n…or simply ask **\"document this repo\"**. The skill resolves the `oxison` CLI\nitself (zero-install via `uvx` if it isn't already on your `PATH` — see\n[Install](#install)), defaults to Sonnet with a per-call budget cap for cost\nsafety, runs the read-only pipeline, and verifies the target repo was left\nuntouched after every run. Pass `--opus` for oxison's Opus default or\n`--full-budget` to drop the budget cap.\n\n\u003e Updates: leave it on auto-update, or run `/plugin marketplace update oxison`\n\u003e to pull the latest.\n\n\u003cdetails\u003e\n\u003csummary\u003eManual install (skill only, without the plugin system)\u003c/summary\u003e\n\nThe skill lives at [`skills/oxison/SKILL.md`](skills/oxison/SKILL.md). To install\nit directly instead of via the plugin:\n\n```bash\nmkdir -p ~/.claude/skills\ncp -r skills/oxison ~/.claude/skills/oxison\n```\n\n\u003c/details\u003e\n\n## Development\n\n```bash\nuv venv --python 3.12 \u0026\u0026 . .venv/bin/activate\nuv pip install -e \".[dev]\"\nruff check src tests \u0026\u0026 mypy src \u0026\u0026 pytest -q\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fescotilha%2Foxison","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fescotilha%2Foxison","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fescotilha%2Foxison/lists"}