Installation

Apothem installs in under two minutes and works alongside your existing harness configuration. Every path runs the same self-contained engine — the source tree carries its vendored dependencies and runs from a checkout on system Python 3.10 or newer (see the self-contained runtime).

Two prerequisites are shared by every path: system Python 3.10 or newer on PATH, with the click and rich packages importable under it. The npm shim (channel 2), the VS Code-family extension (channel 4), and the command-line bootstraps (channels 5–7) additionally need Node.js 18 or newer to run npx. Python 3.10 and Node.js 18 and 20 are past upstream end of life; they remain supported and tested, but newer versions are preferred (see Prerequisites at a glance). Each channel's own section below repeats its exact prerequisites, one copy-ready command, and a verification step.

Choose a channelCopy Anchor Link

Eight install channels are available. Pick by how you already work.

Every path is idempotent: re-running is safe and converges to the same state.

1. Claude Code pluginCopy Anchor Link

Prerequisites: Claude Code, and system Python 3.10+ on PATH.

The plugin path runs entirely inside Claude Code. It bundles the Apothem engine with its slash commands, delegated workers, skills, rules, and hooks, all runnable from the self-contained plugin tree:

/plugin marketplace add ahmed-g-gad/apothem
/plugin install apothem@apothem

After the install, the Apothem command set, the bundled delegated workers, the skills, and the four output styles (pick one with /output-style or from /config) are available in every Claude Code session. The plugin ships each command as a skill, a SKILL.md with the detail it loads on demand in a references/ folder beside it, so Claude Code invokes it with the plugin's prefix: /apothem:plan-spec, /apothem:security-audit, and the rest. Two names are taken by Claude Code itself: /plan enters plan mode and /code-review runs the bundled review, so type /apothem:plan and /apothem:code-review for the Apothem commands. When the Apothem engine installs into Claude Code instead of the plugin, the same skills are written to ~/.claude/skills/ without a prefix, and a personal code-review skill replaces the bundled /code-review (its /review alias still runs the bundled one). Two names, projectify and workflow, are also native skills; the native skill is the one the plugin and the engine install ship, not a skill derived from the command. See Claude Code for how the commands are split, and Slash commands for the full command catalog.

Verify: run /plugin inside Claude Code and confirm apothem is listed as installed, or check the drift report from a terminal:

npx @ahmed-g-gad/apothem verify --harness claude-code

2. npm shim (npx)Copy Anchor Link

Prerequisites: Node.js 18+ (for npx) and system Python 3.10+ on PATH. The shim locates the interpreter and forwards every CLI command to the bundled engine — nothing is placed permanently on your system. It tries python3, python, then py -3 in that order; set APOTHEM_PYTHON to an interpreter path to try it first, which is what you need when Python is installed but not on PATH, or when several versions are and you want a specific one. The interpreter you name still has to pass the Python 3.10+ check; when it does not, the shim falls back to python3, python, then py -3.

npx @ahmed-g-gad/apothem install --harness claude-code

On a machine with no profile, this first install creates the starter profile at ~/.config/apothem/profile.yaml and says so. Its identity fields are placeholders: personalize them (npx @ahmed-g-gad/apothem profile edit), then rerun the command with update in place of install to apply them.

It also runs straight from the repository:

npx github:ahmed-g-gad/apothem install --harness claude-code

Every command in the CLI reference works in this form; substitute npx @ahmed-g-gad/apothem for apothem. This is also the install path for OpenCode and every other tool that exposes no separate plugin or extension registry — Apothem syncs those straight into their native config directory (npx @ahmed-g-gad/apothem install --harness opencode).

Verify:

npx @ahmed-g-gad/apothem --version
npx @ahmed-g-gad/apothem verify --harness claude-code

3. One-shot installersCopy Anchor Link

Prerequisites: system Python 3.10+ on PATH (the installer offers to add the click / rich prerequisites for you); git and gpg for a network install, which clones the source and verifies its signed release tag (Git for Windows ships both).

The installer scripts resolve the latest signed release tag, verify its signature, place the Apothem source tree at ~/.apothem at that tag, create a starter profile when none exists, materialize your first harness, and verify the result, all in one run. The starter profile carries placeholder identity fields: edit it, then run apothem update --harness <name> to apply yours. Re-running is idempotent: an existing tree is re-checked-out to the resolved tag and the harness is re-materialized. The tag-pinned verified install is the default and recommended path.

Import the maintainer signing key once first. The installer stops when the key is not in your keyring. Check that the fingerprint reads 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163, the value SECURITY.md publishes. On Windows, git verify-tag reads the keyring of the gpg that ships with Git for Windows, so the import runs through Git's own bash:

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'

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

irm https://apothem.ahmedgad.com/install.ps1 | iex

The same scripts ship in a checkout under scripts/installer/ — install, uninstall, and update in .sh, .ps1, and .bat forms — so you can run them directly after cloning:

APOTHEM_HARNESS=claude-code sh scripts/installer/install.sh                                 # POSIX
$env:APOTHEM_HARNESS = 'claude-code'; pwsh -NoProfile -File scripts/installer/install.ps1   # Windows

Trust modelCopy Anchor Link

With no APOTHEM_REF set, the installer resolves the highest vMAJOR.MINOR.PATCH release tag and checks that out — never the moving main branch. Before any configuration is materialized, the fetched tag's signature is verified with git verify-tag; an unsigned, tampered, or unverifiable tag aborts the install before anything is written. A signed tag whose maintainer public key is not yet in the local keyring aborts with key-import guidance instead: import the key as shown above, check its fingerprint against the value published in SECURITY.md, and re-run. Pin a specific release with APOTHEM_REF:

APOTHEM_REF=vMAJOR.MINOR.PATCH sh -c "$(curl -fsSL https://apothem.ahmedgad.com/install.sh)"

Replace vMAJOR.MINOR.PATCH with a tag from the releases page. The oldest release tag is a lightweight tag with no signature of its own, so the tag check aborts on it even though its commit is signed; every later release tag is annotated and signed. The SECURITY.md release-signing section lists each tag and how to verify it.

Explicit overrides relax the default. APOTHEM_ALLOW_UNVERIFIED=1 downgrades a verification failure to a warning and proceeds, for air-gapped or local use, or to install a release that predates tag signing. APOTHEM_REF=main checks out the moving branch without verification only together with APOTHEM_ALLOW_UNVERIFIED=1. With APOTHEM_REF=main alone, the installer fetches main into APOTHEM_HOME, then aborts before any configuration is materialized, because a branch is not a signed release tag. A local checkout via APOTHEM_SOURCE fetches nothing and skips verification.

APOTHEM_VERIFY=checksum is the middle path for a host that does not yet hold the maintainer's public key: instead of cloning, the installer downloads the release's platform archive and its SHA256SUMS, aborts on a digest mismatch before extracting anything, and warns that a matching digest proves the archive is the one the release lists, not who published it.

The engine then runs directly from the placed tree. Every third-party dependency except click and rich is vendored inside the source tree, and the entry point puts that vendor directory on sys.path itself:

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

Both scripts read the same configuration environment variables (APOTHEM_HOME, APOTHEM_REPO, APOTHEM_REF, APOTHEM_ALLOW_UNVERIFIED, APOTHEM_VERIFY, APOTHEM_RELEASE_BASE, APOTHEM_SOURCE, APOTHEM_HARNESS, APOTHEM_PROFILE, APOTHEM_SKIP_VERIFY, APOTHEM_AUTO_INSTALL_DEPS, APOTHEM_BIN_DIR); see Installer environment variables for the full table and Self-contained runtime for how the python -m invocation model works.

The apothem command. After a successful install, the installer writes an apothem shim that forwards to the bundled engine — POSIX into $HOME/.local/bin, Windows into %LOCALAPPDATA%\Microsoft\WindowsApps (a user directory already on the default Windows PATH). The installer never edits your PATH. Once the directory is on PATH you run apothem <command> directly, with no manual PYTHONPATH.

Verify:

apothem verify --harness claude-code

# or, before the shim is on PATH, from the bundled source:
PYTHONPATH="$HOME/.apothem/src" python -m apothem verify --harness claude-code

4. VS Code family extensionCopy Anchor Link

Prerequisites: VS Code, Node.js 18+, and system Python 3.10+ on PATH.

The Apothem for VS Code extension is on the Visual Studio Marketplace as ahmed-g-gad.apothem-vscode: install it from the Extensions view or with code --install-extension ahmed-g-gad.apothem-vscode. It also installs from an apothem.vsix package: code --install-extension apothem.vsix, or the editor's Install from VSIX… command. The release workflow signs the package and attaches it to each GitHub Release. Releases published before the workflow packaged the extension carry no .vsix; when the latest release lacks it, build the package from a checkout with the vsce release locked in tools/vsce/ (that vsce release needs Node.js 22 or later): run npm ci --prefix tools/vsce --ignore-scripts, then cd vscode-extension && ../tools/vsce/node_modules/.bin/vsce package --no-dependencies --out apothem.vsix. A copy installed from an earlier apothem.vsix carries the identifier ahmed-g-gad.apothem; uninstall it (code --uninstall-extension ahmed-g-gad.apothem) so the two copies do not both register the same commands. One extension covers the editors of the VS Code family. Its palette commands (Apothem: Install, Verify, Update, Uninstall, Doctor) run the same engine through the configured runner (npx @ahmed-g-gad/apothem@<extension version> by default, so the extension runs the engine version it shipped with; point the apothem.runner user setting at a local checkout to run from source). Install, Verify, Update and Uninstall ask which harness to act on, offering the editor's own harness first; all is a choice, never the default. The apothem.runner setting is machine-scoped, so a workspace cannot change it, and the extension runs only in a trusted workspace.

Verify: run the Apothem: Verify command from the editor's command palette, or from a terminal:

npx @ahmed-g-gad/apothem verify --harness claude-code

5. Command-line bootstrap (extension host)Copy Anchor Link

Prerequisites: its host command-line tool, Node.js 18+, and system Python 3.10+ on PATH.

Install Apothem as an extension straight from the repository — the command carries the exact host and harness slug:

gemini extensions install https://github.com/ahmed-g-gad/apothem

This extension is a bootstrap, not the full install on its own: it loads an Apothem context file and adds a /apothem command that shells out to the engine (npx @ahmed-g-gad/apothem). Materialize the full harness by running the install through it:

npx @ahmed-g-gad/apothem install --harness gemini-cli --project .

Verify:

npx @ahmed-g-gad/apothem verify --harness gemini-cli --project .

6. Command-line bootstrap (qwen-code host)Copy Anchor Link

Prerequisites: its host command-line tool, Node.js 18+, and system Python 3.10+ on PATH.

Install Apothem as a --harness qwen-code extension straight from the repository:

qwen extensions install ahmed-g-gad/apothem

Like the channel-5 extension, this is a bootstrap: it loads an Apothem context file and shells out to the engine. Materialize the full harness by running the install through it:

npx @ahmed-g-gad/apothem install --harness qwen-code

Verify:

npx @ahmed-g-gad/apothem verify --harness qwen-code

7. Command-line bootstrap (plugin host)Copy Anchor Link

Prerequisites: its host command-line tool, Node.js 18+, and system Python 3.10+ on PATH.

Add the repository as a plugin marketplace, then install the plugin — the command carries the exact host and harness slug:

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

The two --sparse paths fetch only the marketplace listing and the plugin, not the whole repository; a full clone can run past the host's 30-second clone limit on a slow disk, such as a Windows drive under WSL.

Like the channel-5 and channel-6 extensions, this is a bootstrap that shells out to the engine. The plugin bundles one entry skill; its manifest is a root plugin.json, and the plugin host's harness page describes the layout and what the plugin leaves to the engine. Materialize the full harness by running the install through it:

npx @ahmed-g-gad/apothem install --harness codex

Verify:

npx @ahmed-g-gad/apothem verify --harness codex

8. Direct engine (python -m apothem)Copy Anchor Link

Prerequisites: system Python 3.10+ with the click and rich packages importable, plus a checkout of the repository. No Node.js required.

Run the engine straight from a clone. The entry point puts the vendored dependencies (src/apothem/_vendor) on sys.path, so with click and rich importable, PYTHONPATH=src is the whole setup:

git clone https://github.com/ahmed-g-gad/apothem
cd apothem
PYTHONPATH=src python -m apothem install --harness claude-code

As with the npm shim, a first install on a machine with no profile creates the starter profile at ~/.config/apothem/profile.yaml and continues.

Verify:

PYTHONPATH=src python -m apothem verify --harness claude-code

Verify any installCopy Anchor Link

Every channel above names its own verification command. The two general forms are:

PYTHONPATH="$HOME/.apothem/src" python -m apothem verify --harness claude-code

npx @ahmed-g-gad/apothem verify --harness claude-code

Replace the harness name with whichever adapter you installed; see the harness list for all supported names. To check every installed adapter at once (its verify and its hook commands), run doctor in place of verify --harness NAME, in whichever form you used above: apothem doctor, PYTHONPATH="$HOME/.apothem/src" python -m apothem doctor, or npx @ahmed-g-gad/apothem doctor. For the plugin path, run /plugin inside Claude Code and confirm apothem is listed as installed.

Prerequisites at a glanceCopy Anchor Link

• Python 3.10 or later — the paths that locate it do so by name, and the names differ by path. The npm shim tries python3, python, then py -3. The installers try python3, python, and the versioned names python3.14 down to python3.10.
• click and rich importable under that interpreter — the two terminal-facing dependencies the engine does not vendor. The installers check both, name anything missing, and offer to install it for you — with your confirmation, or automatically with --yes (-Yes on PowerShell) or APOTHEM_AUTO_INSTALL_DEPS=1. On every other channel, a missing package stops the engine with an error (exit 1) that names the exact command for the interpreter it found, with the version constraints Apothem is tested against (<interpreter> -m pip install "click==…" "rich>=…"); with --json the same error arrives as a JSON envelope with code runtime.dependency_missing.
• Node.js 18 or later — only the paths that run npx: the npm shim (2), the VS Code-family extension (4), and the command-line bootstraps (5–7).
• End-of-life runtimes. Python 3.10 reached upstream end of life on 2026-10-01, and Node.js 18 and 20 on 2025-04-30 and 2026-04-30. Apothem still supports them as its declared floors and tests each one in CI, but they no longer receive upstream security fixes, so prefer Python 3.11 or newer and Node.js 22 or newer. The runtime-floor policy explains how a floor is raised.
• Git — installer path only, and only for the network form (the script clones the source; a local checkout needs no clone).
• Claude Code — plugin path only. VS Code and each command-line bootstrap's own host tool are needed only for their own channel (4–7).

Next guidesCopy Anchor Link