Plugin

Hawa Code supports extending its capabilities through plugins and a plugin marketplace. Plugins are distributed as declarative directories and can contain components such as Skills, slash commands, Agents, Hooks, MCP Servers, and LSP Servers. The marketplace is a plugin catalog for centrally managing and distributing multiple plugins.

Claude Code compatibility: settings.plugins.pluginClaudeCompat is enabled by default. Hawa Code recognizes both .hcode-plugin/ and .claude-plugin/ directories, preferring .hcode-plugin/. This allows reusing a large number of plugins from the Claude Code ecosystem.

Quick Start

1. Add a Marketplace

# Local directory
hcode plugin marketplace add ./my-marketplace

# GitHub repository shorthand
hcode plugin marketplace add owner/repo

# git URL
hcode plugin marketplace add https://github.com/owner/repo.git

# URL pointing directly to a marketplace.json
hcode plugin marketplace add https://example.com/marketplace.json

2. Install a Plugin

hcode plugin install demo-plugin@my-marketplace

3. Use the Plugin

Once installed and enabled, the plugin’s Skills and commands are registered automatically:

Skill: invoke in chat via /plugin-name:SkillName or /SkillName.
Custom command: invoke via /commandName.
MCP Server: after restarting or refreshing, view via hcode mcp list.

Marketplace Management

A marketplace is a collection of plugins described by a marketplace.json file. Hawa Code supports managing marketplaces through CLI and interactive slash commands.

Add a Marketplace

hcode plugin marketplace add <source>

<source> supports the following forms:

Source	Example
Local directory	`./my-marketplace`
GitHub shorthand	`owner/repo`
git URL	`https://github.com/owner/repo.git` or `git@github.com:owner/repo.git`
marketplace.json URL	`https://example.com/marketplace.json`

Remove a Marketplace

hcode plugin marketplace remove <name>

List Marketplaces

hcode plugin marketplace list
hcode plugin marketplace list --json

Update a Marketplace

Re-fetch marketplace content from its source:

# Update all marketplaces
hcode plugin marketplace update

# Update a specific marketplace
hcode plugin marketplace update my-marketplace

Plugin Management

Install a Plugin

hcode plugin install <plugin[@marketplace]>

plugin: plugin name.
marketplace: optional marketplace name. If omitted, all known marketplaces are searched; if only one marketplace contains the plugin, it is used automatically.

Uninstall a Plugin

hcode plugin uninstall <plugin[@marketplace]>

You can use the full ID or the plugin@marketplace shorthand.

Update a Plugin

# Update all plugins
hcode plugin update

# Update a specific plugin
hcode plugin update demo-plugin@my-marketplace

List Installed Plugins

hcode plugin list
hcode plugin list --json

Enable/Disable a Plugin

hcode plugin enable <plugin[@marketplace]>
hcode plugin disable <plugin[@marketplace]>

After disabling, the plugin’s Skills, commands, MCP, and other components no longer take effect, but the files remain in the local cache.

Interactive Manager

Enter the following in the Hawa Code interactive interface:

/plugin

This opens the plugin manager with keyboard navigation:

← / →: switch tabs (Available / Installed / Marketplaces).
↑ / ↓: select list items.
Enter: view details or install/uninstall/update.
Esc: exit.

marketplace.json

The marketplace description file is usually located at .hcode-plugin/marketplace.json in the marketplace root. In compatibility mode, .claude-plugin/marketplace.json is also supported.

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "description": "My Hawa Code plugin marketplace",
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Adds a quality-review skill",
      "version": "1.0.0"
    }
  ]
}

Plugin Source (`source`)

plugins[].source supports multiple forms:

Type	Example
Local relative path	`"./plugins/formatter"`
GitHub	`{ "source": "github", "repo": "owner/repo", "ref": "main", "sha": "..." }`
URL	`{ "source": "url", "url": "https://...", "ref": "..." }`
Git subdirectory	`{ "source": "git-subdir", "url": "https://...", "path": "plugins/foo", "ref": "main" }`
npm	`{ "source": "npm", "package": "@org/pkg", "version": "1.0.0" }`

Relative paths are resolved against the marketplace root (the directory containing .hcode-plugin/), not .hcode-plugin/ itself.

plugin.json

The description file for a single plugin is located at .hcode-plugin/plugin.json in the plugin root. In compatibility mode, .claude-plugin/plugin.json is also supported.

{
  "name": "quality-review-plugin",
  "version": "1.0.0",
  "description": "Adds a quality-review skill for quick code reviews",
  "author": { "name": "Your Name", "email": "you@example.com" },
  "homepage": "https://...",
  "repository": "https://...",
  "license": "MIT",
  "keywords": ["review", "quality"],
  "category": "productivity",
  "skills": "skills",
  "commands": "commands",
  "agents": "agents",
  "hooks": "hooks",
  "mcpServers": "mcp",
  "lspServers": "lsp",
  "permissions": ["read", "write"],
  "strict": true,
  "defaultEnabled": true
}

Field Reference

Field	Description
`name`	Unique plugin name
`version`	Version number
`description`	Description
`author`	Author information
`homepage` / `repository` / `license`	Project metadata
`keywords` / `category`	Classification and tags
`skills`	Skill directory path, default `skills`
`commands`	Custom command directory path, default `commands`
`agents`	Agent directory path, default `agents`
`hooks`	Hooks configuration directory or inline object
`mcpServers`	MCP Server configuration directory or inline object
`lspServers`	LSP Server configuration directory or inline object
`permissions`	List of permissions required by the plugin
`strict`	When `true`, `plugin.json` takes precedence; when `false`, the marketplace entry fully overrides
`defaultEnabled`	Whether the plugin is enabled by default after installation, default `true`

Strict Mode

strict: true (default): plugin.json is the authoritative source of component definitions; the marketplace entry only supplements information.
strict: false: the marketplace entry is the complete definition, and plugin.json must not declare components (skills, commands, etc.), otherwise installation fails.

Plugin Components

A plugin can contain the following extension components:

Skill

Each subdirectory under the plugin’s skills directory (containing SKILL.md) is registered as a Skill and can be invoked directly in chat after installation. See the Skill documentation for details.

Custom Commands

.md files under the plugin’s commands directory are registered as slash commands. Command names are namespaced by default as plugin-name:commandName.

Agent

Definitions under the plugin’s agents directory are added to the Agent scan path.

Hooks

The hooks field can be a directory path (which must contain hooks.json) or an inline HooksConfig object. Supports SessionStart and SessionEnd hooks.

MCP Server

The mcpServers field can be a directory path (containing JSON configuration files) or an inline object. MCP Servers registered by plugins are automatically prefixed:

plugin__<marketplace>__<plugin>__<server>

LSP Server

The lspServers field is used similarly to MCP for registering LSP Servers.

Variable Substitution

Strings in MCP and Hook configurations support the following variable substitutions:

Variable	Substituted with
`${HCODE_PLUGIN_ROOT}`	Plugin cache directory
`${HCODE_PLUGIN_DATA}`	Plugin data directory
`${CLAUDE_PLUGIN_ROOT}`	Same as `${HCODE_PLUGIN_ROOT}`
`${CLAUDE_PLUGIN_DATA}`	Same as `${HCODE_PLUGIN_DATA}`

Configuration

Configure plugin behavior in ~/.hcode/settings.json or project .hcode/settings.json:

{
  "plugins": {
    "enabledPlugins": ["my-marketplace__demo-plugin@1.0.0"],
    "disabledPlugins": [],
    "pluginConfigs": {},
    "extraKnownMarketplaces": [
      { "name": "company", "source": "https://github.com/company/hawa-plugins" }
    ],
    "strictKnownMarketplaces": false,
    "pluginMarketplaceAllowlist": [],
    "pluginAutoUpdate": false,
    "pluginAutoUpdateInterval": 60,
    "pluginSandboxHooks": true,
    "pluginClaudeCompat": true
  }
}

Configuration Reference

Setting	Description
`enabledPlugins`	List of plugin IDs to force-enable
`disabledPlugins`	List of plugin IDs to force-disable
`pluginConfigs`	Per-plugin configuration objects
`extraKnownMarketplaces`	Additional built-in marketplace list
`strictKnownMarketplaces`	When `true`, only accept known marketplaces; when `false`, allow adding new marketplaces
`pluginMarketplaceAllowlist`	Marketplace source allowlist, supports glob/regex
`pluginAutoUpdate`	Whether to enable background auto-update for marketplaces and plugins
`pluginAutoUpdateInterval`	Auto-update interval in minutes, default 60
`pluginSandboxHooks`	Whether to execute Hook and MCP commands in sandbox, default `true`
`pluginClaudeCompat`	Whether to support `.claude-plugin/` directories, default `true`

Security and Permissions

Installation Confirmation

Before installing a plugin, Hawa Code displays its source, version, required permissions, and sandbox status, and requires user confirmation. CLI can skip confirmation via --yes (in current implementation, some paths trust known marketplaces by default).

Allowlist

Use pluginMarketplaceAllowlist to restrict allowed marketplace sources, supporting glob and regular expressions.

Path Isolation

Each plugin is copied to an isolated cache directory. ../ references and out-of-bounds symlinks are forbidden. ${HCODE_PLUGIN_ROOT} and ${HCODE_PLUGIN_DATA} serve as safe variable substitution entry points.

Sandbox Execution

pluginSandboxHooks is enabled by default. Hooks and MCP commands are executed through Hawa Code’s sandbox mechanism, subject to settings.sandbox restrictions.

Cache Directory

Plugin-related data is stored by default under ~/.hcode/plugins/:

~/.hcode/plugins/
├── known_marketplaces.json
├── installed_plugins.json
├── marketplaces/<name>/          # Marketplace clone/download directory
├── installed/<marketplace>__<plugin>@<version>/  # Plugin cache
└── data/<marketplace>__<plugin>/                  # Plugin persistent data

Environment Variables

Environment Variable	Description
`HCODE_PLUGIN_CACHE_DIR`	Override the entire plugin cache root directory
`HCODE_PLUGIN_ROOT`	Points to the installed plugin directory
`HCODE_PLUGIN_DATA`	Points to the plugin data directory
`HCODE_PLUGIN_SEED_DIR`	Pre-installed plugin directory, used for containers/CI
`HCODE_PLUGIN_GIT_TIMEOUT_MS`	Git operation timeout, default 120000ms
`HCODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE`	Keep old cache when update fails

Command Quick Reference

Slash Commands

/plugin marketplace add <source>
/plugin marketplace remove <name>
/plugin marketplace list
/plugin marketplace update [name]
/plugin install <plugin[@marketplace]>
/plugin uninstall <plugin[@marketplace]>
/plugin update [plugin[@marketplace]]
/plugin list
/plugin enable <plugin[@marketplace]>
/plugin disable <plugin[@marketplace]>

CLI

hcode plugin marketplace add <source>
hcode plugin marketplace remove <name>
hcode plugin marketplace list [--json]
hcode plugin marketplace update [name]
hcode plugin install <plugin[@marketplace]>
hcode plugin uninstall <plugin[@marketplace]>
hcode plugin update [plugin[@marketplace]]
hcode plugin list [--json]

Manual Verification Example

Create a local marketplace:

mkdir -p my-marketplace/.hcode-plugin
mkdir -p my-marketplace/plugins/demo-plugin/.hcode-plugin
mkdir -p my-marketplace/plugins/demo-plugin/skills/demo

Write my-marketplace/.hcode-plugin/marketplace.json:

{
  "name": "my-marketplace",
  "owner": { "name": "Demo" },
  "plugins": [
    {
      "name": "demo-plugin",
      "source": "./plugins/demo-plugin",
      "version": "1.0.0"
    }
  ]
}

Write my-marketplace/plugins/demo-plugin/.hcode-plugin/plugin.json:

{
  "name": "demo-plugin",
  "version": "1.0.0",
  "description": "A demo plugin"
}

Write my-marketplace/plugins/demo-plugin/skills/demo/SKILL.md:

---
name: Demo
description: Say hello from plugin
---
Hello from plugin!

Add and install:

hcode plugin marketplace add ./my-marketplace
hcode plugin install demo-plugin@my-marketplace

After installation, run /demo-plugin:Demo in Hawa Code to see the result.