# Awesome Selfhosted

> Browse awesome-selfhosted categories and git-clone apps into a folder

| | |
|---|---|
| Version | 1.0.0 |
| Category | System |
| Permissions | shell.exec, filesystem.write |
| Depends on | ai-chat |

# Awesome Selfhosted

Browse the [awesome-selfhosted](https://github.com/awesome-selfhosted/awesome-selfhosted) list
(categories + apps) inside Kazuo, then `git clone` an app's source repository into a folder you choose.

**Type:** `exec` — uses `window['kazuo-ai'].localExec()` to run `git clone` locally. No backend (`main/`).

## How it works

1. On open, the widget fetches the awesome-selfhosted `README.md` from GitHub, parses it into
   categories → apps (name, description, license, language, website, source repo, ⚠ unmaintained flag),
   and caches the result in the webview's `localStorage` (`as_cache_v1`, 24h TTL). **Refresh** forces a re-fetch.
2. Left pane = categories; right pane = apps in the selected category. The search box filters apps
   across all categories.
3. Each app has **Website** / **Source** (open in the default browser via the OS opener) and **Install**.
4. **Install** runs `git -C "<installDir>" clone [--depth 1] "<repoUrl>"` through `localExec` and streams
   the output into the log panel. If no folder is set yet, the native folder picker opens first.
   Apps with no clonable git repository show **Install** disabled (use **Website** instead).

The clone URL is the app's `Source Code` link, or its homepage when that already points at a git host.
URLs are validated (`isSafeUrl`) before being placed on the shell command line.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — main UI (category browser + install)
  - has its own "⚙" button + settings overlay built into widget.html/widget.js (host no longer provides a per-widget gear icon — see references/plugin-runtime-api.md section 1b)
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields as the widget overlay (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*`/`settings.*` namespaces

## Default settings

- `installDir` — default: `""` — folder that apps are cloned into (chosen via the folder picker or typed in)
- `shallow` — default: `true` — clone with `--depth 1` (latest commit only, faster)

## Requirements

- `git` must be installed and on the system `PATH` (the plugin runs `git clone`).
- Internet access on first load (to fetch the list); afterwards the cached list works offline.

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/`
on its own, no registration needed) → Install → Enable. Pick a folder, open a category, and click
**Install** on any app with a source repo.