Background#

Mixing npm and pnpm in daily development easily causes chaos:

• The same global package gets installed by both managers, command shims overwrite each other, and uninstalling one accidentally deletes the other’s entry;
• You accidentally run npm when installing a new package, resulting in a dependency layout inconsistent with what pnpm manages.

So the idea is: standardize on pnpm and disable the npm command. But pnpm can’t uninstall or update packages that npm installed globally — if you completely disable npm, those packages become unmanageable.

The solution has two layers:

1. ps1 script (interactive terminal): the npm command is intercepted (prompting to use pnpm), while npma is defined as a forwarder to the real npm, specifically for managing npm’s own global packages.
2. AGENTS.md instructions (agent environment): opencode’s shell starts with -NoProfile and doesn’t load the profile, so the same rules need to be documented in AGENTS.md for the agent.

Part 1: The ps1 Script#

Add the following to your PowerShell profile ($PROFILE, i.e. Microsoft.PowerShell_profile.ps1):

1
# Unified UTF-8 encoding to avoid garbled Chinese characters (console codepage may be GBK 936)
2
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
3
[Console]::InputEncoding  = [System.Text.Encoding]::UTF8
4
$OutputEncoding          = [System.Text.Encoding]::UTF8
5

6
# Disable npm, standardize on pnpm (fall back to real npm when pnpm is unavailable to avoid blocking package management)
7
function npm {
8
    if (Get-Command pnpm -ErrorAction SilentlyContinue) {
9
        Write-Error "npm has been disabled. Please use pnpm (use npma to forward to real npm for managing npm's own global packages)."
10
        throw "npm disabled: use pnpm instead"
11
    }
12
    $realNpm = @(Get-Command npm -All -ErrorAction SilentlyContinue |
13
        Where-Object { $_.CommandType -ne 'Function' -and $_.CommandType -ne 'Alias' } |
14
        Select-Object -First 1)
15
    if ($realNpm) {
16
        Write-Warning "pnpm not detected, calling real npm: $($realNpm.Source)"
17
        & $realNpm.Source @args
18
        return
19
    }
20
    Write-Error "npm has been disabled, and neither pnpm nor real npm was found"
21
    throw "npm disabled and no fallback npm found"
22
}
23
function npma {
24
    # npma = real npm forwarder: the npm name is intercepted by the function above,
25
    # use npma when managing global packages installed by npm (visible via npm ls -g, not managed by pnpm).
26
    $realNpm = @(Get-Command npm -All -ErrorAction SilentlyContinue |
27
        Where-Object { $_.CommandType -ne 'Function' -and $_.CommandType -ne 'Alias' } |
28
        Select-Object -First 1)
29
    if ($realNpm) {
30
        & $realNpm.Source @args
31
        return
32
    }
33
    Write-Error "npma: real npm not found"
34
    throw "npma: real npm not found"
35
}

1
npm install -g foo
2
pnpm add -g foo
3
npma uninstall -g hexo

Part 2: AGENTS.md Instructions#

opencode (or other agents) launches commands with pwsh -NoProfile -NonInteractive, which does not load your PowerShell profile — so the npm intercept function and npma from above don’t exist in the agent’s shell: npm in the agent is the real npm, and npma doesn’t exist.

Therefore, the same rules need to be documented in the global AGENTS.md (~/.config/opencode/AGENTS.md):

1
## Package Manager Conventions
2

3
The user's PowerShell profile has disabled the `npm` command (intercepted when pnpm is detected) and defined `npma` = real npm forwarder (for managing npm's own global packages). **The agent's shell starts with `-NoProfile` and does not load that profile** — so in the agent environment, `npm` is the real npm and `npma` does not exist. Based on this:
4

5
- Package management operations **default to `pnpm`** (install / update / uninstall global and project dependencies).
6
- When managing **npm's own global packages** (listed by `npm ls -g`, not managed by pnpm), use the real npm directly: `npm uninstall/update/ls -g ...` (in the interactive terminal the corresponding command is `npma`).
7
- **A single global package must only be managed by one package manager**: never use pnpm to uninstall/update npm-installed packages, and never use npm to uninstall/update pnpm-installed packages (mixing managers on the same package causes shim overwrites / accidental deletions).
8
- Global directories are unified: npm prefix and pnpm global are both `Z:\Code\packages\npm` (pnpm store at `Z:\.pnpm-store\v11`, pnpm/yarn versions managed by corepack).

Appendix: Unified Global Directories#

This setup also unifies global directories, preventing packages from being scattered across the C: drive and tool drives:

• npm prefix: Z:\Code\packages\npm
• pnpm global (global-dir / global-bin-dir): also Z:\Code\packages\npm
• pnpm store: Z:\.pnpm-store\v11
• pnpm / yarn versions managed by corepack

pnpm’s global config lives in its own config.yaml (%LOCALAPPDATA%\pnpm\config\config.yaml), not in ~/.npmrc, to avoid npm emitting warnings.