{"id":51118884,"url":"https://github.com/ztxtech/aion","last_synced_at":"2026-06-25T00:30:26.419Z","repository":{"id":360349718,"uuid":"1208423362","full_name":"ztxtech/aion","owner":"ztxtech","description":"OpenCode-based time-series harness for structured forecasting, contextual reasoning, tool use, and validation-driven agent workflows.","archived":false,"fork":false,"pushed_at":"2026-06-17T14:25:48.000Z","size":11833,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-17T16:45:18.756Z","etag":null,"topics":["agent","ai","harness","ide","llm","loops","opencode","opencode-plugin","skills","time-series","tui","typescript","vibe-coding"],"latest_commit_sha":null,"homepage":"https://ztxtech.github.io/aion/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ztxtech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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-04-12T09:00:08.000Z","updated_at":"2026-06-17T14:27:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ztxtech/aion","commit_stats":null,"previous_names":["ztxtech/aion"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/ztxtech/aion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ztxtech%2Faion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ztxtech%2Faion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ztxtech%2Faion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ztxtech%2Faion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ztxtech","download_url":"https://codeload.github.com/ztxtech/aion/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ztxtech%2Faion/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34755061,"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-24T02:00:07.484Z","response_time":106,"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":["agent","ai","harness","ide","llm","loops","opencode","opencode-plugin","skills","time-series","tui","typescript","vibe-coding"],"created_at":"2026-06-25T00:30:25.697Z","updated_at":"2026-06-25T00:30:26.403Z","avatar_url":"https://github.com/ztxtech.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/ztxtech/aion\"\u003e\n    \u003cimg\n      src=\"https://readme-typing-svg.herokuapp.com?font=Fira+Code\u0026weight=700\u0026size=28\u0026duration=2800\u0026pause=900\u0026color=7C3AED\u0026center=true\u0026vCenter=true\u0026repeat=true\u0026width=720\u0026height=64\u0026lines=AION;Time-Series%20Harness%20for%20OpenCode;Task%20%E2%97%87%20Workspace%20%E2%97%87%20Execution%20%E2%97%87%20Review;Dual-Review%20Governance%20%C3%97%20Leakage%20Gate\"\n      alt=\"AION — Time-Series Harness\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.md\"\u003e\u003cstrong\u003eEnglish\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"README.zh-CN.md\"\u003e\u003cstrong\u003e简体中文\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## 📰 News\n\n- **2026-06-14** — AION is now a compiled TypeScript plugin for OpenCode (one-command install). The original Markdown-based configuration is preserved on the [`oc-conf`](https://github.com/ztxtech/aion/tree/oc-conf) branch.\n\n---\n\n**AION** is a time-series harness — an explicit control layer that connects task specification, runtime execution, and result assessment into one stable process for next-generation time-series workloads.\n\nTime-series research is moving beyond fixed forecasting benchmarks toward tasks that combine prediction, contextual reasoning, tool use, and structured decision support. AION formalizes these as triples of _task file, workspace, and validation interface_, and organizes the entire system around four stacked layers: **task** (what to solve), **workspace** (what evidence and tools are available), **execution** (how the system acts under constraints), and **review** (whether outputs pass validity, temporal, and completeness checks before progress is accepted).\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-quick-start\"\u003e\u003cimg src=\"https://img.shields.io/badge/Quick_Start-3_min-blue?style=for-the-badge\" alt=\"Quick Start\"\u003e\u003c/a\u003e\n  \u003ca href=\"#-four-layer-architecture\"\u003e\u003cimg src=\"https://img.shields.io/badge/Layers-4-10B981?style=for-the-badge\" alt=\"Layers\"\u003e\u003c/a\u003e\n  \u003ca href=\"#-skills\"\u003e\u003cimg src=\"https://img.shields.io/badge/Skills-17-8B5CF6?style=for-the-badge\" alt=\"Skills\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://arxiv.org/abs/2605.25045\"\u003e\u003cimg src=\"https://img.shields.io/badge/arXiv-2605.25045-B31B1B?style=for-the-badge\u0026logo=arxiv\u0026logoColor=white\" alt=\"arXiv\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/OpenCode-≥0.9-blue?logo=terminal\u0026logoColor=white\" alt=\"OpenCode\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-≥3.10-3776AB?logo=python\u0026logoColor=white\" alt=\"Python\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Multi_Agent-6_Roles-F59E0B?style=flat\" alt=\"Multi-Agent\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Tools-34-06B6D4?style=flat\" alt=\"Tools\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Protocols-8-06B6D4?style=flat\" alt=\"Protocols\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Evals-5_Gates-EC4899?style=flat\" alt=\"Evals\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Time_Series-Harness-7C3AED?style=flat\" alt=\"Time Series\"\u003e\n  \u003ca href=\"https://github.com/ztxtech/aion\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/ztxtech/aion?style=social\" alt=\"GitHub stars\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/github/last-commit/ztxtech/aion?color=orange\" alt=\"Last Commit\"\u003e\n  \u003ca href=\"https://deepwiki.com/ztxtech/aion\"\u003e\u003cimg src=\"https://deepwiki.com/badge.svg\" alt=\"Ask DeepWiki\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## ✨ What is AION?\n\nExisting benchmarks and agent-centered systems each capture only part of the shift toward next-generation time-series tasks: benchmarks usually simplify the task too early, while agents alone do not provide temporal contracts, evidence discipline, or reliable stopping criteria.\n\nAION addresses this gap as a **time-series harness** built on [OpenCode](https://github.com/anomalyco/opencode):\n\n- **Task layer** — Formalizes next-generation time-series tasks as triples of _task file, workspace, and validation interface_\n- **Workspace layer** — Provides structured evidence collection, tool orchestration, and persistent memory for open-ended research\n- **Execution layer** — Constrains multi-agent runtime with protocols, governance hierarchy, context compaction, and safety gates\n- **Review layer** — Enforces validity, temporal, and completeness checks before progress is accepted; no output leaves the system without passing layered critics\n\nTime-series specialization enters through **temporal grounding**, **knowledge-grounded search**, and **layered reliability checks**, allowing the system to work with open-ended evidence while preserving output legality and stop discipline.\n\n---\n\n## 🏗️ Four-Layer Architecture\n\nAION organizes everything around four stacked layers — each layer constrains the one below it: **task** (what to solve), **workspace** (what evidence and tools are available), **execution** (how the system acts under constraints), and **review** (whether outputs pass validity, temporal, and completeness checks before progress is accepted).\n\n### Project Structure (Plugin Version)\n\nAION is a compiled TypeScript plugin. The repository contains the source code; the build produces a self-contained bundle that gets installed into each project's `.opencode/plugins/` directory.\n\n**Repository layout:**\n\n```\naion/\n├── src/                        # TypeScript plugin source\n│   ├── index.ts                # Plugin entry point (default export)\n│   ├── plugin-interface.ts     # Assembles the PluginInstance for OpenCode\n│   ├── create-managers.ts      # Central state: governance, trace, phases\n│   ├── create-tools.ts         # Aggregates all AION tools\n│   ├── create-hooks.ts         # Aggregates all OpenCode hooks\n│   ├── workspace-bootstrap.ts  # On-disk workspace initializer\n│   ├── agents/                 # 6 agent factories\n│   │   ├── aion.ts             #   Main orchestrator (primary mode)\n│   │   ├── requirements-analyst.ts\n│   │   ├── information-collector.ts\n│   │   ├── coder.ts            #   Implementation workhorse\n│   │   ├── ts-critic.ts        #   Time-series + Pareto governor\n│   │   └── c-critic.ts         #   Final-gate cold-start critic\n│   ├── config/                 # Zod schema + config loader\n│   ├── hooks/                  # 11 OpenCode lifecycle hooks\n│   ├── tools/                  # 20 AION tools (critic, memory, safety...)\n│   ├── prompts/                # Governance constants + agent prompt loader\n│   └── shared/                 # Logger, JSONC parser, utils, personality\n├── bin/\n│   └── aion-init.js            # CLI installer (aion-ts init)\n├── scripts/\n│   ├── build.sh                # Build + pack release tarball\n│   └── install.sh              # curl-pipe-bash system installer\n├── .opencode/\n│   ├── skills/                 # 17 skill definitions (markdown)\n│   └── themes/aion.json        # AION TUI theme\n├── docs/                       # Documentation website\n├── example/                    # Ready-to-run examples\n├── package.json\n└── tsconfig.json\n```\n\n**After `aion-ts init` in your project:**\n\n```\nyour-project/\n├── .opencode/\n│   ├── plugins/\n│   │   └── aion.js             # Self-contained plugin bundle (auto-discovered)\n│   ├── themes/\n│   │   └── aion.json           # AION theme\n│   ├── aion.jsonc              # AION configuration (all features ON by default)\n│   └── memory/                 # Created at runtime (progress, decisions, etc.)\n└── opencode.json               # OpenCode config (theme, agents)\n```\n\nOpenCode auto-discovers plugins in `.opencode/plugins/` at startup — no global configuration is touched.\n\n---\n\n## 🚀 Quick Start\n\n### 0. Prerequisites\n\n| Command  | Used by                          | Notes                 |\n| -------- | -------------------------------- | --------------------- |\n| `node`   | Runs the `aion-ts` CLI           | ≥ 18 recommended      |\n| `curl`   | Download the installer           | Usually pre-installed |\n| `git`    | Local checkpoint history         | Usually pre-installed |\n| `python3`| Python toolchain, validators     | ≥ 3.10 recommended    |\n\n### 1. Install OpenCode\n\n```bash\n# YOLO\ncurl -fsSL https://opencode.ai/install | bash\n\n# Package managers\nnpm i -g opencode-ai@latest        # or bun/pnpm/yarn\nbrew install anomalyco/tap/opencode # macOS and Linux (recommended)\n```\n\n### 2. Configure OpenCode\n\n```bash\nopencode    # launch the TUI, then pick a provider and authenticate when prompted\n```\n\nSupports **Claude / OpenAI / Codex / Copilot / Gemini** and any compatible endpoint.\n\n### 3. Install the AION CLI\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/ztxtech/aion/dev/scripts/install.sh | bash\n```\n\nThis installs the `aion-ts` CLI to `~/.local/bin`. If that directory is not in your `PATH`, add it:\n\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"   # add to ~/.bashrc or ~/.zshrc\n```\n\n\u003e **During testing (no GitHub Release yet):** Build locally and install from the tarball:\n\u003e ```bash\n\u003e git clone -b dev https://github.com/ztxtech/aion.git \u0026\u0026 cd aion\n\u003e bash scripts/build.sh\n\u003e bash scripts/install.sh --local release/aion-plugin-0.1.0.tar.gz\n\u003e ```\n\n### 4. Add AION to Your Project\n\n```bash\ncd your-project\naion-ts init .\n```\n\nThis drops the plugin bundle into `.opencode/plugins/aion.js`, creates a starter `aion.jsonc` config, and copies the theme. The plugin is fully self-contained — **no `npm install` needed** in your project.\n\n### 5. Run\n\n```bash\n# Interactive TUI mode — pick your model in the TUI\nopencode\n\n# Non-interactive run mode\nopencode run --agent aion \"Your task description here\"\n\n# With a specific model\nopencode run --agent aion -m provider/model \"Analyze this time-series dataset\"\n```\n\n### Run Modes vs Execution Strategies\n\nOpenCode's `run` and `tui` describe the interface shape, not the same thing as how much the agent should ask the user.\n\n- **`run` + autonomous** (default) — The agent detects local context, picks the best path, and keeps going without pausing for routine choices.\n- **`tui` + autonomous** — The user is present and can observe, but the agent still makes routine decisions on its own.\n- **`tui` + interactive** — The user explicitly wants to co-decide important forks. The agent still does local detection first and only asks when multiple equally reasonable options remain.\n- **`run` + interactive** — Not a supported default. If the workflow should pause for user choices, use `tui` instead.\n\nAt session start, AION asks you (via OpenCode's built-in question popup) whether you want **interactive** or **autonomous** mode. You can also toggle mid-conversation by saying \"I'm leaving\" (→ autonomous) or \"switch to interactive\".\n\n---\n\n## 📦 Examples\n\nThe [`example/`](example/) directory contains ready-to-run workspaces that demonstrate AION end-to-end on concrete time-series tasks.\n\n\u003e **⚠️ Clinical disclaimer — `example/aion-medical-demo/` is a DEMONSTRATION only.** The ECG data is real but tiny (3 patients from PhysioNet PTB); the ICU vitals are synthetic. Models, metrics, and reports produced by the agent are demo artefacts — they are **not validated for clinical use**. See [`example/aion-medical-demo/README.md`](example/aion-medical-demo/README.md) for the full disclaimer.\n\n### Medical Time-Series Case — ECG Diagnosis \u0026 ICU Sepsis Onset (Demo)\n\n[`example/aion-medical-demo/`](example/aion-medical-demo/) wraps a clinical case in a recording-specific scaffold. The goal is to make every AION harness feature fire in a single run.\n\n```bash\ncd example/aion-medical-demo/medical\naion-ts init .\nopencode\n\u003e introduce yourself by completing this task, AION\n```\n\n### Local Kaggle-Like Forecasting Competition\n\n[`example/kaggle/`](example/kaggle/) is a local replica of the Kaggle **Store Sales - Time Series Forecasting** competition. A lightweight local evaluation server mimics the Kaggle submission and scoring API. See [`example/kaggle/README.md`](example/kaggle/README.md) for details.\n\n---\n\n## 🤝 Agent Roles\n\nAgents span all four layers — from task parsing through execution orchestration to layered review:\n\n| Agent                     | Primary Layer         | Role                                                                                           |\n| ------------------------- | --------------------- | ---------------------------------------------------------------------------------------------- |\n| **aion**                  | Execution             | Main orchestrator — dispatches subagents, enforces review gates, drives to close               |\n| **requirements-analyst**  | Task                  | Reads tasks \u0026 workspace materials, extracts goals, inputs \u0026 constraints                        |\n| **information-collector** | Workspace             | Supplements SOTA, top-venue papers, official implementations \u0026 domain knowledge                |\n| **coder**                 | Workspace + Execution | Implementation, experiments, delivery \u0026 visualization                                          |\n| **ts-critic**             | Review                | Time-series method review + Pareto stop/governance — highest governance gate before `c-critic` |\n| **c-critic**              | Review                | Final minimal-context cold-start critique — ultimate governance authority                      |\n\n### Governance Order\n\nIn blocker judgment, rebuttal verdicts, route rollback, stop-go, completion-gate, and final-delivery decisions:\n\n```\nc-critic \u003e ts-critic \u003e main agent \u003e other subagents\n```\n\nThe main agent owns **dispatch and execution**, but does **not** own a closeout authority above the critics.\n\n---\n\n## 🔧 Skills (17)\n\nSkills serve the workspace and execution layers — providing evidence collection, tool orchestration, and domain priors:\n\n| Skill                 | Layer     | Description                                           |\n| --------------------- | --------- | ----------------------------------------------------- |\n| **context-init**      | Workspace | Manual workspace bootstrap and task start             |\n| **workspace-init**    | Workspace | Automated workspace initialization and memory seeding |\n| **plan**              | Execution | Complex task planning with branch management          |\n| **brain-storm**       | Workspace | Multi-angle analysis with branch IDs                  |\n| **deep-reasoning**    | Execution | Multi-step reasoning with dependency chains           |\n| **critic-loop**       | Review    | Review and rollback judgment                          |\n| **time-series**       | Workspace | Unified time-series review framework                  |\n| **data-interface**    | Task      | 4-type data entry contract (file / DB / loader / API) |\n| **forecast-contract** | Review    | Forecast output controllability \u0026 validity checks     |\n| **report-writing**    | Workspace | Experiment reports and formal document output         |\n| **python-toolbox**    | Workspace | Python tool selection priors                          |\n| **ztxexp**            | Workspace | Experiment directory structure \u0026 plotting protocol    |\n| **github-search**     | Workspace | GitHub first-hand engineering evidence retrieval      |\n| **pdf-intake**        | Workspace | Safe PDF and scanned document extraction              |\n| **safety-gate**       | Review    | Automated safety pre-check                            |\n| **evolution**         | Execution | Capability gap detection → new agent/skill creation   |\n| **template**          | Workspace | Empty skill skeleton for new skills                   |\n\n---\n\n## 🛠️ Tools (20 AION)\n\nAION tools are programmable primitives invoked by the agents. All return JSON strings and are auto-traced.\n\n| Category | Tools | Purpose |\n| --- | --- | --- |\n| **Experiment** | `aion_ztxexp_init`, `aion_ztxexp_validate`, `aion_ztxexp_run` | Rigid 7-directory experiment boundary for reproducible ablations |\n| **Governance** | `aion_critic_dispatch`, `aion_critic_verdict`, `aion_record_blocker`, `aion_resolve_blocker`, `aion_pre_stop_gate` | Stop-go gate, blocker ledger, c-critic supremacy enforcement |\n| **Memory** | `aion_memory_sync`, `aion_workspace_init`, `aion_compaction` | Shared cache across agents, snapshot refresh |\n| **Safety** | `aion_safety_gate`, `aion_leakage_check` | Pre-action safety, leakage detection (hidden-set, future info, credentials) |\n| **Plan** | `aion_todo_update` | Plan-step ↔ OpenCode TODO mapping with stop-impact analysis |\n| **Session** | `aion_set_interactive_mode`, `aion_set_language` | User-mode toggles driven by session-start question |\n| **Hugging Face** | `aion_hf_search`, `aion_hf_info`, `aion_hf_ingest`, `aion_hf_suggest` | Zero-dependency HF Hub REST integration. Cached 24h under `.opencode/hf-cache/` |\n\n### Ablation \u0026 Statistical Rigor (HARD GATES)\n\nTwo rules in `rules.ts` cannot be bypassed:\n\n1. **Ablation is the SOLE arbiter of \"best method\"** — every \"X is best\" claim MUST be backed by a config-level ablation matrix inside `ztxexp` (≥3 seeds, single-factor toggles). c-critic rejects anecdotal / single-seed / leaderboard-only claims.\n2. **Beyond p-value: complementary analysis battery** — after significance + bootstrap CI, MUST also run SHAP (or equivalent feature attribution), residual structure diagnosis, drift analysis, and sensitivity analysis. Skipping any is a ts-critic blocker.\n\n---\n\n## 📋 Protocols (8)\n\nProtocols constrain the execution layer — governing how agents communicate, escalate, and compact context:\n\n| Protocol           | Purpose                                                                                        |\n| ------------------ | ---------------------------------------------------------------------------------------------- |\n| **dispatch**       | Subagent dispatch with context mode (`full_context` / `compacted_context` / `minimal_context`) |\n| **reportback**     | Structured report-back from subagents with self-critique                                       |\n| **rebuttal**       | Rebuttal protocol for route challenges                                                         |\n| **stop-go**        | Stop/go governance with critic conflict resolution                                             |\n| **lifecycle**      | Agent lifecycle management                                                                     |\n| **memory-sync**    | Memory synchronization across agents                                                           |\n| **runtime-events** | Runtime event tracking and trace updates                                                       |\n| **compaction**     | Context compaction for long-running multi-agent sessions                                       |\n\n---\n\n## 🧠 Memory \u0026 Trace\n\nAION maintains two complementary tracking systems across the workspace layer:\n\n- **`.opencode/trace.md`** — Per-task execution trace: key decisions, failure reviews, and delivery checkpoints\n- **`.opencode/memory/`** — Cross-task persistent memory: positive/negative findings, agent relationships, decisions, features\n- **`.opencode/memory/context-snapshot.md`** — Canonical compaction artifact derived from `initial-prompt`, `progress`, `decisions`, `todo-map`, and active blockers\n- **Local git** — Detail-level checkpoint history at the host project root (auto-initialized, never pushes)\n\nMemory and git serve different purposes: memory handles abstract experience and judgments; git handles detail-level changes and key-node replay.\n\n---\n\n## 📡 CLI Reference\n\n### `aion-ts` — Plugin Installer\n\nThe primary CLI for installing AION into a project:\n\n```bash\naion-ts init [target-dir] [--force]\n```\n\n| Flag            | Default     | Description                                                        |\n| --------------- | ----------- | ------------------------------------------------------------------ |\n| `target-dir`    | `.` (cwd)   | Directory to install into. Created if it does not exist.           |\n| `--force`, `-f` | (off)       | Overwrite an existing `.opencode/plugins/aion.js`.                 |\n| `--help`, `-h`  | —           | Show help.                                                         |\n\nWhat `init` does:\n1. Copies the plugin bundle to `\u003ctarget\u003e/.opencode/plugins/aion.js` (auto-discovered by OpenCode).\n2. Creates `\u003ctarget\u003e/opencode.json` if absent (minimal starter with `$schema` and theme).\n3. Copies a commented default config to `\u003ctarget\u003e/.opencode/aion.jsonc`.\n4. Copies the AION theme to `\u003ctarget\u003e/.opencode/themes/aion.json`.\n\nThe model is NOT set by `init` — you pick it in the OpenCode TUI at runtime.\n\nNothing outside `\u003ctarget\u003e` is touched.\n\n### `aion-ts datasets` — Hugging Face Datasets CLI\n\nMirror of the `aion_hf_*` tools. Lets you prep datasets without launching OpenCode. All commands support `--no-cache` to bypass the 24h HF cache (`.opencode/hf-cache/`).\n\n```bash\naion-ts datasets search \"ECG arrhythmia\" --limit 10 --modality timeseries\naion-ts datasets info Salesforce/lotsa_data\naion-ts datasets ingest Salesforce/lotsa_data --workspace . --split train\naion-ts datasets suggest --goal \"ECG anomaly detection\" --keywords \"ecg,arrhythmia\" --top-k 5\n```\n\n| Action     | Required args                              | Output |\n| ---------- | ------------------------------------------ | ------ |\n| `search`   | `\u003cquery\u003e`                                  | JSON: `{ query, count, results[] }` |\n| `info`     | `\u003cowner/name\u003e`                             | JSON: full dataset card + siblings + splits |\n| `ingest`   | `\u003cowner/name\u003e` `[--workspace DIR]` `[--split S]` | Writes `data/aion-dataset-manifest.json` + `data/\u003cid\u003e.loader.py` |\n| `suggest`  | `--goal \"...\"` `[--keywords k1,k2]` `[--modality M]` `[--top-k N]` | JSON: `{ goal, keywords, candidates[] }` ranked by score |\n\n### `cli.sh` — OpenCode Launcher (Legacy)\n\n`cli.sh` is a convenience wrapper around `opencode` for automated run-mode execution with auto-continue. It is optional — you can always use `opencode` directly.\n\n```bash\nbash cli.sh [OPTIONS]\n```\n\n| Flag                  | Default       | Description                                       |\n| --------------------- | ------------- | ------------------------------------------------- |\n| `--mode MODE`         | `run`         | Launch mode: `run` or `tui`                       |\n| `-m, --model MODEL`   | (from TUI)   | OpenCode model (format: `provider/model`)          |\n| `--max-continues N`   | `30`          | Max auto-continue rounds; `0` for unlimited       |\n| `--no-auto-continue`  | (off)         | Disable auto-continue after each round            |\n| `--debug`             | (off)         | Enable verbose debug logging                      |\n| `-h, --help`          | —             | Show help                                         |\n\n---\n\n## 🗑️ Uninstall\n\n### System-level (CLI + bundle)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/ztxtech/aion/dev/scripts/uninstall.sh | bash\n```\n\nRemoves `~/.local/bin/aion-ts` and `~/.local/lib/aion/`.\n\n### Project-level (also remove from a specific project)\n\n```bash\n# System + current project (backs up AION files before removal)\ncurl -fsSL https://raw.githubusercontent.com/ztxtech/aion/dev/scripts/uninstall.sh | bash -s -- --project .\n\n# Project only (keep the CLI installed)\ncurl -fsSL https://raw.githubusercontent.com/ztxtech/aion/dev/scripts/uninstall.sh | bash -s -- --project . --no-system\n```\n\nProject-level uninstall:\n- **Backs up** all AION-specific files to `.opencode/aion-backup-\u003ctimestamp\u003e.tar.gz` before removal\n- **Removes** `.opencode/plugins/aion.js`, `.opencode/themes/aion.json`, `.opencode/aion.jsonc`\n- **Cleans** `opencode.json` (removes `theme: \"aion\"`, keeps everything else)\n- **Does NOT touch** `.opencode/memory/`, `.opencode/trace.md`, `.opencode/skills/`, or any user data\n\nUse `--dry-run` to preview without removing:\n```bash\nbash scripts/uninstall.sh --project . --no-system --dry-run\n```\n\n---\n\n## 🔨 Building from Source\n\nFor contributors and local testing:\n\n```bash\ngit clone -b dev https://github.com/ztxtech/aion.git \u0026\u0026 cd aion\nnpm install\n\n# Build + pack a release tarball\nbash scripts/build.sh\n# → release/aion-plugin-0.1.0.tar.gz\n\n# Install from the local tarball\nbash scripts/install.sh --local release/aion-plugin-0.1.0.tar.gz\n```\n\n---\n\n## 🛡️ Key Constraints\n\nThe harness enforces hard boundaries across all four layers:\n\n- **No knowledge/data leakage** — Future information, labels, hidden-set content, and private data must never leak into features, code, logs, or outputs\n- **Ruthless skepticism** — A single success or metric gain is not proof of reliability; active investigation of leakage, spurious correlation, overfitting, and unverified assumptions is mandatory\n- **Governance hierarchy** — `c-critic \u003e ts-critic \u003e main agent \u003e others` in all governance decisions; main agent cannot override critic blockers\n- **Mutually exclusive delegation first** — As long as an existing role already covers a class of work, the main agent should delegate it by default instead of doing it directly\n- **Benchmark-first** — Tasks with leaderboards or competitions must maintain parallel branches: self-exploration + top-solution reverse-engineering\n- **Mermaid-only diagrams** — All structural diagrams must use Mermaid; ASCII/plain-text diagrams are forbidden in formal outputs\n- **Workspace cleanup** — Empty directories, temp files, and debug residue must be cleaned before final delivery\n\n---\n\n## 🤝 Acknowledgements\n\nAION is a time-series harness built on top of the open-source community. We gratefully acknowledge the following projects, which made this work possible:\n\n- [OpenCode](https://github.com/anomalyco/opencode) — the open-source AI coding agent that AION is built on\n- [Awesome-Agentic-Time-Series](https://github.com/TROUBADOUR000/Awesome-Agentic-Time-Series) — a curated resource list of agentic time-series research\n- [TSFpaper](https://github.com/ddz16/TSFpaper) — a comprehensive collection of time-series forecasting papers\n\n---\n\n## 📝 Citation\n\nIf you use AION in your research, please cite:\n\n```bibtex\n@misc{zhan2026aion,\n      title={AION: Next-Generation Tasks and Practical Harness for Time Series},\n      author={Tianxiang Zhan and Xiaobao Song and Tong Guan and Shirui Pan and Ming Jin},\n      year={2026},\n      eprint={2605.25045},\n      archivePrefix={arXiv},\n      url={https://arxiv.org/abs/2605.25045},\n}\n```\n\n---\n\n## 🤝 Contributing\n\nAION is a community-driven research project. We welcome contributions from researchers, engineers, and domain practitioners — but please follow the process below so we can review your work quickly and keep the project healthy.\n\n**Before you start**\n\n- **Read** [`CONTRIBUTING.md`](./CONTRIBUTING.md) — it covers the dev setup, coding conventions, and the PR process.\n- **Open an issue first** for non-trivial changes (new agents, skills, tools, hooks, protocols, eval suites, governance changes). Use the **Component Proposal** template so the maintainers can sanity-check the fit in the four-layer architecture before any code is written.\n- **Bug reports and small fixes** can go straight to a PR with the **Bug Report** / **Documentation** issue template.\n\n**Contribution areas**\n\n| Area          | Examples                                                       |\n| ------------- | -------------------------------------------------------------- |\n| **Agents**    | New specialized agent roles                                    |\n| **Skills**    | Domain knowledge `.md` files (finance, climate, healthcare...) |\n| **Tools**     | New AION tools (TypeScript)                                    |\n| **Hooks**     | New OpenCode lifecycle hooks (TypeScript)                      |\n| **Protocols** | New coordination or governance patterns                        |\n| **Evals**     | Suite definitions, graders, scorecards                         |\n\n**When you open a PR**\n\n- Fill in the **PR template** completely, including the *Governance Impact* and *Four-Layer Impact* sections.\n- Run `bun run typecheck` and `bun run test:all` locally — both must pass (574/574 baseline).\n- If your change is user-facing, mirror it in **both** `README.md` and `README.zh-CN.md` in the same PR.\n- Tag the relevant maintainer(s) and be ready to iterate.\n\n**Community norms**\n\nThis project follows the [Code of Conduct](./CODE_OF_CONDUCT.md). Security issues are handled via [`SECURITY.md`](./SECURITY.md), not public issues.\n\n---\n\n## 📄 License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAION\u003c/strong\u003e\u003cbr\u003e\n  \u003cem\u003eNext Generation Tasks and Practical Harness for Time Series\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://star-history.com/#ztxtech/aion\u0026Date\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=ztxtech/aion\u0026type=Date\u0026theme=dark\" /\u003e\n      \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=ztxtech/aion\u0026type=Date\" /\u003e\n      \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=ztxtech/aion\u0026type=Date\" style=\"border-radius: 15px; box-shadow: 0 0 30px rgba(124, 58, 237, 0.3);\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eThanks for visiting AION!\u003c/em\u003e\u003cbr\u003e\n  \u003cimg src=\"https://visitor-badge.laobi.icu/badge?page_id=ztxtech.aion\u0026style=for-the-badge\u0026color=7C3AED\" alt=\"Views\"\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fztxtech%2Faion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fztxtech%2Faion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fztxtech%2Faion/lists"}