Instalasi

Apothem terpasang dalam waktu kurang dari dua menit dan bekerja berdampingan dengan konfigurasi harness Anda yang sudah ada. Setiap jalur menjalankan mesin mandiri yang sama — pohon sumber membawa dependensinya yang di-vendor dan berjalan dari checkout pada Python sistem 3.10 atau yang lebih baru (lihat runtime mandiri).

Dua prasyarat berlaku untuk setiap jalur: Python 3.10 atau lebih baru milik sistem pada PATH, dengan paket click dan rich yang dapat diimpor di bawahnya. Shim npm (kanal 2), ekstensi keluarga VS Code (kanal 4), dan bootstrap baris perintah (kanal 5–7) juga membutuhkan Node.js 18 atau lebih baru untuk menjalankan npx. Python 3.10 serta Node.js 18 dan 20 telah melewati akhir masa pakai (end of life) di upstream; ketiganya tetap didukung dan diuji, tetapi versi yang lebih baru lebih disarankan (lihat Prasyarat sekilas). Bagian masing-masing kanal di bawah ini mengulang prasyarat persisnya, satu perintah siap-salin, dan langkah verifikasi.

Pilih kanalCopy Anchor Link

Delapan kanal instalasi tersedia. Pilih berdasarkan cara Anda sudah bekerja.

Setiap jalur bersifat idempoten: menjalankan ulang aman dan konvergen ke keadaan yang sama.

1. Plugin Claude CodeCopy Anchor Link

Prasyarat: Claude Code, dan Python sistem 3.10+ pada PATH.

Jalur plugin berjalan sepenuhnya di dalam Claude Code. Jalur ini membundel mesin Apothem bersama perintah slash, pekerja terdelegasi, skill, aturan, dan hook-nya, yang semuanya dapat dijalankan dari pohon plugin mandiri:

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

Setelah instalasi, set perintah Apothem, pekerja terdelegasi yang disertakan, skill, dan empat output-style (pilih salah satu dengan /output-style atau dari /config) tersedia di setiap sesi Claude Code. Plugin mengirim setiap perintah sebagai skill, yaitu sebuah SKILL.md dengan detail yang dimuatnya sesuai kebutuhan di folder references/ di sebelahnya, sehingga Claude Code memanggilnya dengan awalan plugin: /apothem:plan-spec, /apothem:security-audit, dan seterusnya. Dua nama sudah dipakai oleh Claude Code sendiri: /plan masuk ke mode rencana dan /code-review menjalankan tinjauan bawaan, jadi ketik /apothem:plan dan /apothem:code-review untuk perintah Apothem. Ketika mesin Apothem dipasang ke Claude Code alih-alih plugin, skill yang sama ditulis ke ~/.claude/skills/ tanpa awalan, dan skill pribadi code-review menggantikan /code-review bawaan (aliasnya, /review, tetap menjalankan yang bawaan). Dua nama, projectify dan workflow, juga merupakan skill native; skill native itulah yang dikirim oleh plugin dan instalasi mesin, bukan skill yang diturunkan dari perintah. Lihat Claude Code untuk cara perintah dipecah, dan Perintah slash untuk katalog perintah lengkap.

Verifikasi: jalankan /plugin di dalam Claude Code dan konfirmasikan bahwa apothem tercantum sebagai terpasang, atau periksa laporan penyimpangan dari terminal:

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

2. Shim npm (npx)Copy Anchor Link

Prasyarat: Node.js 18+ (untuk npx) dan Python sistem 3.10+ pada PATH. Shim menemukan interpreter dan meneruskan setiap perintah CLI ke mesin yang disertakan — tidak ada yang ditempatkan secara permanen di sistem Anda. Shim mencoba python3, python, lalu py -3 dalam urutan itu; setel APOTHEM_PYTHON ke jalur interpreter agar interpreter itu dicoba lebih dahulu, yang Anda perlukan ketika Python terpasang tetapi tidak ada di PATH, atau ketika beberapa versi terpasang dan Anda menginginkan versi tertentu. Interpreter yang Anda sebutkan tetap harus lolos pemeriksaan Python 3.10+; jika tidak lolos, shim kembali ke python3, python, lalu py -3.

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

Pada komputer tanpa profil, install pertama ini membuat profil awal di ~/.config/apothem/profile.yaml dan memberitahukannya. Bidang identitasnya berupa placeholder: personalisasikan bidang tersebut (npx @ahmed-g-gad/apothem profile edit), lalu jalankan ulang perintah dengan update sebagai pengganti install untuk menerapkannya.

Shim ini juga berjalan langsung dari repositori:

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

Setiap perintah dalam referensi CLI berfungsi dalam bentuk ini; gunakan npx @ahmed-g-gad/apothem sebagai pengganti apothem. Ini juga jalur instalasi untuk OpenCode dan setiap alat lain yang tidak mengekspos registri plugin atau ekstensi terpisah — Apothem menyinkronkan alat-alat tersebut langsung ke direktori konfigurasi native-nya (npx @ahmed-g-gad/apothem install --harness opencode).

Verifikasi:

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

3. Pemasang satu langkahCopy Anchor Link

Prasyarat: Python sistem 3.10+ pada PATH (pemasang menawarkan untuk menambahkan prasyarat click / rich untuk Anda); git dan gpg untuk instalasi jaringan, yang mengkloning sumber dan memverifikasi tag rilisnya yang ditandatangani (Git for Windows menyertakan keduanya).

Skrip pemasang me-resolve tag rilis bertanda tangan terbaru, memverifikasi tanda tangannya, menempatkan pohon sumber Apothem di ~/.apothem pada tag tersebut, membuat profil awal bila belum ada, mematerialisasikan harness pertama Anda, dan memverifikasi hasilnya, semuanya dalam satu kali jalan. Profil awal membawa bidang identitas placeholder: sunting profil itu, lalu jalankan apothem update --harness <name> untuk menerapkan nilai milik Anda. Menjalankan ulang bersifat idempoten: pohon yang sudah ada di-checkout ulang ke tag yang di-resolve dan harness dimaterialisasikan ulang. Instalasi terverifikasi yang dipatok ke tag adalah jalur default dan yang direkomendasikan.

Impor kunci penandatanganan pemelihara sekali terlebih dahulu. Pemasang berhenti ketika kunci itu tidak ada di keyring Anda. Periksa bahwa sidik jari menunjukkan 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163, nilai yang dipublikasikan di SECURITY.md. Di Windows, git verify-tag membaca keyring dari gpg yang disertakan dengan Git for Windows, sehingga impor dijalankan melalui bash milik Git:

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

Skrip yang sama disertakan dalam checkout di bawah scripts/installer/ — install, uninstall, dan update dalam bentuk .sh, .ps1, dan .bat — sehingga Anda dapat menjalankannya langsung setelah mengkloning:

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

Model kepercayaanCopy Anchor Link

Bila APOTHEM_REF tidak disetel, pemasang me-resolve tag rilis vMAJOR.MINOR.PATCH tertinggi dan melakukan checkout tag itu — tidak pernah branch main yang terus bergerak. Sebelum konfigurasi apa pun dimaterialisasikan, tanda tangan tag yang diambil diverifikasi dengan git verify-tag; tag yang tidak bertanda tangan, telah dirusak, atau tidak dapat diverifikasi membatalkan instalasi sebelum apa pun ditulis. Tag bertanda tangan yang kunci publik pemeliharanya belum ada di keyring lokal justru membatalkan instalasi dengan panduan impor kunci: impor kunci seperti yang ditunjukkan di atas, periksa sidik jarinya terhadap nilai yang dipublikasikan di SECURITY.md, lalu jalankan ulang. Patok rilis tertentu dengan APOTHEM_REF:

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

Ganti vMAJOR.MINOR.PATCH dengan tag dari halaman rilis. Tag rilis tertua adalah tag ringan (lightweight) tanpa tanda tangannya sendiri, sehingga pemeriksaan tag membatalkan instalasi pada tag itu meskipun commit-nya bertanda tangan; setiap tag rilis setelahnya beranotasi dan bertanda tangan. Bagian penandatanganan rilis di SECURITY.md mencantumkan setiap tag dan cara memverifikasinya.

Penggantian eksplisit melonggarkan perilaku default. APOTHEM_ALLOW_UNVERIFIED=1 menurunkan kegagalan verifikasi menjadi peringatan lalu melanjutkan proses, untuk penggunaan air-gapped atau lokal, atau untuk memasang rilis yang terbit sebelum penandatanganan tag diterapkan. APOTHEM_REF=main melakukan checkout branch yang bergerak tanpa verifikasi hanya bersama APOTHEM_ALLOW_UNVERIFIED=1. Dengan APOTHEM_REF=main saja, pemasang mengambil main ke dalam APOTHEM_HOME, lalu membatalkan proses sebelum konfigurasi apa pun dimaterialisasikan, karena branch bukan tag rilis yang bertanda tangan. Checkout lokal melalui APOTHEM_SOURCE tidak mengambil apa pun dan melewati verifikasi.

APOTHEM_VERIFY=checksum adalah jalan tengah untuk host yang belum memegang kunci publik pemelihara: alih-alih mengkloning, pemasang mengunduh arsip platform rilis beserta SHA256SUMS-nya, membatalkan instalasi bila digest tidak cocok sebelum mengekstrak apa pun, dan memperingatkan bahwa digest yang cocok membuktikan bahwa arsip tersebut adalah arsip yang dicantumkan rilis, bukan siapa yang memublikasikannya.

Mesin kemudian berjalan langsung dari pohon yang ditempatkan. Setiap dependensi pihak ketiga kecuali click dan rich di-vendor di dalam pohon sumber, dan entry point sendiri yang menaruh direktori vendor tersebut di sys.path:

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

Kedua skrip membaca variabel lingkungan konfigurasi yang sama (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); lihat Variabel lingkungan pemasang untuk tabel lengkapnya dan Runtime mandiri untuk cara kerja model pemanggilan python -m.

Perintah apothem. Setelah instalasi berhasil, pemasang menulis shim apothem yang meneruskan ke mesin yang disertakan — di POSIX ke dalam $HOME/.local/bin, di Windows ke dalam %LOCALAPPDATA%\Microsoft\WindowsApps (direktori pengguna yang sudah ada pada PATH default Windows). Pemasang tidak pernah menyunting PATH Anda. Setelah direktori tersebut ada di PATH, Anda menjalankan apothem <command> secara langsung, tanpa PYTHONPATH manual.

Verifikasi:

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. Ekstensi keluarga VS CodeCopy Anchor Link

Prasyarat: VS Code, Node.js 18+, dan Python sistem 3.10+ pada PATH.

Ekstensi Apothem for VS Code tersedia di Visual Studio Marketplace sebagai ahmed-g-gad.apothem-vscode: pasang dari tampilan Extensions atau dengan code --install-extension ahmed-g-gad.apothem-vscode. Ekstensi ini juga dapat dipasang dari paket apothem.vsix: code --install-extension apothem.vsix, atau perintah Install from VSIX… milik editor. Alur kerja rilis menandatangani paket tersebut dan melampirkannya ke setiap GitHub Release. Rilis yang dipublikasikan sebelum alur kerja mengemas ekstensi tidak menyertakan .vsix; jika rilis terbaru tidak memilikinya, bangun paket dari checkout dengan rilis vsce yang dikunci di tools/vsce/ (rilis vsce itu memerlukan Node.js 22 atau lebih baru): jalankan npm ci --prefix tools/vsce --ignore-scripts, lalu cd vscode-extension && ../tools/vsce/node_modules/.bin/vsce package --no-dependencies --out apothem.vsix. Salinan yang dipasang dari apothem.vsix versi sebelumnya membawa pengenal ahmed-g-gad.apothem; hapus salinan tersebut (code --uninstall-extension ahmed-g-gad.apothem) agar kedua salinan tidak sama-sama mendaftarkan perintah yang sama. Satu ekstensi mencakup editor-editor dalam keluarga VS Code. Perintah paletnya (Apothem: Install, Verify, Update, Uninstall, Doctor) menjalankan mesin yang sama melalui runner yang dikonfigurasi (npx @ahmed-g-gad/apothem@<extension version> secara default, sehingga ekstensi menjalankan versi mesin yang dikirim bersamanya; arahkan pengaturan pengguna apothem.runner ke checkout lokal untuk menjalankan dari sumber). Install, Verify, Update, dan Uninstall menanyakan harness mana yang akan ditangani, dengan menawarkan harness milik editor itu sendiri terlebih dahulu; all adalah salah satu pilihan, tidak pernah menjadi default. Pengaturan apothem.runner berlingkup komputer (machine-scoped), sehingga workspace tidak dapat mengubahnya, dan ekstensi hanya berjalan di workspace tepercaya.

Verifikasi: jalankan perintah Apothem: Verify dari palet perintah editor, atau dari terminal:

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

5. Bootstrap baris perintah (host ekstensi)Copy Anchor Link

Prasyarat: alat baris perintah host-nya, Node.js 18+, dan Python sistem 3.10+ pada PATH.

Pasang Apothem sebagai ekstensi langsung dari repositori — perintahnya memuat slug host dan harness yang persis:

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

Ekstensi ini adalah bootstrap, bukan instalasi penuh dengan sendirinya: ekstensi ini memuat berkas konteks Apothem dan menambahkan perintah /apothem yang memanggil mesin melalui shell (npx @ahmed-g-gad/apothem). Materialisasikan harness lengkap dengan menjalankan instalasi melaluinya:

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

Verifikasi:

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

6. Bootstrap baris perintah (host qwen-code)Copy Anchor Link

Prasyarat: alat baris perintah host-nya, Node.js 18+, dan Python sistem 3.10+ pada PATH.

Pasang Apothem sebagai ekstensi --harness qwen-code langsung dari repositori:

qwen extensions install ahmed-g-gad/apothem

Seperti ekstensi kanal 5, ini adalah bootstrap: ekstensi ini memuat berkas konteks Apothem dan memanggil mesin melalui shell. Materialisasikan harness lengkap dengan menjalankan instalasi melaluinya:

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

Verifikasi:

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

7. Bootstrap baris perintah (host plugin)Copy Anchor Link

Prasyarat: alat baris perintah host-nya, Node.js 18+, dan Python sistem 3.10+ pada PATH.

Tambahkan repositori sebagai marketplace plugin, lalu pasang plugin-nya — perintahnya memuat slug host dan harness yang persis:

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

Kedua path --sparse hanya mengambil daftar marketplace dan plugin, bukan seluruh repositori; clone penuh dapat melampaui batas clone 30 detik milik host pada disk yang lambat, seperti drive Windows di bawah WSL.

Seperti ekstensi kanal 5 dan kanal 6, ini adalah bootstrap yang memanggil mesin melalui shell. Plugin ini membundel satu skill entri; manifesnya adalah plugin.json di root, dan halaman harness host plugin menjelaskan tata letaknya serta apa yang diserahkan plugin kepada mesin. Materialisasikan harness lengkap dengan menjalankan instalasi melaluinya:

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

Verifikasi:

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

8. Mesin langsung (python -m apothem)Copy Anchor Link

Prasyarat: Python sistem 3.10+ dengan paket click dan rich yang dapat diimpor, ditambah checkout repositori. Node.js tidak diperlukan.

Jalankan mesin langsung dari klon. Entry point menaruh dependensi yang di-vendor (src/apothem/_vendor) di sys.path, sehingga dengan click dan rich yang dapat diimpor, PYTHONPATH=src adalah seluruh penyiapannya:

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

Seperti pada shim npm, install pertama pada komputer tanpa profil membuat profil awal di ~/.config/apothem/profile.yaml lalu melanjutkan.

Verifikasi:

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

Verifikasi instalasi apa punCopy Anchor Link

Setiap kanal di atas menyebutkan perintah verifikasinya sendiri. Dua bentuk umumnya adalah:

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

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

Ganti nama harness dengan adapter mana pun yang Anda pasang; lihat daftar harness untuk semua nama yang didukung. Untuk memeriksa setiap adapter yang terpasang sekaligus (verifikasinya dan perintah hook-nya), jalankan doctor sebagai pengganti verify --harness NAME, dalam bentuk mana pun yang Anda gunakan di atas: apothem doctor, PYTHONPATH="$HOME/.apothem/src" python -m apothem doctor, atau npx @ahmed-g-gad/apothem doctor. Untuk jalur plugin, jalankan /plugin di dalam Claude Code dan konfirmasikan bahwa apothem tercantum sebagai terpasang.

Prasyarat sekilasCopy Anchor Link

• Python 3.10 atau lebih baru — jalur yang menemukannya melakukannya berdasarkan nama, dan namanya berbeda per jalur. Shim npm mencoba python3, python, lalu py -3. Pemasang mencoba python3, python, dan nama berversi python3.14 turun hingga python3.10.
• click dan rich dapat diimpor di bawah interpreter itu — dua dependensi yang berhadapan dengan terminal yang tidak di-vendor oleh mesin. Pemasang memeriksa keduanya, menyebutkan apa pun yang hilang, dan menawarkan untuk memasangnya untuk Anda — dengan konfirmasi Anda, atau secara otomatis dengan --yes (-Yes di PowerShell) atau APOTHEM_AUTO_INSTALL_DEPS=1. Di setiap kanal lainnya, paket yang hilang menghentikan mesin dengan galat (kode keluar 1) yang menyebutkan perintah persis untuk interpreter yang ditemukannya, dengan batasan versi yang diuji oleh Apothem (<interpreter> -m pip install "click==…" "rich>=…"); dengan --json, galat yang sama tiba sebagai amplop JSON dengan kode runtime.dependency_missing.
• Node.js 18 atau lebih baru — hanya jalur yang menjalankan npx: shim npm (2), ekstensi keluarga VS Code (4), dan bootstrap baris perintah (5–7).
• Runtime yang telah mencapai akhir masa pakai. Python 3.10 mencapai akhir masa pakai di upstream pada 2026-10-01, dan Node.js 18 dan 20 pada 2025-04-30 dan 2026-04-30. Apothem masih mendukung ketiganya sebagai batas bawah yang dideklarasikannya dan menguji masing-masing di CI, tetapi ketiganya tidak lagi menerima perbaikan keamanan dari upstream, jadi utamakan Python 3.11 atau lebih baru dan Node.js 22 atau lebih baru. Kebijakan batas bawah runtime menjelaskan cara batas bawah dinaikkan.
• Git — hanya jalur pemasang, dan hanya untuk bentuk jaringan (skrip mengkloning sumber; checkout lokal tidak memerlukan kloning).
• Claude Code — hanya jalur plugin. VS Code dan alat host milik setiap bootstrap baris perintah hanya dibutuhkan untuk kanalnya masing-masing (4–7).

Panduan berikutnyaCopy Anchor Link