Add-ons

Add-ons are folder-based repo adapters. They let ChunkyMonkey call focused tooling for a repo type without hard-coding everything into the main app.

Built-in Hugging Face and Unity adapters use the same contract local add-ons use.

Included Add-ons

Hugging Face

Hub model, dataset, Space, and Storage Bucket workflows through local HF tooling.

• Detect model, dataset, and Space remotes.
• Check local HF CLI auth and tooling.
• Create/check buckets, parse names/URLs/handles, scan candidates, dry-run, sync, and optionally ignore synced source files.

Unity

Unity repo hygiene and a free Unity Editor extension.

• Detect Unity project shape and editor version.
• Find missing `.meta` files and generated folders.
• Preview/apply `.gitignore` and Git LFS rules.

User Controls

1. Settings > Add-ons: enable included add-ons, add local folders, trust local backend code, refresh status, run actions, and remove local add-ons.
2. Add-on status controls show whether an adapter detected the current repo and which actions are available.

Manifest data can be read without running code. Local backend code runs only after you explicitly trust that add-on.

Folder Layout

my-addon/
  chunkymonkey-addon.json
  backend/
    chunkymonkey_addon.py
  README.md

Supported manifest file names:

1. chunkymonkey-addon.json
2. addon.json
3. package.json with chunkymonkeyAddon or chunkymonkey.addon

Local add-ons can live in:

1. A folder selected from Settings > Add-ons.
2. %APPDATA%\ChunkyMonkey\addons
3. ~/.chunkymonkey/addons
4. CHUNKYMONKEY_ADDONS_DIR

Manifest

{
  "id": "repo-linter",
  "name": "Repo Linter",
  "description": "Checks repo-specific generated files and release hygiene.",
  "version": "0.1.0",
  "apiVersion": 1,
  "kind": "repo-adapter",
  "entry": "backend/chunkymonkey_addon.py",
  "capabilities": ["detect", "status", "actions", "run"]
}

Rules:

1. apiVersion must be 1.
2. id is normalized to lowercase letters, numbers, hyphen, or underscore.
3. entry must stay inside the add-on folder.
4. entry is optional for manifest-only add-ons.
5. capabilities are descriptive. The actual callable backend methods decide what works.

Backend

from pathlib import Path


def detect(repo: str) -> dict:
    root = Path(repo or ".")
    return {"ok": True, "data": {"detected": (root / "pyproject.toml").exists()}}


def status(repo: str) -> dict:
    return {"ok": True, "text": "Repo Linter is ready."}


def actions(repo: str) -> dict:
    return {
        "ok": True,
        "actions": [
            {
                "id": "scan",
                "label": "Scan",
                "description": "Run the repo linter.",
                "fields": [
                    {"id": "strict", "label": "Strict mode", "type": "boolean"}
                ]
            }
        ]
    }


def run(repo: str, args: dict) -> dict:
    if args.get("action") != "scan":
        return {"ok": False, "error": "Unknown action.", "category": "unknown_action"}
    return {"ok": True, "text": "Scan complete.", "data": {"strict": bool(args.get("strict"))}}

Methods:

1. detect(repo: str) -> dict
2. status(repo: str) -> dict
3. actions(repo: str) -> dict
4. run(repo: str, args: dict) -> dict

Missing status and actions methods are allowed. Missing run fails when an action is called.

Results

Return dictionaries:

{ "ok": true, "text": "Done.", "data": {}, "actions": [] }

Failures should be explicit:

{ "ok": false, "error": "Tool is not installed.", "category": "tool_missing" }

Useful keys:

1. ok: boolean success flag.
2. text: human-readable result.
3. data: structured data for the UI.
4. actions: action list returned from actions.
5. error: failure text.
6. category: stable failure category.
7. output, warning, gitOutput, debugOutput: optional diagnostic text.

Long diagnostic text is capped by ChunkyMonkey so a bad add-on cannot flood the UI.

Action Fields

Actions can request simple user input:

{
  "id": "clone_space",
  "label": "Clone Space",
  "fields": [
    { "id": "repo_id", "label": "Repo ID", "required": true },
    { "id": "private", "label": "Private", "type": "boolean" },
    { "id": "sdk", "label": "SDK", "options": ["docker", "static"], "default": "docker" }
  ]
}

Field rules:

1. id must match [A-Za-z][A-Za-z0-9_]{0,39}.
2. type: "boolean" uses a confirmation.
3. options creates a constrained text prompt.
4. required: true rejects an empty value.

Action fields are rendered as small inputs or constrained choices. Keep actions small and explicit.

Security Model

1. Built-in add-ons are trusted only when loaded from the packaged built-in add-on folders.
2. Local add-ons are untrusted by default.
3. Local backend code runs out of process after explicit trust.
4. Backend entries cannot point outside the add-on folder.
5. Unsupported API versions fail before code runs.
6. Common secret environment variables are stripped before local add-on code starts.
7. stdout/stderr are captured and shown as diagnostics, not streamed into the app.

Add-ons are still trusted local code after you enable backend execution. Do not trust add-ons from people you do not trust.

Built-ins

Hugging Face:

1. Detect Hub model, dataset, and Space remotes.
2. Check local HF auth/tooling.
3. List visible Hub repos where supported.
4. Inspect repo and Space status where supported.
5. Run clone/create actions through local tooling.
6. Use HF Storage Buckets from the Commit panel Bucket tab: create private buckets, parse bucket names/URLs/handles, check access, scan candidates, dry-run sync, run the matched sync, and optionally ignore synced source files.

Bucket setup:

1. Install or upgrade the HF CLI: pip install -U huggingface_hub[cli].
2. Authenticate once with hf auth login using a token from https://huggingface.co/settings/tokens, or expose HF_TOKEN to the built-in Hugging Face add-on process.
3. Paste a bucket name, owner/name, hf://buckets/owner/name, or a Hugging Face bucket URL into the Bucket field.
4. Use Check before Dry run when you are using an existing bucket or org bucket.

Unity:

1. Detect Unity projects.
2. Find missing .meta files.
3. Flag generated folders.
4. Preview and apply .gitignore and Git LFS rules.
5. Support the free Unity Editor extension.

Unity Package Manager Git URL:

https://github.com/pwlot/ChunkyMonkey.git?path=addons/unity/EditorPackage