# Hosts, installation and updates

The npm package `@humbleteam/humbleagents` is public. Anyone can download its code and bundled knowledge without an npm account. Installing it grants no GitHub repository permissions: private projects and the team template still require the user's own GitHub access. Creating a repository in `Humbleteam-team` requires the corresponding organization permission.

Revoking GitHub access prevents future authorized project downloads, fetches and pushes, but cannot prevent downloading public plugin versions. Local files and Git history remain on the user's computer. Private GitHub release downloads, when used, also require personal GitHub authorization.

## Four separate operations

| Operation | What happens |
| --- | --- |
| Publish source | A maintainer uploads reviewed source to the private repository. This does not update anyone's installation. |
| Publish a release | A maintainer publishes a version to npm or creates a private GitHub release with its archive. This does not install it. |
| Install an update | The employee obtains the archive and explicitly updates their installed files. |
| Activate | A new host session loads the updated files. Finish existing work before updating linked/local files. |

The local preparation process performs no publication. npm can install a registry package or a local `.tgz`. [npm documentation](https://docs.npmjs.com/cli/v11/commands/npm-install/)

## npm and local installation

For the public package, use Node.js 20 or 22 and npm 10:

```text
npm install --global @humbleteam/humbleagents@next --ignore-scripts
```

Create your chosen installation directory, then select the hosts you use:

```text
humbleagents plan --location /absolute/install/root --profile core --runtime claude,codex,gemini,cursor
humbleagents install --location /absolute/install/root --profile core --runtime claude,codex,gemini,cursor --yes
humbleagents doctor --location /absolute/install/root
```

Register the bundles using the host instructions below. `next` selects the candidate release; use an exact version to pin the installation. GitHub CLI authentication is needed for private repository operations, not for downloading the public npm package.

### Install from source or a local archive

With access to the private source repository:

```text
gh repo clone Humbleteam-team/humbleagents
```

For direct source use, Claude Code accepts `claude --plugin-dir "/absolute/clone/platform/generated/claude"`. Codex accepts `codex plugin marketplace add "/absolute/clone"`, followed by `codex plugin add humbleagents@humbleagents-local`. Start a new session after registration. The generated helpers are included in source; this route does not install a global `humbleagents` CLI.

To build an archive from a source checkout, use Node.js 20 or 22 and npm 10.9.4:

```text
npm ci --prefix platform --ignore-scripts
npm run pack:local --prefix platform
```

The archive is written to `platform/.artifacts/humbleagents-13.0.0-rc.0.tgz`.

Install the prepared archive with npm, then select the host bundles and a separate installation directory:

```text
npm install --global --ignore-scripts /absolute/path/humbleagents-13.0.0-rc.0.tgz
humbleagents plan --location /absolute/install/root --profile core --runtime claude,codex,gemini,cursor
humbleagents install --location /absolute/install/root --profile core --runtime claude,codex,gemini,cursor --yes
humbleagents doctor --location /absolute/install/root
```

Create the installation directory first. Replace the example paths for your operating system. `core`, `full` and `custom` select components, not permissions. Components can be selected with repeated `--component` or comma-separated values. Commands automatically include agents/workers and knowledge required to execute them; agent selection includes its knowledge. Legacy preset names exist only for compatibility and receive the same dependency closure; no studio roles or bootstrap are needed.

CLI options: `--location` sets the installation directory; `--runtime` selects hosts; `--profile` and `--component` select features. Use `--json` for structured output. Commands that change files require `--yes`; without it they return exit code 2. `--transaction` selects a transaction for rollback. An update describes the complete desired state of hosts and components.

The installer owns files below that root, including `runtimes/<host>`. Project data lives separately in the platform's user data directory. Package installation and host registration are separate steps; `doctor` reports installed files as `installed`, with `execution: not-probed`, until a real host test supplies evidence elsewhere. MCP configuration alone is similarly `not-probed`.

## Register the installed bundles

### Claude Code

Start a fresh session with the installed bundle:

```text
claude --plugin-dir /absolute/install/root/runtimes/claude
```

The plugin namespace is `humble`, preserving `/humble:help`, `/humble:setup` and the other `/humble:*` commands. The product and CLI remain `humbleagents`; the registry package is `@humbleteam/humbleagents`, while GitHub archives retain the unscoped package identity. Test the command in a synthetic project before normal work. `--plugin-dir` does not register a permanent marketplace installation. [Claude plugin reference](https://code.claude.com/docs/en/plugins-reference)

For a future personal private marketplace installation, use Claude's native manager. Manual marketplace/plugin operations use the employee's git credentials. Native auto-updates already notify; keep humbleagents' custom notification channel disabled for that installation. The locally inspected Claude Code 2.1.220 says updates require restart. Newer documentation also describes explicit reload; this workflow uses a fresh session. [Private repository authentication](https://code.claude.com/docs/en/plugin-marketplaces#private-repositories), [native updates](https://code.claude.com/docs/en/discover-plugins#configure-auto-updates)

### Codex CLI and app

Selecting the Codex runtime installs `/absolute/install/root/.agents/plugins/marketplace.json` with a local source. The installer owns this registration file and protects local modifications:

```json
{
  "name": "humbleagents-local",
  "plugins": [{
    "name": "humbleagents",
    "source": { "source": "local", "path": "./runtimes/codex" }
  }]
}
```

```text
codex plugin marketplace add /absolute/install/root
codex plugin add humbleagents@humbleagents-local
```

These commands are present in the locally inspected Codex CLI 0.150.1. Start a new task after registration. The host may load a managed copy; after updating the local source, rerun the native add command rather than editing the host cache. For a Git marketplace the installed CLI provides `codex plugin marketplace upgrade <name>`. It does not provide `codex plugin update`. Remote registration and activation need a release smoke test.

Codex discovers the router skill; native colon-command menu registration varies by version. If `/humble:*` is absent from the menu, invoke the installed humble skill with the same `/humble:<name> project=<id> -- <task>` text. A listed skill alone does not prove the worker completed its task.

The marketplace paths above are relative to the marketplace root. A source checkout needs `./platform/generated/codex` instead. [Official marketplace format](https://learn.chatgpt.com/docs/enterprise/plugin-management#supported-formats)

### Gemini CLI

Link the managed local bundle, then start a fresh Gemini session:

```text
gemini extensions link /absolute/install/root/runtimes/gemini
gemini extensions list
```

Linking is Gemini's supported local-development mechanism. It reads the chosen directory, so update that directory only after finishing current work. A Git-installed extension uses `gemini extensions update humbleagents` instead. Do not pass the source repository root to native install until a root-level Gemini extension bundle is actually published. [Extension reference](https://geminicli.com/docs/extensions/reference/)

### Cursor

For a custom root, use Cursor's documented `workspaceOpen` registration. Put a small script in your user configuration directory, for example `~/.cursor/register-humbleagents.mjs`:

```javascript
process.stdout.write(JSON.stringify({
  pluginPaths: ['D:/Tools/humbleagents/runtimes/cursor']
}));
```

Replace that path with your installation. Merge this entry into your existing `~/.cursor/hooks.json` without removing other hooks:

```json
{
  "version": 1,
  "hooks": {
    "workspaceOpen": [{ "command": "node ./register-humbleagents.mjs" }]
  }
}
```

Reload the window, inspect Customize and run a synthetic command. Alternatively, Cursor supports complete local plugin directories under `~/.cursor/plugins/local`; external-target symlinks there are skipped. `workspaceOpen` keeps the selected installation location. Local-import policies still apply. These steps are documented; successful task execution must be checked in the actual Cursor host. [Plugin paths and hook schema](https://cursor.com/docs/hooks#workspaceopen), [local plugin rules](https://cursor.com/docs/plugins#test-plugins-locally)

## Obtain and install a private update

After a stable release exists:

```text
humbleagents check-update
humbleagents fetch-update --version 13.0.0
```

`fetch-update` performs authenticated `gh api` reads against the fixed `Humbleteam-team/humbleagents` repository. It accepts stable releases tagged `vX.Y.Z`, with exactly one `humbleagents-X.Y.Z.tgz` asset and GitHub's SHA-256 digest. Drafts, prereleases, missing digests, oversized archives and mismatched bytes are rejected. Prerelease candidates can be installed from a locally prepared archive. Downloads go to `<user-data>/updates/downloads`; no extraction or execution occurs. Existing changed archives are preserved and reported.

Use the downloaded path returned by that command:

```text
npm install --global --ignore-scripts /absolute/download/path/humbleagents-13.0.0.tgz
humbleagents update --location /absolute/install/root --profile core --runtime claude,codex,gemini,cursor --yes
humbleagents doctor --location /absolute/install/root
```

Keep the same runtime/component selection you installed unless you intend to change it. Updating is a transaction: modified owned files or foreign files cause a conflict rather than an overwrite. Run `humbleagents rollback --location /absolute/install/root --yes` to compensate the latest transaction; modified files also block unsafe rollback. `humbleagents uninstall --location /absolute/install/root --yes` removes only verified owned files and preserves user files/state. Native host registrations can be removed separately through their managers.

The custom installer refuses Claude/Codex/Cursor plugin caches and Gemini's manager-owned extensions directory, including configured `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `CURSOR_CONFIG_DIR`, Cursor's `XDG_CONFIG_HOME/cursor`, and `GEMINI_CLI_HOME/.gemini` locations. A native manager copy is refreshed through that manager. No custom process edits its cache, downloads in the background, or activates code during a task. [Codex configuration root](https://learn.chatgpt.com/docs/config-file/environment-variables), [Claude configuration root](https://code.claude.com/docs/en/env-vars), [Cursor configuration roots](https://cursor.com/docs/cli/reference/configuration), [Gemini configuration root](https://geminicli.com/docs/reference/configuration/)

GitHub failures remain distinct: `authentication-required`, `forbidden`, `offline`, `rate-limited`, `not-found`, `unavailable`. A private-resource 404 can mean no release or no visible repository; it is not claimed as confirmed denial. None changes the availability of local workflows.

## Public npm delivery

Public downloads do not require npm login or a paid npm organization plan. An npm installation does not grant access to the private GitHub source, template or project repositories. [npm organizations](https://docs.npmjs.com/organizations/)

Check the available versions and install an update after finishing the current task:

```text
npm view @humbleteam/humbleagents dist-tags --json
npm install --global @humbleteam/humbleagents@next --ignore-scripts
humbleagents update --location /absolute/install/root --profile core --runtime claude,codex,gemini,cursor --yes
humbleagents doctor --location /absolute/install/root
```

Use `humbleagents install` for a new managed root; `update` applies to an existing installation. Finish the current task before replacing npm or managed files, and start a fresh host session after the update. `next` is the candidate tag; choose an exact approved version to pin downloads. npm's native registry operations handle acquisition. No second background updater is installed.

If switching from the global unscoped `humbleagents` package, first remove that CLI with `npm uninstall --global humbleagents`; it does not remove the separate managed root or project data. Managed rollback/uninstall use the same ownership checks regardless of package scope.

The built-in `check-update`, `fetch-update` and session notification remain specific to GitHub releases. They do not query npm dist-tags or advertise npm candidates. Check npm explicitly with `npm view` as shown above. A source push, npm publication, npm installation, managed update and host activation are separate operations. A GitHub release notice should be checked against the chosen npm channel before updating a scoped installation.

## Private npm delivery

The build tools also support a separate `npm-private` artifact with `restricted` visibility. Private npm packages require [npm Teams](https://docs.npmjs.com/organizations/), personal npm login and appropriate npm team permissions. Those permissions are independent of GitHub: if this channel is used, revoke both npm and GitHub access when someone leaves. Publishing a version publicly means that version's contents can already have been copied; a later access change cannot undo those downloads.

## Uninstall

Stop sessions using the plugin. For a Claude `--plugin-dir` installation, start future sessions without that flag. For Codex, remove the registration:

```text
codex plugin remove humbleagents@humbleagents-local
```

Remove the managed files before uninstalling the CLI:

```text
humbleagents uninstall --location /absolute/install/root --yes
npm uninstall --global @humbleteam/humbleagents
```

The managed uninstaller preserves user files and project data and refuses to remove modified owned files. Gemini and Cursor registrations can be removed through the host or user configuration used to add them. A direct source installation has no managed root; remove its host registration before deleting the source clone if it is no longer needed.

## Optional notifications

```text
humbleagents update-notifications off
humbleagents update-notifications on
humbleagents update-notifications status
humbleagents update-notifications on --channel native
humbleagents update-notifications on --channel local
```

Preferences and check history are stored in `<user-data>/updates`. `--data-root /absolute/path` is available for isolated setups; use the same root in every corresponding command/hook. Checks use no LLM, are cached for at least 24 hours including failures, and emit one message per version. A lock prevents concurrent checkers from duplicating notices. No new version means no notice. Metadata reads time out after two seconds; session-hook failures return an empty JSON object and succeed.

The npm/local installer owns an `update-channel.json` delivery marker in each runtime bundle. It remains `local` if Codex copies that bundle into its cache: the checker can then discover a new private release while the native manager refreshes only the explicitly updated local source. This check writes only user-data state, never the cache. Explicit `--channel` wins over saved settings, which win over the bundle's marker. For a delivery channel where the host already provides update notifications, select `native` to suppress custom notices. An unmarked native-cache copy conservatively defaults to `native`; an explicit local choice is supported for older local installations.

Claude, Codex and Gemini bundles include synchronous **command** SessionStart hooks in `hooks/hooks.json`. They become available when that bundle is registered and activated through the host's normal trust process; no global hook settings are overwritten. The hooks call the installed launcher. These equivalent commands can be used for troubleshooting:

```text
node /absolute/install/root/runtimes/claude/runtime.mjs session-start --host claude
node /absolute/install/root/runtimes/codex/runtime.mjs session-start --host codex
node /absolute/install/root/runtimes/gemini/runtime.mjs session-start --host gemini
```

Use an absolute, quoted launcher path if it contains spaces. Do not register a second copy of the bundled hook. Claude and Codex resolve the plugin root from their host environment; Gemini uses its documented `${extensionPath}` substitution. Session startup or resume may show the notice; existing tasks are never interrupted or reloaded by this hook. Native notification channels stay silent; locally delivered cache copies retain their local channel.

| Host | Deterministic notification surface |
| --- | --- |
| Claude Code | Synchronous SessionStart `systemMessage` warning; async hook output does not guarantee direct display. |
| Codex | SessionStart `systemMessage` in UI/event stream after hook trust; not guaranteed chat text. |
| Gemini CLI | SessionStart `systemMessage` displayed at session start. |
| Cursor | No direct SessionStart message contract used. Use `check-update` in a terminal; a Cursor hook returns `{}` and does not consume an unseen notice. |

Sources: [Claude hook output](https://code.claude.com/docs/en/hooks#json-output), [Codex hooks and trust](https://developers.openai.com/codex/hooks/), [Gemini SessionStart](https://geminicli.com/docs/hooks/reference/#sessionstart), [Cursor SessionStart](https://cursor.com/docs/hooks#sessionstart).

## Why distribution channels differ

Current [Superpowers installation guidance](https://github.com/obra/superpowers/blob/main/README.md) uses host-specific mechanisms. Its [session-start source](https://github.com/obra/superpowers/blob/main/hooks/session-start) only loads local instructions; it does not download updates. humbleagents follows the same separation rather than assuming all hosts behave alike.

Public npm distributes the plugin without an access restriction. Personal authenticated GitHub downloads remain available for private releases. ChatGPT administrative imports sync using the importing administrator's GitHub connection. Cursor team marketplaces use their GitHub App plus marketplace audiences. These shared distribution mechanisms do not establish every employee's effective repository permission at download time. Project access is always checked separately through the employee's own GitHub identity. [ChatGPT sync identity](https://learn.chatgpt.com/docs/enterprise/plugin-management#reconnect-or-change-github-access), [Cursor marketplace updates](https://cursor.com/docs/plugins#keep-plugins-up-to-date).

The documentation and local `--help` checks were reviewed on 2026-09-15. Host presence, successful installation, successful helper execution, and completed agent work are separate evidence levels; see the verification report for actual runs.