hoocode can help you create hoocode packages. Ask it to bundle your extensions, skills, prompt templates, or themes.

HooCode Packages

HooCode packages bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. A package can declare resources in package.json under the hoocode key, or use conventional directories.

Table of Contents

• Install and Manage
• Package Sources
• Creating a HooCode Package
• Package Structure
• Dependencies
• Package Filtering
• Enable and Disable Resources
• Scope and Deduplication

Install and Manage

Security: HooCode packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.

hoocode install npm:@foo/bar@1.0.0
hoocode install git:github.com/user/repo@v1
hoocode install https://github.com/user/repo  # raw URLs work too
hoocode install /absolute/path/to/package
hoocode install ./relative/path/to/package

hoocode remove npm:@foo/bar
hoocode list                     # show installed packages from settings
hoocode update                   # update hoocode and all non-pinned packages
hoocode update --extensions      # update all non-pinned packages only
hoocode update --self            # update hoocode only
hoocode update --self --force    # reinstall hoocode even if current
hoocode update npm:@foo/bar      # update one package
hoocode update --extension npm:@foo/bar

By default, install and remove write to global settings (~/.hoocode/settings.json). Use -l to write to project settings (.hoocode/settings.json) instead. Project settings can be shared with your team, and hoocode installs any missing packages automatically on startup.

To try a package without installing it, use --extension or -e. This installs to a temporary directory for the current run only:

hoocode -e npm:@foo/bar
hoocode -e git:github.com/user/repo

Package Sources

HooCode accepts three source types in settings and hoocode install.

npm

npm:@scope/pkg@1.2.3
npm:pkg

• Versioned specs are pinned and skipped by package updates (hoocode update, hoocode update --extensions).
• Global installs use npm install -g.
• Project installs go under .hoocode/npm/.
• Set npmCommand in settings.json to pin npm package lookup and install operations to a specific wrapper command such as mise or asdf.

Example:

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

git

git:github.com/user/repo@v1
git:git@github.com:user/repo@v1
https://github.com/user/repo@v1
ssh://git@github.com/user/repo@v1

• Without git: prefix, only protocol URLs are accepted (https://, http://, ssh://, git://).
• With git: prefix, shorthand formats are accepted, including github.com/user/repo and git@github.com:user/repo.
• HTTPS and SSH URLs are both supported.
• SSH URLs use your configured SSH keys automatically (respects ~/.ssh/config).
• For non-interactive runs (for example CI), you can set GIT_TERMINAL_PROMPT=0 to disable credential prompts and set GIT_SSH_COMMAND (for example ssh -o BatchMode=yes -o ConnectTimeout=5) to fail fast.
• Refs pin the package and skip package updates (hoocode update, hoocode update --extensions).
• Cloned to ~/.hoocode/git/<host>/<path> (global) or .hoocode/git/<host>/<path> (project).
• Runs npm install after clone or pull if package.json exists.

SSH examples:

# git@host:path shorthand (requires git: prefix)
hoocode install git:git@github.com:user/repo

# ssh:// protocol format
hoocode install ssh://git@github.com/user/repo

# With version ref
hoocode install git:git@github.com:user/repo@v1.0.0

Local Paths

/absolute/path/to/package
./relative/path/to/package

Local paths point to files or directories on disk and are added to settings without copying. Relative paths are resolved against the settings file they appear in. If the path is a file, it loads as a single extension. If it is a directory, hoocode loads resources using package rules.

Creating a HooCode Package

Add a hoocode manifest to package.json or use conventional directories. Include the hoocode-package keyword for discoverability.

A pi manifest key is still read, for packages written against the upstream project HooCode grew out of. It is a deprecated alias: write hoocode. A package declaring both gets hoocode.

{
  "name": "my-package",
  "keywords": ["hoocode-package"],
  "hoocode": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

Paths are relative to the package root. Arrays support glob patterns and !exclusions.

Gallery Metadata

Packages are discovered on npm by their hoocode-package keyword. Add video or image fields so front-ends that list packages can show a preview:

{
  "name": "my-package",
  "keywords": ["hoocode-package"],
  "hoocode": {
    "extensions": ["./extensions"],
    "video": "https://example.com/demo.mp4",
    "image": "https://example.com/screenshot.png"
  }
}

• video: MP4 only. On desktop, autoplays on hover. Clicking opens a fullscreen player.
• image: PNG, JPEG, GIF, or WebP. Displayed as a static preview.

If both are set, video takes precedence.

Package Structure

Convention Directories

If no hoocode manifest is present, hoocode auto-discovers resources from these directories:

• extensions/ loads .ts and .js files
• skills/ recursively finds SKILL.md folders and loads top-level .md files as skills
• prompts/ loads .md files
• themes/ loads .json files

Dependencies

Third party runtime dependencies belong in dependencies in package.json. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in dependencies. When hoocode installs a package from npm or git, it runs npm install, so those dependencies are installed automatically.

HooCode bundles core packages for extensions and skills. If you import any of these, list them in peerDependencies with a "*" range and do not bundle them: @kolisachint/hoocode-ai, @kolisachint/hoocode-agent-core, @kolisachint/hoocode-agent, @kolisachint/hoocode-tui, typebox.

Other hoocode packages must be bundled in your tarball. Add them to dependencies and bundledDependencies, then reference their resources through node_modules/ paths. HooCode loads packages with separate module roots, so separate installs do not collide or share modules.

Example:

{
  "dependencies": {
    "shitty-extensions": "^1.0.1"
  },
  "bundledDependencies": ["shitty-extensions"],
  "hoocode": {
    "extensions": ["extensions", "node_modules/shitty-extensions/extensions"],
    "skills": ["skills", "node_modules/shitty-extensions/skills"]
  }
}

Package Filtering

Filter what a package loads using the object form in settings:

{
  "packages": [
    "npm:simple-pkg",
    {
      "source": "npm:my-package",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": [],
      "prompts": ["prompts/review.md"],
      "themes": ["+themes/legacy.json"]
    }
  ]
}

+path and -path are exact paths relative to the package root.

• Omit a key to load all of that type.
• Use [] to load none of that type.
• !pattern excludes matches.
• +path force-includes an exact path.
• -path force-excludes an exact path.
• Filters layer on top of the manifest. They narrow down what is already allowed.

Enable and Disable Resources

Use hoocode config to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. Works for both global (~/.hoocode) and project (.hoocode/) scopes.

Scope and Deduplication

Packages can appear in both global and project settings. If the same package appears in both, the project entry wins. Identity is determined by:

• npm: package name
• git: repository URL without ref
• local: resolved absolute path