설치

Apothem은 2분 이내에 설치되며 기존 하니스 구성과 함께 동작합니다. 모든 경로는 동일한 자체 완결형 엔진을 실행합니다 — 소스 트리가 벤더링된 종속성을 담고 있으며, 시스템 Python 3.10 이상에서 체크아웃으로부터 실행됩니다 (자체 완결형 런타임 참조).

모든 경로가 공유하는 두 가지 사전 요건: PATH에 있는 시스템 Python 3.10 이상, 그리고 그 인터프리터에서 임포트할 수 있는 click과 rich 패키지입니다. npm 심(채널 2), VS Code 계열 확장(채널 4), 명령줄 부트스트랩(채널 5–7)은 npx를 실행하기 위해 추가로 Node.js 18 이상이 필요합니다. Python 3.10과 Node.js 18 및 20은 업스트림 수명 종료를 지났습니다. 이들은 계속 지원되고 테스트되지만, 더 새로운 버전을 권장합니다(사전 요건 한눈에 참조). 아래 각 채널의 섹션은 해당 채널의 정확한 사전 요건, 복사해서 바로 쓸 수 있는 명령 하나, 그리고 검증 단계를 다시 제시합니다.

채널 선택Copy Anchor Link

여덟 개의 설치 채널이 있습니다. 이미 일하는 방식에 맞춰 고르세요.

모든 경로는 멱등적입니다. 재실행은 안전하며 같은 상태로 수렴합니다.

1. Claude Code 플러그인Copy Anchor Link

사전 요건: Claude Code, 그리고 PATH에 있는 시스템 Python 3.10+.

플러그인 경로는 전적으로 Claude Code 내부에서 실행됩니다. Apothem 엔진을 슬래시 명령, 위임 작업자, 스킬, 규칙, 훅과 함께 번들하며, 이 모두를 자체 완결형 플러그인 트리에서 실행할 수 있습니다.

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

설치 후에는 Apothem 명령 세트, 번들된 위임 작업자, 스킬, 그리고 네 가지 출력 스타일(/output-style로 또는 /config에서 하나를 고릅니다)을 모든 Claude Code 세션에서 사용할 수 있습니다. 플러그인은 각 명령을 스킬로 제공합니다. 스킬은 SKILL.md와, 필요할 때 로드하는 세부 내용을 담아 그 옆에 두는 references/ 폴더로 이루어지므로, Claude Code는 플러그인의 접두사를 붙여 호출합니다: /apothem:plan-spec, /apothem:security-audit 등. 두 이름은 Claude Code 자체가 사용합니다. /plan은 플랜 모드로 들어가고 /code-review는 번들된 리뷰를 실행하므로, Apothem 명령을 쓰려면 /apothem:plan과 /apothem:code-review를 입력하세요. 플러그인 대신 Apothem 엔진이 Claude Code에 설치하는 경우, 같은 스킬이 접두사 없이 ~/.claude/skills/에 쓰이며, 개인 code-review 스킬이 번들된 /code-review를 대체합니다(그 /review 별칭은 여전히 번들된 것을 실행합니다). 두 이름, projectify와 workflow는 네이티브 스킬이기도 합니다. 플러그인과 엔진 설치가 제공하는 것은 네이티브 스킬이며, 명령에서 파생한 스킬이 아닙니다. 명령이 어떻게 나뉘는지는 Claude Code를, 전체 명령 카탈로그는 슬래시 명령을 참조하세요.

검증: Claude Code 내부에서 /plugin을 실행하여 apothem이 설치됨으로 나열되는지 확인하거나, 터미널에서 드리프트 보고서를 확인하세요.

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

2. npm 심(npx)Copy Anchor Link

사전 요건: Node.js 18+(npx용)와 PATH에 있는 시스템 Python 3.10+. 심은 인터프리터를 찾아 모든 CLI 명령을 번들된 엔진으로 전달합니다 — 시스템에 영구적으로 배치되는 것은 없습니다. 심은 python3, python, py -3을 이 순서대로 시도합니다. **APOTHEM_PYTHON**을 인터프리터 경로로 설정하면 그 인터프리터를 먼저 시도하며, Python이 설치되어 있지만 PATH에 없을 때, 또는 여러 버전이 설치되어 있고 그중 특정 버전을 원할 때 필요한 설정입니다. 지정한 인터프리터도 여전히 Python 3.10+ 검사를 통과해야 합니다. 통과하지 못하면 심은 대신 python3, python, py -3을 이 순서대로 시도합니다.

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

프로필이 없는 머신에서는 이 첫 install이 ~/.config/apothem/profile.yaml에 초기 프로필을 생성하고 그 사실을 알립니다. 이 프로필의 신원 필드는 플레이스홀더입니다. 이를 개인화한 다음(npx @ahmed-g-gad/apothem profile edit), 적용하려면 install 대신 update로 명령을 다시 실행하세요.

저장소에서 곧바로 실행할 수도 있습니다.

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

CLI 참조의 모든 명령이 이 형식으로 동작합니다. apothem 대신 npx @ahmed-g-gad/apothem을 쓰세요. 이는 별도의 플러그인이나 확장 레지스트리를 노출하지 않는 OpenCode와 그 밖의 모든 도구의 설치 경로이기도 합니다 — Apothem은 이 도구들을 네이티브 구성 디렉터리로 곧바로 동기화합니다 (npx @ahmed-g-gad/apothem install --harness opencode).

검증:

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

3. 원샷 설치 프로그램Copy Anchor Link

사전 요건: PATH에 있는 시스템 Python 3.10+(설치 프로그램이 click / rich 사전 요건을 대신 추가하겠다고 제안합니다). 네트워크 설치에는 git과 gpg가 필요하며, 네트워크 설치는 소스를 클론한 뒤 서명된 릴리스 태그를 검증합니다(Git for Windows에는 두 도구가 모두 포함되어 있습니다).

설치 스크립트는 한 번의 실행으로 서명된 최신 릴리스 태그를 해석하고, 그 서명을 검증하고, 해당 태그의 Apothem 소스 트리를 ~/.apothem에 배치하고, 프로필이 없으면 초기 프로필을 생성하고, 첫 하니스를 머티리얼라이즈하고, 결과를 검증합니다. 초기 프로필에는 플레이스홀더 신원 필드가 들어 있습니다. 프로필을 편집한 다음 apothem update --harness <name>을 실행하여 여러분의 값을 적용하세요. 재실행은 멱등적입니다. 기존 트리는 해석된 태그로 다시 체크아웃되고 하니스는 다시 머티리얼라이즈됩니다. 태그에 고정된 검증 설치가 기본이자 권장 경로입니다.

먼저 메인테이너 서명 키를 한 번 가져오세요. 키가 사용자의 키링에 없으면 설치 프로그램이 중단됩니다. 지문이 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163인지 확인하세요. 이 값은 SECURITY.md에 게시되어 있습니다. Windows에서는 git verify-tag가 Git for Windows에 포함된 gpg의 키링을 읽으므로, 키 가져오기는 Git 자체의 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

같은 스크립트가 체크아웃의 scripts/installer/ 아래에 함께 들어 있으므로 — .sh, .ps1, .bat 형식의 install, uninstall, update — 클론한 뒤 직접 실행할 수 있습니다.

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

신뢰 모델Copy Anchor Link

APOTHEM_REF가 설정되지 않으면 설치 프로그램은 가장 높은 vMAJOR.MINOR.PATCH 릴리스 태그를 해석하고 그 태그를 체크아웃합니다 — 움직이는 main 브랜치는 결코 체크아웃하지 않습니다. 구성이 머티리얼라이즈되기 전에 가져온 태그의 서명을 git verify-tag로 검증합니다. 서명되지 않았거나, 변조되었거나, 검증할 수 없는 태그는 아무것도 기록하기 전에 설치를 중단합니다. 서명은 되어 있지만 메인테이너 공개 키가 아직 로컬 키링에 없는 태그는 대신 키 가져오기 안내와 함께 중단됩니다. 위에 표시된 대로 키를 가져오고, 그 지문을 SECURITY.md에 게시된 값과 대조한 뒤 다시 실행하세요. 특정 릴리스를 고정하려면 APOTHEM_REF를 사용하세요:

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

vMAJOR.MINOR.PATCH를 릴리스 페이지의 태그로 바꾸세요. 가장 오래된 릴리스 태그는 자체 서명이 없는 경량 태그이므로, 그 커밋이 서명되어 있더라도 태그 검사가 이 태그에서 중단됩니다. 그 이후의 모든 릴리스 태그는 주석 태그이며 서명되어 있습니다. SECURITY.md의 릴리스 서명 섹션에 각 태그와 그 검증 방법이 나열되어 있습니다.

명시적 재정의는 기본 동작을 완화합니다. APOTHEM_ALLOW_UNVERIFIED=1은 검증 실패를 경고로 낮추고 계속 진행합니다. 에어갭 또는 로컬 용도이거나, 태그 서명 이전에 나온 릴리스를 설치하려는 경우에 사용합니다. APOTHEM_REF=main은 APOTHEM_ALLOW_UNVERIFIED=1과 함께 지정할 때에만 검증 없이 움직이는 브랜치를 체크아웃합니다. APOTHEM_REF=main만 지정하면, 설치 프로그램은 main을 APOTHEM_HOME으로 가져온 뒤 구성을 머티리얼라이즈하기 전에 중단합니다. 브랜치는 서명된 릴리스 태그가 아니기 때문입니다. APOTHEM_SOURCE를 통한 로컬 체크아웃은 아무것도 가져오지 않으며 검증도 건너뜁니다.

APOTHEM_VERIFY=checksum은 메인테이너의 공개 키를 아직 보유하지 않은 호스트를 위한 중간 경로입니다. 설치 프로그램은 클론하는 대신 릴리스의 플랫폼 아카이브와 그 SHA256SUMS를 다운로드하고, 다이제스트가 일치하지 않으면 아무것도 추출하기 전에 중단하며, 일치하는 다이제스트는 그 아카이브가 릴리스에 나열된 아카이브라는 것을 증명할 뿐 누가 게시했는지는 증명하지 않는다고 경고합니다.

그런 다음 엔진은 배치된 트리에서 직접 실행됩니다. click과 rich를 제외한 모든 서드파티 종속성은 소스 트리 내부에 벤더링되어 있으며, 진입점이 그 벤더 디렉터리를 직접 sys.path에 올립니다.

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

두 스크립트 모두 동일한 구성 환경 변수(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)를 읽습니다. 전체 표는 설치 프로그램 환경 변수를, python -m 호출 모델의 작동 방식은 자체 완결형 런타임을 참조하세요.

apothem 명령. 설치가 성공하면 설치 프로그램은 번들된 엔진으로 전달하는 apothem 심을 씁니다 — POSIX에서는 $HOME/.local/bin에, Windows에서는 %LOCALAPPDATA%\Microsoft\WindowsApps(기본 Windows PATH에 이미 포함된 사용자 디렉터리)에 씁니다. 설치 프로그램은 여러분의 PATH를 결코 편집하지 않습니다. 그 디렉터리가 PATH에 오르면 수동 PYTHONPATH 설정 없이 apothem <command>를 직접 실행합니다.

검증:

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 계열 확장Copy Anchor Link

사전 요건: VS Code, Node.js 18+, 그리고 PATH에 있는 시스템 Python 3.10+.

Apothem for VS Code 확장은 Visual Studio Marketplace에 ahmed-g-gad.apothem-vscode로 등록되어 있습니다. 확장 보기에서 설치하거나 code --install-extension ahmed-g-gad.apothem-vscode를 실행하세요. 또한 apothem.vsix 패키지로도 설치합니다: code --install-extension apothem.vsix를 실행하거나 에디터의 Install from VSIX… 명령을 사용하세요. 릴리스 워크플로가 패키지에 서명하고 각 GitHub Release에 첨부합니다. 워크플로가 확장을 패키징하기 전에 게시된 릴리스에는 .vsix가 없습니다. 최신 릴리스에 없으면, tools/vsce/에 고정된 vsce 릴리스(이 vsce 릴리스에는 Node.js 22 이상이 필요합니다)로 체크아웃에서 패키지를 빌드하세요. npm ci --prefix tools/vsce --ignore-scripts를 실행한 다음 cd vscode-extension && ../tools/vsce/node_modules/.bin/vsce package --no-dependencies --out apothem.vsix를 실행합니다. 이전 apothem.vsix로 설치한 사본은 식별자 ahmed-g-gad.apothem을 가지므로, 두 사본이 같은 명령을 모두 등록하지 않도록 code --uninstall-extension ahmed-g-gad.apothem으로 제거하세요. 하나의 확장이 VS Code 계열의 에디터를 모두 다룹니다. 팔레트 명령(Apothem: Install, Verify, Update, Uninstall, Doctor)은 구성된 러너를 통해 동일한 엔진을 실행합니다(기본 러너는 npx @ahmed-g-gad/apothem@<extension version>이므로 확장은 함께 배포된 엔진 버전을 실행합니다. 소스에서 실행하려면 apothem.runner 사용자 설정이 로컬 체크아웃을 가리키도록 하세요). Install, Verify, Update, Uninstall은 어느 하니스에 적용할지 묻고 에디터 자체의 하니스를 먼저 제시합니다. all은 선택지 중 하나일 뿐 결코 기본값이 아닙니다. apothem.runner 설정은 머신 범위이므로 워크스페이스가 변경할 수 없으며, 확장은 신뢰할 수 있는 워크스페이스에서만 실행됩니다.

검증: 에디터의 명령 팔레트에서 Apothem: Verify 명령을 실행하거나, 터미널에서 다음을 실행하세요.

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

5. 명령줄 부트스트랩(확장 호스트)Copy Anchor Link

사전 요건: 해당 호스트 명령줄 도구, Node.js 18+, 그리고 PATH에 있는 시스템 Python 3.10+.

저장소에서 곧바로 Apothem을 확장으로 설치하세요 — 명령에 정확한 호스트와 하니스 slug가 들어 있습니다.

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

이 확장은 그 자체로 전체 설치가 아니라 부트스트랩입니다. Apothem 컨텍스트 파일을 로드하고, 엔진으로 셸 아웃하는(npx @ahmed-g-gad/apothem) /apothem 명령을 추가합니다. 이 확장을 통해 설치를 실행하여 전체 하니스를 머티리얼라이즈하세요.

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

검증:

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

6. 명령줄 부트스트랩(qwen-code 호스트)Copy Anchor Link

사전 요건: 해당 호스트 명령줄 도구, Node.js 18+, 그리고 PATH에 있는 시스템 Python 3.10+.

저장소에서 곧바로 Apothem을 --harness qwen-code 확장으로 설치하세요.

qwen extensions install ahmed-g-gad/apothem

채널 5의 확장과 마찬가지로 이것은 부트스트랩입니다. Apothem 컨텍스트 파일을 로드하고 엔진으로 셸 아웃합니다. 이 확장을 통해 설치를 실행하여 전체 하니스를 머티리얼라이즈하세요.

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

검증:

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

7. 명령줄 부트스트랩(플러그인 호스트)Copy Anchor Link

사전 요건: 해당 호스트 명령줄 도구, Node.js 18+, 그리고 PATH에 있는 시스템 Python 3.10+.

저장소를 플러그인 마켓플레이스로 추가한 다음 플러그인을 설치하세요 — 명령에 정확한 호스트와 하니스 slug가 들어 있습니다.

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

두 --sparse 경로는 저장소 전체가 아니라 마켓플레이스 목록과 플러그인만 가져옵니다. 전체 클론은 WSL 아래의 Windows 드라이브처럼 느린 디스크에서 호스트의 30초 클론 제한을 넘길 수 있습니다.

채널 5와 채널 6의 확장과 마찬가지로 이것은 엔진으로 셸 아웃하는 부트스트랩입니다. 플러그인은 진입 스킬 하나를 번들합니다. 그 매니페스트는 루트의 plugin.json이며, 플러그인 호스트의 하니스 페이지가 레이아웃과 플러그인이 엔진에 맡기는 작업을 설명합니다. 이 플러그인을 통해 설치를 실행하여 전체 하니스를 머티리얼라이즈하세요.

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

검증:

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

8. 직접 엔진(python -m apothem)Copy Anchor Link

사전 요건: click과 rich 패키지를 임포트할 수 있는 시스템 Python 3.10+, 그리고 저장소의 체크아웃. Node.js는 필요하지 않습니다.

클론에서 곧바로 엔진을 실행하세요. 진입점이 벤더링된 종속성 (src/apothem/_vendor)을 sys.path에 올리므로, click과 rich를 임포트할 수 있다면 PYTHONPATH=src가 설정의 전부입니다.

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

npm 심과 마찬가지로, 프로필이 없는 머신에서 첫 install은 ~/.config/apothem/profile.yaml에 초기 프로필을 생성하고 계속 진행합니다.

검증:

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

어떤 설치든 검증하기Copy Anchor Link

위의 모든 채널은 각자의 검증 명령을 제시합니다. 두 가지 일반 형식은 다음과 같습니다.

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

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

하니스 이름을 설치한 어댑터로 바꾸세요. 지원되는 모든 이름은 하니스 목록을 참조하세요. 설치된 모든 어댑터를 한 번에 점검하려면(각 어댑터의 verify와 훅 명령), verify --harness NAME 대신 doctor를 위에서 사용한 형식 그대로 실행하세요. 즉 apothem doctor, PYTHONPATH="$HOME/.apothem/src" python -m apothem doctor, 또는 npx @ahmed-g-gad/apothem doctor입니다. 플러그인 경로의 경우 Claude Code 내부에서 /plugin을 실행하여 apothem이 설치됨으로 나열되는지 확인하세요.

사전 요건 한눈에Copy Anchor Link

• Python 3.10 이상 — 이를 찾는 경로는 이름으로 찾으며, 그 이름은 경로마다 다릅니다. npm 심은 python3, python, py -3 순으로 시도합니다. 설치 프로그램은 python3, python, 그리고 버전이 붙은 이름 python3.14부터 python3.10까지 시도합니다.
• click과 rich 임포트 가능(해당 인터프리터에서) — 엔진이 벤더링하지 않는 터미널 대면 종속성 두 가지입니다. 설치 프로그램은 둘 다 확인하고, 누락된 항목의 이름을 알려 주며, 대신 설치하겠다고 제안합니다 — 여러분의 확인을 받아서, 또는 --yes(PowerShell에서는 -Yes)나 APOTHEM_AUTO_INSTALL_DEPS=1이 있으면 자동으로. 그 밖의 모든 채널에서는 누락된 패키지가 오류(종료 코드 1)와 함께 엔진을 중지시키며, 이 오류는 엔진이 찾은 인터프리터에 맞는 정확한 명령을, Apothem을 테스트하는 기준이 되는 버전 제약 조건과 함께 제시합니다 (<interpreter> -m pip install "click==…" "rich>=…"). --json을 사용하면 같은 오류가 코드 runtime.dependency_missing이 담긴 JSON 엔벨로프로 전달됩니다.
• Node.js 18 이상 — npx를 실행하는 경로에서만 필요합니다. npm 심(2), VS Code 계열 확장(4), 명령줄 부트스트랩(5–7)입니다.
• 수명 종료 런타임. Python 3.10은 2026-10-01에, Node.js 18과 20은 각각 2025-04-30과 2026-04-30에 업스트림 수명 종료에 도달했습니다. Apothem은 이들을 선언된 최저 버전으로서 여전히 지원하고 CI에서 각각을 테스트하지만, 이들은 더 이상 업스트림 보안 수정을 받지 않으므로 Python 3.11 이상과 Node.js 22 이상을 우선 사용하세요. 런타임 최저 버전 정책이 최저 버전을 올리는 방법을 설명합니다.
• Git — 설치 프로그램 경로에서만, 그것도 네트워크 형식에서만 필요합니다 (스크립트가 소스를 클론합니다. 로컬 체크아웃은 클론이 필요하지 않습니다).
• Claude Code — 플러그인 경로에서만 필요합니다. VS Code와 각 명령줄 부트스트랩 자체의 호스트 도구는 각자의 채널(4–7)에서만 필요합니다.

다음 가이드Copy Anchor Link