apothem

One shared profile · materialized into eleven AI-coding-tool harnesses.

Install  ·  Quick tour  ·  How it works  ·  Harnesses  ·  Documentation  ·  Changelog  ·  Contributing

---

apothem ships one portable profile — behavioral rules, slash-command pipelines, persistent agents, hooks, and skills — and materializes it uniformly into every AI coding tool's native configuration directory through per-harness adapters. One source of truth. Eleven destinations. Zero hand-maintained drift.

Install

Pick the package manager that matches your operating system. Every channel delivers the same apothem CLI.

Platform / channel	Command
Python (any OS)	pipx install apothem  ·  uvx apothem
npm / Node (any OS)	npm install -g apothem  ·  npx apothem
macOS / Linux	brew tap Gad360/apothem https://github.com/Gad360/apothem.git && brew install Gad360/apothem/apothem
Windows (WinGet)	winget install Gad360.Apothem
Windows (Scoop)	scoop bucket add apothem https://github.com/Gad360/apothem.git && scoop install apothem/apothem
Arch Linux (AUR)	yay -S apothem  ·  paru -S apothem
Curl one-shot (POSIX)	curl -fsSL https://apothem.ahmedgad.com/install.sh | bash
PowerShell one-shot (Windows)	irm https://apothem.ahmedgad.com/install.ps1 | iex

Verify the install:

apothem --version
apothem --help

Detailed walkthroughs at apothem.ahmedgad.com/install/.

Quick tour

A 60-second demonstration: configure once, install across every harness on every machine.

# 1. Initialise your shared profile (one-time setup).
apothem profile init

# 2. Install the profile into a target harness.
apothem install --harness claude-code
apothem install --harness cursor
apothem install --harness gemini-cli
# ... or do all eleven in one command:
apothem install --harness all

# 3. Verify what each harness sees.
apothem verify --harness claude-code

# 4. Roll forward when the upstream profile evolves.
apothem update --harness all

# 5. Roll back cleanly.
apothem uninstall --harness cursor

Every command exits 0 on success, prints a structured JSON summary with --format json, and supports --dry-run for safe preview.

How it works

apothem decouples what you want every AI tool to do (your shared profile) from where each tool reads its configuration (eleven different filesystem destinations with eleven different schemas).

graph LR
    P["shared profile<br/>(rules, skills, agents, hooks)"]
    A["apothem<br/>core CLI"]
    P --> A
    A --> CC["~/.claude/<br/>Claude Code"]
    A --> CU["~/.cursor/<br/>Cursor"]
    A --> GE["~/.gemini/<br/>Gemini CLI"]
    A --> CO["~/.codex/<br/>Codex"]
    A --> WI["~/.windsurf/<br/>Windsurf"]
    A --> GC["~/.github/copilot/<br/>GitHub Copilot"]
    A --> OC["~/.opencode/<br/>OpenCode"]
    A --> AG["~/.antigravity/<br/>Antigravity"]
    A --> OW["~/.openclaw/<br/>Open-Claw"]
    A --> HE["~/.hermes/<br/>Hermes"]
    A --> QW["~/.qwen/<br/>Qwen Code"]

Loading

Each harness has its own per-harness adapter that:

• Maps profile elements (rules, skills, agents, hooks) onto the harness-native primitives.
• Translates between the shared schema and the harness's expected filesystem layout.
• Reverses cleanly on uninstall — no orphaned files, no manual cleanup.
• Verifies at install time, update time, and on demand.

Read the architecture overview for the deep walkthrough.

Supported harnesses

Harness	Adapter status	Materialization root
Claude Code	✅ Stable	~/.claude/
Cursor	✅ Stable	~/.cursor/
Gemini CLI	✅ Stable	~/.gemini/
GitHub Copilot	✅ Stable	~/.github/copilot/
Codex	✅ Stable	~/.codex/
Windsurf	✅ Stable	~/.windsurf/
OpenCode	✅ Stable	~/.opencode/
Antigravity	✅ Stable	~/.antigravity/
Open-Claw	✅ Stable	~/.openclaw/
Hermes	✅ Stable	~/.hermes/
Qwen Code	✅ Stable	~/.qwen/

Adapters live at src/apothem/adapters/. Authoring a new adapter? See the new-harness-adapter authoring runbook.

Updating

apothem update --self                  # bring the apothem CLI itself current
apothem update --harness all           # propagate profile changes to every harness
apothem update --harness cursor        # update one specific harness
apothem update --dry-run --harness all # preview what would change

Uninstalling

apothem uninstall --harness all        # remove apothem-managed surfaces from every harness

Operator-confirmed per-file destructive prompts protect any local edits you have made. Timestamped backups land at ~/.apothem/backups/YYYY-MM-DDTHHMMSSZ/ by default; --no-backup opts into permanent deletion.

To remove the CLI itself, use your package manager (pipx uninstall apothem, npm uninstall -g apothem, brew uninstall apothem, etc.).

Documentation

The full documentation site is at apothem.ahmedgad.com:

• Getting started — installation, harness setup, first profile.
• CLI reference — every subcommand, every flag.
• Architecture — adapter contract, profile schema, source layout.
• Concepts — AI-platform agnosticism, review-fortress, cognitive identity, seriousness tiers.
• Pipeline commands — /plan-spec, /plan-generate, /plan-review, /plan-execute, /plan-status, and the audit-fortress family.
• Runbooks — operational guides for adapter authoring, release engineering, security response.

Project status

Surface	State
CLI	Stable. Semver-compatible at v0.x; v1.0 cuts the public-API freeze.
Adapter ecosystem	Eleven harnesses live; new adapters welcomed via PR.
Documentation	Comprehensive; revised alongside every release.
Supply chain	OpenSSF Scorecard tracked; SLSA-3 provenance + Sigstore signatures on every release artifact; CycloneDX SBOM published.
Releases	GPG-signed tags; PEP-740 PyPI attestations; signed Homebrew formula + Scoop manifest + WinGet manifest.

Contributing

Contributions are welcomed. The short version:

1. Read CONTRIBUTING.md.
2. Open a discussion or issue describing your proposed change before sinking time into a PR.
3. Follow the codebase's ratified conventions — every change ships with tests, docs, a CHANGELOG entry, and passes CI in the same PR.
4. New harness adapters follow the adapter authoring runbook.

Reporting a security vulnerability? See SECURITY.md for the coordinated-disclosure protocol.

License

MIT © Ahmed G. Gad.

Third-party licenses are cataloged at LICENSES/ under the REUSE specification.

Acknowledgements

apothem stands on the AI-tool ecosystem's open foundation: every supported harness is an independent project authored and maintained by its respective creators. The adapter layer translates between schemas; the harnesses themselves are credit to their authors.