Installation

Apothem is a harness-agnostic framework that materializes into each supported AI tool's native configuration directory via per-harness adapters under src/apothem/harnesses/<harness>/. The guide below walks through the Claude Code adapter install (destination ~/.claude/) — the most common path; see docs/harnesses/<harness>.md for the per-harness install matrix when targeting a different tool. To adopt the ecosystem on a fresh machine, run the one-shot installer or clone the repository into the adapter's destination directory and ratify the toolchain.

Repository naming

The repository is named apothem; for the Claude Code adapter the install destination is ~/.claude. The two are different on purpose: GitHub does not permit repository names that begin with a . character (the leading dot is reserved for hidden filesystem entries), so the repository uses the discoverable name apothem (matching the package name in pyproject.toml) and the destination uses the conventional hidden-dir form. This is the same pattern as oh-my-zsh, nvm, pyenv, and most home-directory frameworks: a discoverable repo name on GitHub plus a short, hidden install destination on disk. Other harnesses materialize into their own native paths — see docs/harnesses/ for the per-harness destination matrix.

Prerequisites

• Python 3.10 or newer (the codebase tests against 3.10–3.13).
• Git 2.30+.
• A POSIX shell (bash) on macOS / Linux, or Windows PowerShell 5.1+ on Windows. The hook layer ships paired Bash and PowerShell wrappers; both are exercised in CI.
• Optional: uv (recommended) or pip-tools for fully reproducible dependency lock files.

Step 0 — choose an install path

Path	Command	When to use
One-shot installer (POSIX)	curl -fsSL https://raw.githubusercontent.com/Gad360/apothem/main/scripts/installer/install.sh \| bash	macOS / Linux / WSL — fastest path
One-shot installer (PowerShell)	irm https://raw.githubusercontent.com/Gad360/apothem/main/scripts/installer/install.ps1 \| iex	Windows — fastest path
Manual clone	The four steps below	Total control; preferred for contributors

The installer is idempotent: re-running it fast-forwards an existing ~/.claude checkout to the latest main. See scripts/installer/install.sh or scripts/installer/install.ps1 for the full source — the scripts are short, prerequisite-checked, and configurable via environment variables (CLAUDE_INSTALL_DIR, CLAUDE_REMOTE_URL, CLAUDE_REF, CLAUDE_SKIP_PIP, CLAUDE_SKIP_VERIFY).

Step 1 — clone into your harness configuration directory

If you skipped the one-shot installer, clone manually. For the Claude Code adapter the destination is ~/.claude (the Claude Code hook dispatcher resolves the ecosystem root from $CLAUDE_PROJECT_DIR first, then $LLM_PROJECT_DIR, then falls back to $HOME/.claude, so this path is the zero-config default). For other harnesses substitute the destination documented at docs/harnesses/<harness>.md.

git clone https://github.com/Gad360/apothem.git ~/.claude

If you already have a ~/.claude directory you want to preserve, clone elsewhere and set CLAUDE_PROJECT_DIR=/path/to/checkout in your shell profile.

Step 2 — install the Python dependencies

Editable install with the dev extra brings in ruff, mypy, pytest, pytest-cov, bandit, and pip-audit so the local quality gates match what CI runs.

cd ~/.claude
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

To preview the documentation site locally, install the docs extra as well:

python -m pip install -e ".[docs]"
mkdocs serve

Step 3 — verify the install

Run the bundled validators. Each one prints a per-check summary and exits non-zero on failure.

python scripts/dev/validate_ecosystem.py
python -m pytest -q

The first command sweeps every artifact class registered in CLAUDE.md §7; the second runs the full test suite.

Step 4 — register hooks (optional)

Hooks fire on tool events when the host harness loads its native settings file (for the Claude Code adapter: ~/.claude/settings.json, or ~/.claude/settings-unix.json on POSIX hosts; other harnesses use the analogous file documented under docs/harnesses/<harness>.md). The shipped settings file already wires the canonical event set; no additional configuration is needed.

To verify the dispatcher resolves a Python interpreter and the bootstrap stub completes cleanly:

echo '{"event":"SessionStart"}' | bash src/apothem/hooks/lib/bootstrap.sh SessionStart

A JSON envelope with exit 0 on stdout indicates the hook layer is healthy.

Upgrading

Pull the latest tag and re-run the install:

cd ~/.claude
git fetch --tags
git checkout vX.Y.Z
python -m pip install -e ".[dev]"
python scripts/dev/validate_ecosystem.py

The Release engineering policy describes the support window (N-2) and the breaking-change policy.

Uninstalling

The ecosystem is fully self-contained — no system files are touched.

rm -rf ~/.claude

If you set CLAUDE_PROJECT_DIR in your shell profile, remove that line as well.