Troubleshooting

Solutions for common Apothem install and runtime issues.

Installation issuesCopy Anchor Link

No Python 3.10+ foundCopy Anchor Link

The installers probe python3, python, and the versioned names (python3.14 through python3.10) — rejecting Microsoft Store launcher shims — and stop with No Python >= 3.10 found in PATH when no candidate meets the 3.10 floor. The npx shim probes APOTHEM_PYTHON when it is set, then python3, python, and py -3, and exits 1 with its own message when none qualifies. Install CPython 3.10 or newer from python.org or your OS package repository, confirm python3 --version (or py -3 --version on Windows) reports at least 3.10, then re-run.

Missing runtime dependencies: click, richCopy Anchor Link

The engine vendors most of its third-party dependencies inside the source tree, but click and rich must be importable under the interpreter the installer selects. When either is missing, the installer names it and offers to install it for you:

! Missing Python prerequisites under <python>: click rich
  Install click rich under <python> now? [y/N]

Accept the prompt to have the installer run pip install under that interpreter. To skip the prompt, pass --yes (-Yes on PowerShell) or set APOTHEM_AUTO_INSTALL_DEPS=1 to install automatically. If you decline — or pip is unavailable, or you prefer your OS package manager — install the named packages yourself (for example python3-click and python3-rich on Debian-family hosts, or pip install click rich) and re-run.

apothem not found after running the installerCopy Anchor Link

The installer places the source tree at ~/.apothem and writes an apothem shim to ~/.local/bin by default (POSIX) or %LOCALAPPDATA%\Microsoft\WindowsApps (Windows). It does not edit your PATH. If apothem is not found, that directory is not on PATH; add it, or use the PYTHONPATH form below until you do. Run the engine through the invocation the installer prints at completion:

PYTHONPATH="$HOME/.apothem/src" python -m apothem <command>

or use the npx form (npx @ahmed-g-gad/apothem <command>), which needs no PATH entry.

/plugin marketplace add failsCopy Anchor Link

/plugin marketplace add ahmed-g-gad/apothem fetches the marketplace listing from GitHub. When it fails, confirm the machine can reach https://github.com/ahmed-g-gad/apothem (network, proxy, or firewall rules), then retry. If the marketplace was added earlier under a partial fetch, remove and re-add it before running /plugin install apothem@apothem.

Adding the plugin host's marketplace times outCopy Anchor Link

The plugin host's command that adds a marketplace clones its repository and gives up after 30 seconds. A full clone of this repository can take longer on a slow disk, such as a Windows drive under WSL, and an earlier full clone can also leave the plugin stuck at an old version when a later refresh times out. Fetch only the two folders the plugin needs:

codex plugin marketplace remove apothem
codex plugin marketplace add ahmed-g-gad/apothem --sparse .agents/plugins --sparse plugins/apothem
codex plugin add apothem@apothem

Listing the host's plugins then shows the current version of apothem@apothem.

npx serves a stale versionCopy Anchor Link

npx caches downloaded packages. When npx @ahmed-g-gad/apothem --version reports an older version than the current release, clear the cache or pin the dist-tag:

npx clear-npx-cache
npx @ahmed-g-gad/apothem@latest --version

The installer stops: the maintainer public key is not in the local keyringCopy Anchor Link

The installer verifies the signed release tag and stops when the signing key is not in your keyring. Import it once, check that the fingerprint reads 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163, then run the installer again:

curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import
gpg --fingerprint 70396FED9C634163

& "$env:ProgramFiles\Git\bin\bash.exe" -c 'curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import && gpg --fingerprint 70396FED9C634163'

On Windows, import through Git's bash as shown: git verify-tag reads the keyring of the gpg that ships with Git for Windows. A host without gpg can install with APOTHEM_VERIFY=checksum, which checks the release archive's digest instead of the tag signature.

irm / iex blocked on WindowsCopy Anchor Link

If PowerShell execution policy blocks the installer:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm https://apothem.ahmedgad.com/install.ps1 | iex

Runtime issuesCopy Anchor Link

apothem install finds no harnessesCopy Anchor Link

Run apothem doctor to read its Harness Status table, which has one row per harness. A row marked not installed means Apothem found no install for that harness. A row marked needs --project is a project-scope harness, which doctor checks only when you pass --project <path>. If doctor reports No harness is installed yet, ensure your harness is installed, then run apothem install --harness <name>.

apothem verify reports a failing adapterCopy Anchor Link

Re-run apothem install to re-materialize the adapter. If the issue persists, check the adapter-specific page under Harness Adapters.

Hooks not firing in Claude CodeCopy Anchor Link

Confirm Apothem is wired by checking ~/.claude/settings.json for the hook entries. If the file is missing the hooks, run apothem install again.

Getting helpCopy Anchor Link

• GitHub Issues -- bug reports
• GitHub Discussions -- questions
• FAQ -- frequently asked questions