Installing HagiTask

Who this is for: Users who want to install and use community tasks in HagiCode.

Prerequisites:

• You can access your HagiCode application and its backend service.
• Your application version supports HagiTask community task management and the Community Gallery.
• Any agents, skills, or CLI dependencies required by the task are ready; check the task details for these requirements.

Install from the Community Gallery

The supported flow is to find task details and a ZIP archive in the HagiTask Site Community Gallery, then use the application’s community task installation feature:

1. Find a task in the Gallery by name, category, or tag.
2. Open its details and check the version, publisher, compatibility, and download size.
3. Choose Install. The application retrieves the ZIP from packageUrl and verifies the task ID, version, and SHA-256 hash.
4. After validation, the application writes the package to its local HagiTask data directory and refreshes the task catalog.

The Gallery exposes discovery, details, and archives at /index.json, /tasks/<taskId>.json, and /packages/<taskId>.zip, respectively. Installation uses the archive; it does not parse the website’s HTML.

Install from an archive

If you already have a ZIP obtained through a supported Gallery flow, you can install the local archive through the application’s community task management interface. The archive must contain the complete task package directory, and its ID, version, and content digest must match the installation request.

Uploading a browser-local folder is not part of the current Community Gallery installation flow. Server-side folder source configuration serves another purpose; see Using HagiTask.

Verify the installation

After installation, check the community task management interface:

• The task shows the correct taskId, version, and publisher.
• The task is enabled or can be enabled manually.
• No task dependency or compatibility requirements are unmet.
• The task remains in the catalog after a refresh, and you can open its panel.

The installation record stores the source, version, archive digest, and enabled state. Built-in tasks are displayed as read-only items and cannot be uninstalled as community packages.

Troubleshooting

Gallery is unavailable

Confirm that the configured Gallery URL is reachable and uses HTTPS; check the network, timeouts, and site status. If the first catalog fetch fails, the application does not invent an empty catalog. If a valid cache already exists, it may temporarily show the older catalog.

Task not found or invalid details

Use the canonical taskId from the task details, not a display alias. agentsmd and portytail are human-facing aliases for claude-md-update and ponytail, not installable task IDs.

Integrity or version check fails

Download the archive from the Gallery again. Do not edit the ZIP or generated catalog files manually. If the error persists, ask the package maintainer to check the Community Packages source data and version number.

Task cannot be used after installation

Check the task’s agent, skills, and CLI requirements; make sure it is enabled and refresh the catalog. If the package contents are invalid, see the community contribution guide for the Schema and validation process.

Next step: Use HagiTask.