{"id":51183055,"url":"https://github.com/carrilloapps/hfo","last_synced_at":"2026-06-27T08:02:39.463Z","repository":{"id":353398509,"uuid":"1219153863","full_name":"carrilloapps/hfo","owner":"carrilloapps","description":"Fullscreen TUI and headless CLI for Hugging Face GGUF models on Ollama, auto-tuned to your hardware.","archived":false,"fork":false,"pushed_at":"2026-04-23T18:49:39.000Z","size":209,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-23T19:29:37.144Z","etag":null,"topics":["claude-code","cli","codex","gguf","huggingface","ink","llm","local-llm","ollama","terminal","tui","typescript"],"latest_commit_sha":null,"homepage":"https://hfo.carrillo.app","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/carrilloapps.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":".github/SUPPORT.md","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},"funding":{"custom":["https://carrillo.app"]}},"created_at":"2026-04-23T15:27:42.000Z","updated_at":"2026-04-23T18:49:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/carrilloapps/hfo","commit_stats":null,"previous_names":["carrilloapps/hfo"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/carrilloapps/hfo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carrilloapps%2Fhfo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carrilloapps%2Fhfo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carrilloapps%2Fhfo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carrilloapps%2Fhfo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carrilloapps","download_url":"https://codeload.github.com/carrilloapps/hfo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carrilloapps%2Fhfo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34845749,"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-27T02:00:06.362Z","response_time":126,"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":["claude-code","cli","codex","gguf","huggingface","ink","llm","local-llm","ollama","terminal","tui","typescript"],"created_at":"2026-06-27T08:02:38.654Z","updated_at":"2026-06-27T08:02:39.450Z","avatar_url":"https://github.com/carrilloapps.png","language":"TypeScript","funding_links":["https://carrillo.app"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ca href=\"https://hfo.carrillo.app\" target=\"_blank\" rel=\"noopener\"\u003e\n  \u003cimg src=\"./docs/assets/logo-wordmark.svg\" alt=\"hfo\" width=\"220\" /\u003e\n\u003c/a\u003e\n\n\u003ch3\u003eHugging\u0026nbsp;Face\u0026nbsp;·\u0026nbsp;Ollama, in your terminal.\u003c/h3\u003e\n\n\u003cp\u003e\n  \u003cstrong\u003eTurn any Hugging\u0026nbsp;Face GGUF repo into a running, hardware-tuned Ollama model — in three keystrokes.\u003c/strong\u003e\u003cbr/\u003e\n  A fullscreen TUI and a headless CLI with no telemetry, no accounts, no subscriptions.\u003cbr/\u003e\n  Cross-OS. Strict TypeScript. MIT.\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://www.npmjs.com/package/hfo-cli\"\u003e\u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/v/hfo-cli?style=for-the-badge\u0026logo=npm\u0026logoColor=white\u0026color=7C5BF3\u0026labelColor=0a0b0f\u0026label=npm\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/carrilloapps/hfo/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/carrilloapps/hfo/ci.yml?branch=main\u0026style=for-the-badge\u0026logo=githubactions\u0026logoColor=white\u0026color=5ED7A8\u0026labelColor=0a0b0f\u0026label=CI\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org\"\u003e\u003cimg alt=\"node\" src=\"https://img.shields.io/node/v/hfo-cli?style=for-the-badge\u0026logo=nodedotjs\u0026logoColor=white\u0026color=3B6FE5\u0026labelColor=0a0b0f\"/\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg alt=\"license\" src=\"https://img.shields.io/npm/l/hfo-cli?style=for-the-badge\u0026color=FFD766\u0026labelColor=0a0b0f\"/\u003e\u003c/a\u003e\n  \u003ca href=\"./tsconfig.json\"\u003e\u003cimg alt=\"typescript strict\" src=\"https://img.shields.io/badge/TypeScript-strict-3178C6?style=for-the-badge\u0026logo=typescript\u0026logoColor=white\u0026labelColor=0a0b0f\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://hfo.carrillo.app\"\u003e\u003cstrong\u003eWebsite\u003c/strong\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://www.npmjs.com/package/hfo-cli\"\u003e\u003cstrong\u003enpm\u003c/strong\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://github.com/carrilloapps/hfo/releases\"\u003e\u003cstrong\u003eReleases\u003c/strong\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://github.com/carrilloapps/hfo/issues\"\u003e\u003cstrong\u003eIssues\u003c/strong\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"./CHANGELOG.md\"\u003e\u003cstrong\u003eChangelog\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n```console\n$ npm i -g hfo-cli\n$ hfo bartowski/Qwen2.5-Coder-7B-Instruct-GGUF\n→ RTX 4090 · 24 GiB VRAM · 64 GiB RAM\n→ scoring 8 quants…  Q6_K 97/100  ·  Q5_K_M 94/100\n\n? Install Q6_K → ~/AI/LLMs/qwen2-5-coder/q6-k  [Enter]\n```\n\n\u003e **Three keystrokes, no Modelfile by hand.** Pick a quant, press \u003ckbd\u003eEnter\u003c/kbd\u003e, wait for the download. Every TUI action has a headless flag so the same pipeline runs in CI, cron, or an editor plugin.\n\n---\n\n## Table of contents\n\n- [Why](#why)\n- [Install](#install)\n- [Quick start](#quick-start)\n- [Features](#features)\n- [CLI reference](#cli-reference)\n- [Keyboard reference](#keyboard-reference)\n- [Configuration](#configuration)\n- [Architecture](#architecture)\n- [Development](#development)\n- [Privacy, security, cost](#privacy-security-cost)\n- [Roadmap](#roadmap)\n- [Author](#author)\n- [License](#license)\n\n## Why\n\nRunning open-weight LLMs locally via Ollama is powerful but punishingly repetitive:\n\n1. Browse Hugging Face. Pick a repo. Eyeball the quant table.\n2. Guess which quant fits your VRAM. Read the card for temperature / top_p hints.\n3. Download the `.gguf`. Hand-write a `Modelfile`. `ollama create` it.\n4. Tune env vars (`OLLAMA_FLASH_ATTENTION`, `OLLAMA_KV_CACHE_TYPE`, …) differently on every OS.\n5. Back it up. Restore it. Manage a dozen tags. Hand it off to Claude Code or Codex.\n\n`hfo` collapses that into a single session. It reads your rig, scores every quant in the repo\nagainst your VRAM and RAM, parses the model card for recommended sampling parameters, and — on the\nhappy path — installs a ready-to-run model with **one Enter keystroke**. Every TUI capability has a\nnon-interactive flag so you can script the same pipeline from CI, cron, or an editor plugin.\n\nIt is written in **strict TypeScript**, runs on **Windows / macOS / Linux**, talks only to the\npublic Hugging Face API and your local Ollama daemon, and ships as both an **npm package** and\n**standalone binaries** for each OS.\n\n## How it runs\n\nTwo entry points share the same engine — the fullscreen TUI for interactive\nexploration and headless flags for scripts, cron, and editor plugins. Both\nshells read the same settings file, write the same backup format, and invoke\nthe same Ollama commands underneath.\n\n```mermaid\nflowchart LR\n    A[hfo CLI] --\u003e B{argv?}\n    B --\u003e|--view, --list, --backup,\u003cbr/\u003e--restore, --tune, --delete,\u003cbr/\u003e--launch| C[Headless dispatch]\n    B --\u003e|no flag, or URL / --tab| D[Fullscreen TUI]\n    C --\u003e E[Plain stdout + exit code]\n    D --\u003e F[Alt-screen buffer]\n    F --\u003e G[Dashboard · Models · Install ·\u003cbr/\u003eTune · Help · Settings]\n    G --\u003e H[Optional handoff to\u003cbr/\u003eollama launch\u003cbr/\u003eon exit]\n    C -.reads.-\u003e S[(settings.json)]\n    D -.reads + writes.-\u003e S\n    C -.calls.-\u003e O[(Ollama daemon)]\n    D -.calls.-\u003e O\n    C -.GET.-\u003e HF[(huggingface.co public API)]\n    D -.GET.-\u003e HF\n```\n\n## Install\n\n### One-liner scripts (no Node required)\n\n```sh\n# macOS / Linux — detects OS + arch, installs to /usr/local/bin or ~/.local/bin.\ncurl -fsSL https://hfo.carrillo.app/install.sh | sh\n```\n\n```powershell\n# Windows PowerShell — installs to %LOCALAPPDATA%\\Programs\\hfo and adds it\n# to your user PATH. No admin prompt required.\nirm https://hfo.carrillo.app/install.ps1 | iex\n```\n\nBoth scripts always pull the **latest GitHub Release** binary for your\nplatform. Override with `HFO_VERSION=v0.2.0` (or `$env:HFO_VERSION`) to\npin a specific tag, or `HFO_INSTALL_DIR=/some/dir` to relocate.\n\n\u003e **Binaries are built and published only when a `v*.*.*` tag is pushed**,\n\u003e never on regular commits. Every-commit CI runs only typecheck, lint,\n\u003e test and build.\n\n### Package managers\n\nPick the one you already have. All four ship the same `hfo-cli` package\nfrom the npm registry.\n\n```bash\nnpm  i   -g hfo-cli\npnpm add -g hfo-cli\nyarn global add hfo-cli\nbun  add -g hfo-cli\n```\n\nRequires Node.js **≥ 20**. Ollama is optional — `hfo` will install it for\nyou via `winget`, `brew`, or the official shell script if it isn't\nalready on your PATH.\n\n### Standalone binaries\n\nEach tagged release on GitHub publishes self-contained executables you\ncan drop straight onto your PATH:\n\n| Asset                | OS · Arch                     |\n| -------------------- | ----------------------------- |\n| `hfo-linux-x64`      | Linux x64                     |\n| `hfo-linux-arm64`    | Linux arm64                   |\n| `hfo-macos-x64`      | macOS x64 (Intel)             |\n| `hfo-macos-arm64`    | macOS arm64 (Apple Silicon)   |\n| `hfo-win-x64.exe`    | Windows x64                   |\n\nDownload directly from the\n[Releases](https://github.com/carrilloapps/hfo/releases) page, make it\nexecutable, and put it on your PATH — no Node runtime required. The\none-liner scripts above wrap exactly this flow for you.\n\n## Quick start\n\n```bash\n# Explore — fullscreen dashboard: hardware, capacity, picks, live metrics\nhfo\n\n# Install a specific repo (opens the Install tab pre-filled)\nhfo bartowski/Llama-3.2-3B-Instruct-GGUF\n\n# One-keystroke install, no TUI\nhfo --view\nhfo bartowski/Qwen2.5-Coder-7B-Instruct-GGUF --code\n# (the new quick-confirm screen auto-accepts with Enter)\n\n# Launch a coding agent wired to a local model\nhfo --launch claude --model llama3.1:8b\n\n# Back up a model folder\nhfo --backup qwen2-5-coder-7b:q4-k-m\n\n# Restore it later\nhfo --restore ~/.config/hfo/backups/2026-04-23_11-48-25/qwen2-5-coder-7b_q4-k-m.zip\n```\n\n## Install flow (at a glance)\n\nOn the happy path a new install is three keystrokes: pick the quant, press\nEnter, wait for the download. Conflicts and customisations branch off into\ntheir own screens — no mandatory detours when there's nothing to decide.\n\n```mermaid\nstateDiagram-v2\n    [*] --\u003e Probing\n    Probing --\u003e OllamaMissing: ollama absent\n    OllamaMissing --\u003e OfferTune: installed + reachable\n    Probing --\u003e OfferTune: ollama ok\n    OfferTune --\u003e LoadingRepo\n    LoadingRepo --\u003e Scored: repo + card + quant scores\n    Scored --\u003e QuantsPicked: user selects quant(s)\n\n    state if_conflict \u003c\u003cchoice\u003e\u003e\n    QuantsPicked --\u003e if_conflict\n    if_conflict --\u003e QuickConfirm: single quant, no conflicts\n    if_conflict --\u003e Reviewing: multi-quant OR tag/file conflicts\n\n    QuickConfirm --\u003e Processing: Enter (recommended defaults)\n    QuickConfirm --\u003e ChangeDir: O (file browser)\n    QuickConfirm --\u003e ParamsEditing: C (customize)\n    QuickConfirm --\u003e Scored: Esc\n\n    ChangeDir --\u003e QuickConfirm: new dir chosen\n    Reviewing --\u003e Processing: confirm plans\n    ParamsEditing --\u003e Processing: save\n    Processing --\u003e Installed\n    Installed --\u003e Done: launch or skip\n    Done --\u003e [*]\n```\n\n## Features\n\n- **Fullscreen TUI with six tabs.** Dashboard (live GPU / VRAM / RAM meters + loaded models +\n  capacity tier), Models (installed + orphan-available-to-reinstall + loaded status), Install\n  (quant picker + quick-confirm + file browser + plan reviewer + parameter editor), Tune\n  (default vs suggested vs current env table), Help, and Settings.\n- **Hardware scoring.** Every GGUF is graded 0–100 against your usable VRAM (GPU reserve subtracted)\n  and RAM headroom, with per-quant labels like `Full GPU`, `Partial 87%`, `CPU-heavy`.\n- **HF model-card parameters.** The README is parsed for recommended `temperature`, `top_p`,\n  `top_k`, `repeat_penalty`, `min_p`, and context size — overlaid onto your hardware-tuned\n  defaults, with a star marker on rows the card contributed.\n- **Quick-confirm install.** New in this release: if the picked quant has no tag or directory\n  conflicts, the install collapses to a single \"Enter to install / O to change dir / C to\n  customize\" screen. Three-keystroke flow end to end.\n- **Orphan reinstall.** Tags removed from Ollama but whose GGUFs still live on disk appear in a\n  separate \"Available to reinstall\" section. `I` regenerates the Modelfile from the GGUF alone\n  using your hardware + HF card and re-registers with Ollama.\n- **Zip backup + restore.** Level-9 compression, streaming (multi-GB safe), metadata sidecar.\n  `B` zips a model; `hfo --restore \u003czip\u003e` extracts and re-registers, regenerating the Modelfile\n  if needed.\n- **Deep delete.** `d` removes the Ollama tag only; `Alt+d` also wipes the tracked directory.\n- **Launch integrations.** Press `L` on any model to run `ollama launch \u003cintegration\u003e` with that\n  model as the backend. Supports Claude Code, Cline, Codex, Copilot CLI, Droid, Hermes, Kimi,\n  OpenCode, OpenClaw, Pi, and VS Code, with runtime probing against `ollama launch --help` to\n  mark unsupported targets.\n- **~90% capacity tuner.** Side-by-side default / suggested / current for\n  `OLLAMA_FLASH_ATTENTION`, `OLLAMA_KV_CACHE_TYPE`, `OLLAMA_KEEP_ALIVE`, `OLLAMA_NUM_PARALLEL`,\n  `OLLAMA_MAX_LOADED_MODELS`, `OLLAMA_MAX_QUEUE`. Persists via `setx` on Windows,\n  `launchctl setenv` + `~/.zprofile` on macOS, and `~/.profile` + `systemd` override on Linux.\n- **Seven themes, 20 languages.** Dark, Light, Dracula, Solarized Dark/Light, Nord, Monokai.\n  Translations in English, Spanish, Chinese, Hindi, Arabic, Portuguese, Bengali, Russian,\n  Japanese, German, French, Korean, Italian, Turkish, Vietnamese, Indonesian, Polish, Dutch,\n  Thai, and Ukrainian. Live language switching from the Settings tab.\n- **Reusable searchable dropdown.** Themes, languages, and sort-order pickers all use the same\n  keyboard-driven component — type to filter, arrow to nav, Enter to select.\n\n## CLI reference\n\nEvery TUI capability ships a headless flag equivalent that prints plain text and exits with a\nnon-zero status on failure.\n\n| Command | Description |\n| ------- | ----------- |\n| `hfo` | Open the fullscreen TUI (Dashboard tab) |\n| `hfo \u003chf-url-or-repo\u003e` | Open the TUI pre-filled on the Install tab |\n| `hfo --help` / `-h` | Print the full flag reference |\n| `hfo --version` | Print `hfo vX.Y.Z · MIT · \u003cauthor\u003e` |\n| `hfo --view` | Print hardware profile, capacity score, tier, picks, pre-filtered HF search URLs |\n| `hfo --list` | List installed models + orphaned GGUFs on disk |\n| `hfo --tune` | Persist the ~90% capacity Ollama env profile, then restart the daemon |\n| `hfo --backup \u003ctag\u003e` | Create a `.zip` backup of the model's folder with level-9 compression |\n| `hfo --restore \u003czip\u003e` | Extract a backup, regenerate the Modelfile if needed, re-register with Ollama |\n| `hfo --delete \u003ctag\u003e` | Remove the tag from Ollama (shallow) |\n| `hfo --delete \u003ctag\u003e --deep` | Remove the tag AND delete its on-disk folder |\n| `hfo --launch \u003cintegration\u003e` | Run `ollama launch \u003cintegration\u003e` with the given model as backend |\n| `hfo --tab \u003cname\u003e` | Open the TUI on `dashboard` · `models` · `install` · `tune` · `help` · `settings` |\n\nAdditional flags:\n\n| Flag | Description |\n| ---- | ----------- |\n| `--dir`, `-d` | Base directory for the install file browser (default: `settings.modelDir` → `process.cwd()`) |\n| `--token`, `-t` | Hugging Face token for gated/private repos (or set `$HF_TOKEN`) |\n| `--code`, `-c` | Mark the install as code-specialized (adjusts SYSTEM prompt) |\n| `--ctx` | Force context size (default: auto — 8192 if fits in VRAM, else 4096) |\n| `--model` | Model tag to pass to `--launch` |\n| `--deep` | Deep-delete alongside `--delete` |\n| `--no-fullscreen` | Disable the alt-screen buffer (helpful on legacy terminals) |\n\n## Keyboard reference\n\n| Scope | Keys | Action |\n| ----- | ---- | ------ |\n| Global | `1`–`6` | Jump to a tab |\n| Global | `Tab` / `Shift+Tab` | Cycle tabs |\n| Global | `,` | Open Settings |\n| Global | `?` | Open Help |\n| Global | `Ctrl+H` | Open the author's homepage |\n| Global | `q` · `Ctrl+C` | Quit (restores scrollback) |\n| Dashboard | `Alt+↑` · `Alt+↓` | Focus / cycle panels |\n| Dashboard | `Esc` · `b` | Return to the 4-panel grid |\n| Dashboard | `Enter` | Open the selected link in the default browser |\n| Dashboard | `r` | Force refresh |\n| Models | `↑` `↓` | Navigate rows |\n| Models | `L` / `G` | Launch integration with selected model / Launch menu without preset |\n| Models | `I` | Reinstall an orphan (regenerates Modelfile if missing) |\n| Models | `B` | Create a `.zip` backup |\n| Models | `d` / `Alt+d` | Remove tag / Remove tag AND delete files |\n| Models | `r` | Refresh |\n| Install (quick-confirm) | `Enter` | Install now with recommended defaults |\n| Install (quick-confirm) | `O` | Change target directory |\n| Install (quick-confirm) | `C` | Customize Modelfile parameters |\n| Install (quick-confirm) | `Esc` | Back to the quant picker |\n| Tune | `↑↓` · `←→` | Navigate rows · cycle enum values |\n| Tune | `E` · `D` · `S` · `R` · `X` · `A` | Edit freely · Default · Suggested · Reset→suggested · Reset→defaults · Apply |\n| Settings | `Enter` | Open dropdown (themes / 20 languages, searchable) |\n\n## Configuration\n\n`hfo` persists a JSON settings file under the OS-appropriate config directory:\n\n- **Windows** — `%APPDATA%\\hfo\\settings.json`\n- **macOS** — `~/Library/Application Support/hfo/settings.json`\n- **Linux** — `$XDG_CONFIG_HOME/hfo/settings.json` (defaults to `~/.config/hfo/`)\n\nSchema:\n\n```ts\ninterface Settings {\n  theme: 'dark' | 'light' | 'dracula' | 'solarized-dark' | 'solarized-light' | 'nord' | 'monokai';\n  language: 'en' | 'es' | 'zh' | 'hi' | 'ar' | 'pt' | 'bn' | 'ru' | 'ja' | 'de'\n          | 'fr' | 'ko' | 'it' | 'tr' | 'vi' | 'id' | 'pl' | 'nl' | 'th' | 'uk';\n  refreshIntervalMs: number;         // Dashboard polling cadence\n  defaultSort: 'trending' | 'downloads' | 'likes7d' | 'modified';\n  defaultCodeMode: boolean;\n  modelDir: string | null;           // null = current working directory at launch (self-contained)\n  useAltScreen: boolean;\n  installations: Installation[];     // { tag, dir, repoId, quant, installedAt }\n}\n```\n\nBackups are written under `\u003cconfigDir\u003e/hfo/backups/\u003ctimestamp\u003e/\u003cslug\u003e.zip` with a sidecar\n`.metadata.json` containing tag, repo, quant, byte counts, and compression ratio.\n\n## Architecture\n\nModule layout, grouped by concern. Tests live under `test/`, UI components\nunder `src/components/`, tab containers under `src/tabs/`, everything else is\npure TypeScript suitable for unit testing and reuse.\n\n```mermaid\ngraph TB\n    subgraph Entry[\"Entry points\"]\n      CLI[cli.tsx]\n      Shell[Shell.tsx]\n      Headless[headless.ts]\n    end\n\n    subgraph Flow[\"Install flow state machine\"]\n      App[App.tsx]\n      QuickConfirm[components/QuickConfirm]\n      Planner[plan.ts]\n      Reviewer[components/PlanReviewer]\n      ParamsEditor[components/ParamsEditor]\n      Processor[components/Processor]\n    end\n\n    subgraph Domain[\"Pure-logic modules\"]\n      HF[hf.ts]\n      HW[hardware.ts]\n      Scoring[scoring.ts]\n      Capacity[capacity.ts]\n      Readme[readme.ts]\n      Modelfile[modelfile.ts]\n      Describe[describe.ts]\n      Backup[backup.ts]\n      Restore[restore.ts]\n      Reinstall[reinstall.ts]\n      Launch[launch.ts]\n    end\n\n    subgraph Infra[\"Cross-OS infra\"]\n      Ollama[ollama.ts]\n      Platform[platform.ts]\n      Settings[settings.ts]\n      Live[live.ts]\n      Theme[theme.ts]\n      I18n[i18n.ts]\n    end\n\n    CLI --\u003e Shell\n    CLI --\u003e Headless\n    Shell --\u003e App\n    Shell --\u003e Settings\n    App --\u003e QuickConfirm\n    App --\u003e Planner\n    App --\u003e Reviewer\n    App --\u003e ParamsEditor\n    App --\u003e Processor\n    Processor --\u003e HF\n    Processor --\u003e Modelfile\n    Processor --\u003e Ollama\n    Processor --\u003e Settings\n    Planner --\u003e HF\n    Planner --\u003e Ollama\n    Scoring --\u003e HF\n    Capacity --\u003e HW\n    App --\u003e Scoring\n    App --\u003e Capacity\n    App --\u003e Readme\n    Headless --\u003e Backup\n    Headless --\u003e Restore\n    Headless --\u003e Reinstall\n    Headless --\u003e Launch\n    Headless --\u003e HW\n    Headless --\u003e Ollama\n    Backup --\u003e Settings\n    Restore --\u003e Reinstall\n    Reinstall --\u003e Scoring\n    Reinstall --\u003e Modelfile\n    Shell --\u003e Live\n    Shell --\u003e Theme\n    Shell --\u003e I18n\n```\n\n## Layout\n\n```\nhfo/\n├─ .github/                    # Community health + CI/CD\n│  ├─ ISSUE_TEMPLATE/           #   bug_report.yml · feature_request.yml · config.yml\n│  ├─ workflows/                #   ci.yml (every push) · pages.yml (docs) · release.yml (tags only)\n│  ├─ CODEOWNERS · FUNDING.yml · dependabot.yml · SUPPORT.md · PULL_REQUEST_TEMPLATE.md\n├─ bin/hfo.js                  # npm bin entrypoint → dist/cli.js\n├─ docs/                       # Static site deployed at hfo.carrillo.app\n│  ├─ .well-known/security.txt  #   RFC 9116 disclosure contact\n│  ├─ assets/                   #   logo-mark.svg · logo-wordmark.svg · og-image.svg\n│  ├─ 404.html                  #   Not-found page sharing the site design\n│  ├─ CNAME · humans.txt · robots.txt · sitemap.xml · manifest.webmanifest\n│  ├─ install.sh · install.ps1  #   One-liner installers (hfo.carrillo.app/install.*)\n│  └─ index.html                #   Landing: Hero · Features · Install · CLI · Kb · FAQ\n├─ scripts/\n│  ├─ generate-favicons.mjs     # SVG → PNG/ICO + og.png, invoked by the Pages workflow\n│  └─ install-skills.mjs        # `pnpm run skills:install`\n├─ src/                        # Strict-TypeScript source — grouped by layer\n│  ├─ cli.tsx                   # Entry points (stay at root — framework hooks use)\n│  ├─ Shell.tsx                 #   argv + headless dispatch · 6-tab router · install FSM\n│  ├─ App.tsx                   #   non-interactive command dispatch\n│  ├─ headless.ts\n│  ├─ core/                    # Pure domain logic — zero UI, zero OS side effects\n│  │  ├─ hf.ts                  #   public HF API client + resumable downloader\n│  │  ├─ hardware.ts            #   nvidia-smi + systeminformation probes\n│  │  ├─ live.ts                #   real-time samplers for the Dashboard\n│  │  ├─ scoring.ts             #   per-quant compatibility 0-100\n│  │  ├─ capacity.ts            #   rig tier + picks + HF search URLs\n│  │  ├─ readme.ts              #   HF model-card parser\n│  │  ├─ plan.ts                #   install plans + conflict detection\n│  │  ├─ modelfile.ts           #   Modelfile generator + tag slugifier\n│  │  ├─ reinstall.ts           #   orphan detection + Modelfile regeneration\n│  │  ├─ backup.ts              #   archiver-based zip writer + metadata sidecar\n│  │  ├─ restore.ts             #   adm-zip reader + reinstall handoff\n│  │  ├─ launch.ts              #   ollama launch targets + runtime probing\n│  │  └─ describe.ts            #   quant flavour + modality detection\n│  ├─ infra/                   # Cross-OS platform integration\n│  │  ├─ ollama.ts              #   Ollama CLI wrappers + env persistence (setx/launchctl/systemd)\n│  │  ├─ platform.ts            #   openUrl + config paths (Windows / macOS / Linux)\n│  │  ├─ settings.ts            #   persisted preferences + installations index\n│  │  └─ about.ts               #   package.json metadata loader\n│  ├─ ui/                      # UI-layer primitives consumed by tabs/ + components/\n│  │  ├─ theme.ts               #   7-theme registry with contrast pairs\n│  │  ├─ i18n.ts                #   20-language translation catalogs\n│  │  ├─ icons.ts               #   figures-backed icon set\n│  │  ├─ hooks.ts               #   useTerminalSize · useInterval · useNow\n│  │  └─ format.ts              #   byte / ETA / progress-bar formatters\n│  ├─ tabs/                    #   Dashboard · Models · Install · Tune · Help · Settings\n│  └─ components/              #   Dropdown · QuickConfirm · BootScreen · PlanReviewer · ParamsEditor · FileBrowser · LaunchMenu · …\n├─ test/                       # 12 vitest suites · 71 tests · v8 coverage\n├─ CHANGELOG.md · CODE_OF_CONDUCT.md · CONTRIBUTING.md · LICENSE · README.md · SECURITY.md\n├─ eslint.config.js · tsconfig.json · vitest.config.ts\n└─ package.json                # packageManager pinned; pkg config for binaries\n```\n\n## Development\n\n```bash\ngit clone https://github.com/carrilloapps/hfo.git\ncd hfo\npnpm install\n\npnpm dev           # run from source via tsx\npnpm build         # compile TS to dist/\npnpm typecheck     # tsc --noEmit (strict mode, all flags on)\npnpm lint          # eslint flat config with @typescript-eslint\npnpm test          # vitest (12 suites, 71 tests)\npnpm test:watch    # TDD mode\npnpm test:coverage # generate coverage/index.html\npnpm run ci        # typecheck + lint + test + build in one go\n```\n\nThe CI workflow runs the same chain on Ubuntu / macOS / Windows × Node 20 / 22 for every push\nand PR. The release workflow publishes to npm and uploads per-OS binaries to GitHub Releases\nwhen a `v*.*.*` tag is pushed.\n\n### Coding style\n\n- **Strict TypeScript.** Every flag in `tsconfig.json` is on, including `strictNullChecks`,\n  `noImplicitReturns`, `noFallthroughCasesInSwitch`, and `isolatedModules`.\n- **No raw emojis in source.** Use `src/icons.ts` (backed by the `figures` package, with ASCII\n  fallback on legacy consoles). ESLint guards this.\n- **Cross-OS is non-negotiable.** Anything OS-specific lives behind `src/platform.ts` or\n  `src/ollama.ts`.\n- **No telemetry.** `hfo` only talks to the public Hugging Face API and the local Ollama daemon.\n- **English source.** Spanish and 18 other languages live in `src/i18n.ts`.\n\nSee [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the PR workflow and\n[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) for community guidelines.\nSecurity issues: see [`SECURITY.md`](./SECURITY.md).\n\n## Privacy, security, cost\n\n`hfo` makes **exactly two kinds of external requests**, both to Hugging Face's public,\nunauthenticated API:\n\n```\nGET https://huggingface.co/api/models/\u003crepo\u003e/tree/main\nGET https://huggingface.co/\u003crepo\u003e/resolve/main/\u003cfile\u003e\n```\n\nEverything else — `nvidia-smi`, `systeminformation`, `ollama ps`, `ollama create`,\n`ollama launch` — runs locally. No telemetry. No accounts. Gated or private repos use a\nstandard `HF_TOKEN` environment variable or the `--token` flag.\n\nThe Ollama install helpers (`winget install`, `brew install`, the official shell script) run only\nwhen the user explicitly opts in from the TUI's Ollama installer overlay.\n\nAll costs are zero: no subscriptions, no API keys, no rate-limited tiers.\n\n## Roadmap\n\n- [ ] Real-time progress in backup/restore for multi-gigabyte archives (pause / resume).\n- [ ] Multi-install batch mode in `--install \u003cfile-with-repos\u003e`.\n- [ ] Snapshot diffing between two Modelfiles (for A/B testing parameter changes).\n- [ ] Plugin API for custom launch integrations.\n- [ ] Windows-native toast notifications when a long backup finishes.\n\nOpen an issue with the label `enhancement` to propose items.\n\n## Author\n\n**José Carrillo** — Senior Full-stack Developer (Tech Lead)\n\n- Website — [carrillo.app](https://carrillo.app)\n- Email — [m@carrillo.app](mailto:m@carrillo.app)\n- GitHub — [@carrilloapps](https://github.com/carrilloapps)\n- LinkedIn — [in/carrilloapps](https://linkedin.com/in/carrilloapps)\n- X — [@carrilloapps](https://x.com/carrilloapps)\n- Dev.to — [@carrilloapps](https://dev.to/carrilloapps)\n- Medium — [@carrilloapps](https://medium.com/@carrilloapps)\n\n## License\n\n[MIT](./LICENSE) — © 2026 José Carrillo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarrilloapps%2Fhfo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarrilloapps%2Fhfo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarrilloapps%2Fhfo/lists"}