Metadata-Version: 2.4
Name: apothem
Version: 0.1.9
Summary: Host-agnostic AI-harness configuration manager.
Author-email: "Ahmed G. Gad" <me@ahmedgad.com>
Maintainer-email: "Ahmed G. Gad" <me@ahmedgad.com>
License-Expression: MIT
Project-URL: Homepage, https://apothem.ahmedgad.com/
Project-URL: Documentation, https://apothem.ahmedgad.com/usage/
Project-URL: Reference, https://apothem.ahmedgad.com/reference/
Project-URL: Architecture, https://apothem.ahmedgad.com/architecture/
Project-URL: Repository, https://github.com/ahmed-g-gad/apothem
Project-URL: Issues, https://github.com/ahmed-g-gad/apothem/issues
Project-URL: Discussions, https://github.com/ahmed-g-gad/apothem/discussions
Project-URL: Changelog, https://github.com/ahmed-g-gad/apothem/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/ahmed-g-gad/apothem/security
Project-URL: Brand, https://apothem.ahmedgad.com/brand/
Keywords: llm,hooks,developer-tools,ecosystem,claude-code,agent,automation,ai,governance,orchestration,cursor,gemini-cli,github-copilot,apothem
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSES/MIT.txt
Requires-Dist: click>=8.4.1
Requires-Dist: rich>=15.0.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: jsonschema>=4.26.0
Provides-Extra: dev
Requires-Dist: ruff>=0.15.14; extra == "dev"
Requires-Dist: mypy>=2.1.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.12.20260518; extra == "dev"
Requires-Dist: types-jsonschema>=4.26.0.20260518; extra == "dev"
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
Requires-Dist: hypothesis>=6.152.9; extra == "dev"
Provides-Extra: security
Requires-Dist: bandit[toml]>=1.9.4; extra == "security"
Requires-Dist: pip-audit>=2.10.0; extra == "security"
Provides-Extra: release
Requires-Dist: build>=1.5.0; extra == "release"
Requires-Dist: twine>=6.2.0; extra == "release"
Dynamic: license-file

<!-- SPDX-License-Identifier: MIT -->

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ahmed-g-gad/apothem/main/assets/logo-dark.svg">
    <img src="https://raw.githubusercontent.com/ahmed-g-gad/apothem/main/assets/logo.svg" alt="Apothem" width="140" height="140">
  </picture>
</p>

<h1 align="center">apothem</h1>

<p align="center">
  <em>One shared profile · materialized into eleven coding-assistant harnesses.</em>
</p>

<p align="center">
  <a href="https://github.com/ahmed-g-gad/apothem/actions/workflows/ci.yml"><img alt="Build" src="https://github.com/ahmed-g-gad/apothem/actions/workflows/ci.yml/badge.svg?branch=main"></a>
  <a href="https://github.com/ahmed-g-gad/apothem/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/github/license/ahmed-g-gad/apothem?color=0F172A"></a>
  <a href="https://pypi.org/project/apothem/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/apothem?color=10B981&label=pypi"></a>
  <a href="https://github.com/ahmed-g-gad/apothem/actions/workflows/ci.yml"><img alt="Coverage" src="https://img.shields.io/badge/coverage-see%20CI-2563EB"></a>
  <a href="https://securityscorecards.dev/viewer/?uri=github.com/ahmed-g-gad/apothem"><img alt="OpenSSF Scorecard" src="https://api.securityscorecards.dev/projects/github.com/ahmed-g-gad/apothem/badge"></a>
  <a href="https://github.com/ahmed-g-gad/apothem/discussions"><img alt="Community discussions" src="https://img.shields.io/badge/discussions-GitHub-7C3AED"></a>
  <a href="https://apothem.ahmedgad.com/"><img alt="Documentation" src="https://img.shields.io/badge/docs-Astro%20Starlight-0F172A"></a>
  <a href="https://pypi.org/project/apothem/"><img alt="PyPI downloads" src="https://img.shields.io/pypi/dm/apothem?color=10B981&label=downloads"></a>
</p>

<p align="center">
  <a href="https://github.com/ahmed-g-gad/apothem#install">Install</a>
  &nbsp;·&nbsp;
  <a href="https://github.com/ahmed-g-gad/apothem#quick-start">Quick Start</a>
  &nbsp;·&nbsp;
  <a href="https://apothem.ahmedgad.com/">Documentation</a>
  &nbsp;·&nbsp;
  <a href="https://github.com/ahmed-g-gad/apothem#supported-harnesses">Harnesses</a>
  &nbsp;·&nbsp;
  <a href="https://github.com/ahmed-g-gad/apothem/blob/main/CHANGELOG.md">Changelog</a>
  &nbsp;·&nbsp;
  <a href="https://github.com/ahmed-g-gad/apothem/blob/main/CONTRIBUTING.md">Contributing</a>
  &nbsp;·&nbsp;
  <a href="https://apothem.ahmedgad.com/community/">Showcase</a>
</p>

---

<p align="center">
  <a href="https://apothem.ahmedgad.com/architecture/">
    <img alt="Apothem project preview with the A logo and product summary" src="https://raw.githubusercontent.com/ahmed-g-gad/apothem/main/assets/social-preview.svg" width="900">
  </a>
</p>

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

## Why apothem

Supported coding tools proliferate; each one parks its configuration in a different directory, reads a different schema, and accepts a different vocabulary for the same primitives. Operators who use more than one tool today maintain parallel copies of nearly-identical configuration by hand, with all the divergence, dead-link, and "fix-in-one-place-missed-in-ten" pathologies that implies.

apothem cuts the drift at the root:

- **One profile, eleven destinations.** Author your rules, skills, helpers, hooks, and slash-commands once. Push to every harness with one command.
- **Reversible installs.** Every install is undone by the matching uninstall — timestamped backups, zero orphans, zero manual cleanup.
- **Per-harness verification.** `apothem verify --harness <name>` answers "is the profile faithfully installed here?" with a structured JSON report.
- **Operator-respecting.** Installs and updates back up existing targets before replacement; uninstall prompts unless `--yes` is supplied.
- **Built for review.** The full pipeline — `/plan-spec → /plan-generate → /plan-review → /plan-design` when architecture changes, then `/plan-execute` — applies to every change to the profile itself.

## Features

<table>
<tr>
<td width="33%" valign="top">

### 🎯 One profile, eleven destinations
Author once. Install everywhere. Every harness gets the same rules, skills, helpers, hooks, and slash-commands — translated into its native schema.

</td>
<td width="33%" valign="top">

### ↩️ Reversible installs
Every install is matched by a clean uninstall. Replacements and stale-sweep removals create timestamped backups at `~/.apothem/backups/`. Zero orphans.

</td>
<td width="33%" valign="top">

### 🔍 Verifiable state
`apothem verify --harness <name>` reports drift between source profile and harness destination. Structured JSON with `--format json` for CI integration.

</td>
</tr>
<tr>
<td width="33%" valign="top">

### 🛡️ Operator-safe destructives
Install and update preserve existing targets in `~/.apothem/backups/` before replacement. Uninstall keeps the confirmation prompt, with `--yes` for batch acceptance.

</td>
<td width="33%" valign="top">

### 📦 Broad release coverage
PyPI · npm · GHCR OCI image · Homebrew · WinGet · Scoop · AUR · `.deb` · `.rpm` · signed source archives · one-shot POSIX and PowerShell installers.

</td>
<td width="33%" valign="top">

### 🔐 Supply-chain hardened
SLSA-3 build provenance · Sigstore signatures · CycloneDX SBOM · PEP 740 PyPI release proofs · OpenSSF Scorecard tracked.

</td>
</tr>
</table>

## Quick Start

Three commands create a schema-valid shared profile and preview or install the
registered harness set for the current project. The `--project` flag is required
when `all` includes project-scope adapters such as Cursor, Gemini CLI, GitHub
Copilot, and Windsurf.

```shell
pipx install apothem
apothem profile init
apothem install --harness all --project .
apothem verify --harness all --project .
```

Lifecycle commands exit 0 on success, print a structured JSON summary with
`--format json`, and support `--dry-run` where a write would otherwise occur.
Narrower scopes (`--harness claude-code`, `--harness cursor`, etc.) target a
single harness when you need it; project-scope harnesses still require
`--project PATH`.

## 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` &nbsp;·&nbsp; `uvx apothem` |
| **Node.js (macOS / Linux / Windows)** | `npm install -g @ahmed-g-gad/apothem` |
| **Container (GHCR)** | `docker run --rm ghcr.io/ahmed-g-gad/apothem:latest --version` |
| **macOS / Linux (Homebrew)** | `brew tap ahmed-g-gad/apothem https://github.com/ahmed-g-gad/apothem.git && brew install ahmed-g-gad/apothem/apothem` |
| **Windows (WinGet)** | `winget install AhmedGGad.Apothem` |
| **Windows (Scoop)** | `scoop bucket add apothem https://github.com/ahmed-g-gad/apothem.git && scoop install apothem/apothem` |
| **Arch Linux (AUR)** | `yay -S apothem` &nbsp;·&nbsp; `paru -S apothem` |
| **Debian / Ubuntu** | Download `apothem_<version>-1_all.deb` from the GitHub Release and run `sudo apt install ./apothem_<version>-1_all.deb` |
| **Fedora / RHEL family** | Download `apothem-<version>-1.noarch.rpm` from the GitHub Release and run `sudo dnf install ./apothem-<version>-1.noarch.rpm` |
| **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` |

> **Integrity.** The curl / PowerShell one-shot installers pin the resolved version and verify the downloaded wheel's SHA-256 against the digest PyPI publishes (the artifact the OIDC Trusted-Publisher chain produced) before installing it; a mismatch aborts with a clear message. Prefer not to pipe to a shell? Use the `pipx install apothem` channel above, or read the script first (`curl -fsSL https://apothem.ahmedgad.com/install.sh`) — each installer carries the manual verification recipe in its header comments.

Verify the install:

```shell
apothem --version
apothem --help
```

Detailed install walkthroughs live on the project website at [apothem.ahmedgad.com/install/](https://apothem.ahmedgad.com/install/).

## How it works

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

```mermaid
%% verified: 2026-05-19 %%
%% provenance: README.md §How it works — apothem's eleven-harness materialization fan-out %%
graph LR
    P["shared profile<br/>(rules, skills, agents, hooks)"]
    A["apothem<br/>core CLI"]
    P --> A
    A --> AG["~/.gemini/GEMINI.md + antigravity-cli plugin<br/>Antigravity"]
    A --> CC["~/.claude/<br/>Claude Code"]
    A --> CO["~/.codex + ~/.agents<br/>Codex"]
    A --> CU["project .cursor/rules<br/>Cursor"]
    A --> GE["project GEMINI.md + .gemini<br/>Gemini CLI"]
    A --> GC["project .github/copilot-instructions.md<br/>GitHub Copilot"]
    A --> HE["~/.hermes/<br/>Hermes"]
    A --> OW["~/.openclaw/<br/>Open-Claw"]
    A --> OC["~/.config/opencode/<br/>OpenCode"]
    A --> QW["~/.qwen/<br/>Qwen Code"]
    A --> WI["project .windsurf/rules<br/>Windsurf"]
```

Each harness has its own per-harness adapter that:

- **Maps** profile elements (rules, skills, helpers, hooks) onto harness-native primitives where they exist and Apothem-owned support paths where they do not.
- **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](https://apothem.ahmedgad.com/architecture/) for the deep walkthrough.

> **Asset palette.** apothem's mark places eleven peripheral nodes around a central hub — each node color-keyed to one coding-assistant harness, alphabetically clockwise from 12 o'clock. The full design rationale, including per-harness hex values and accessibility posture, is published at [Brand](https://apothem.ahmedgad.com/brand/).

## Supported harnesses

The eleven adapters and their materialization roots:

```text
Antigravity     -> ~/.gemini/GEMINI.md + ~/.gemini/antigravity-cli/plugins/apothem/
Claude Code     -> ~/.claude/ + ~/.claude/apothem/{templates,hooks}/
Codex           -> ~/.codex/ + ~/.agents/skills/ + ~/.config/apothem/{rules,templates}/
Cursor          -> <project>/.cursor/rules/
Gemini CLI      -> <project>/GEMINI.md + <project>/.gemini/
GitHub Copilot  -> <project>/.github/copilot-instructions.md
Hermes          -> ~/.hermes/
Open-Claw       -> ~/.openclaw/
OpenCode        -> ~/.config/opencode/
Qwen Code       -> ~/.qwen/
Windsurf        -> <project>/.windsurf/rules/
```

Adapters live at [`src/apothem/harnesses/`](https://github.com/ahmed-g-gad/apothem/tree/main/src/apothem/harnesses). Authoring a new adapter? See the [new-harness-adapter authoring runbook](https://apothem.ahmedgad.com/runbooks/new-harness-adapter-authoring/).

## Updating

```shell
python -m pip install --upgrade apothem # or the package manager you installed with
apothem update --harness all --project . --dry-run
apothem update --harness all --project .
apothem update --harness cursor --project .
```

`apothem update` re-materializes harness configuration from the current shared
profile. It is not a CLI self-updater, and the current command surface does not
include `update --self`, `update --check`, or `update --apply`.

| Platform | Scheduler integration |
|---|---|
| **macOS / Linux** | `cron`, `systemd-timer`, `launchd` — update scheduling guidance at [Updating](https://apothem.ahmedgad.com/install/updating/) |
| **Windows** | Task Scheduler — update scheduling guidance at [Updating](https://apothem.ahmedgad.com/install/updating/) |

Updates never silently discard operator edits: matching managed targets are
backed up before replacement, shared directories are merged child-by-child, and
unchanged generated content is left untouched.

## Uninstalling

```shell
apothem uninstall --harness all --project . --yes
```

The uninstall command prompts before removal unless `--yes` is supplied. Install and update backups land at `~/.apothem/backups/YYYYMMDDTHHMMSSZ/`.

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

## Website

The Apothem project website at [**apothem.ahmedgad.com**](https://apothem.ahmedgad.com/) is the canonical operator guide. It keeps installation choices, harness walkthroughs, CLI reference, architecture notes, pipeline documentation, brand assets, security posture, and release runbooks in the site instead of expanding the root README into a full documentation portal.

| Section | What you'll find |
|---|---|
| [Home](https://apothem.ahmedgad.com/) | Product summary, harness overview, feature pillars, and start links |
| [Get started](https://apothem.ahmedgad.com/install/) | Installation, quick start, harness setup, updating, uninstalling, concepts, troubleshooting, FAQ, glossary |
| [Documentation](https://apothem.ahmedgad.com/usage/) | Day-to-day workflows — writing rules, authoring plans, using helpers, hook development, running the conformity gate, worked examples |
| [Harnesses](https://apothem.ahmedgad.com/harnesses/) | Per-harness pages for all eleven supported adapters (see the Supported harnesses table above for the full list) |
| [CLI & reference](https://apothem.ahmedgad.com/reference/) | Every subcommand · per-artifact-class reference · frontmatter / artifact / settings schemas · registries · conventions |
| [Architecture](https://apothem.ahmedgad.com/architecture/) | Adapter contract, profile schema, source layout, installation workflow, helpers, concepts, positioning, directory tree |
| [Pipelines & audits](https://apothem.ahmedgad.com/pipeline/) | The architecture-aware `/plan-*` pipeline and the eleven-command audit fortress, plus the fifteen-bar conformity gate |
| [Project](https://apothem.ahmedgad.com/security/) | Security posture (Scorecard, webhooks, branch protection, binary-artifacts sweep), brand assets, operational runbooks, engineering policies |
| [Community](https://apothem.ahmedgad.com/community/) | Roadmap, discussions, code of conduct, contributing guide, changelog |

## Release posture

The current public release line is documented in
[`CHANGELOG.md`](https://github.com/ahmed-g-gad/apothem/blob/main/CHANGELOG.md);
the README stays focused on what the tool does, how to install it, and where to
find deeper documentation.

Release artifacts are tied to the signed release tag and include platform
archives, Python distributions, SHA-256 checksums, Sigstore signatures, SLSA
provenance, and a CycloneDX SBOM.

## Contributing

Contributions are welcomed. The short version:

1. Read [`CONTRIBUTING.md`](https://github.com/ahmed-g-gad/apothem/blob/main/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](https://apothem.ahmedgad.com/runbooks/new-harness-adapter-authoring/).

Reporting a security vulnerability? See [`SECURITY.md`](https://github.com/ahmed-g-gad/apothem/blob/main/SECURITY.md) for the coordinated-disclosure protocol.

## Community

| Channel | Purpose |
|---|---|
| [GitHub Discussions](https://github.com/ahmed-g-gad/apothem/discussions) | Open-ended questions, workflow patterns, proposal socialization |
| [GitHub Issues](https://github.com/ahmed-g-gad/apothem/issues) | Defects, concrete feature requests, anchored clarification questions |
| [Security](https://github.com/ahmed-g-gad/apothem/security) | Private Vulnerability Reporting (see [`SECURITY.md`](https://github.com/ahmed-g-gad/apothem/blob/main/SECURITY.md)) |
| [Project website](https://apothem.ahmedgad.com/) | Comprehensive nine-section facade — landing page, documentation, reference, harnesses, architecture, pipelines, project, community |

Full channel-routing guidance at [`SUPPORT.md`](https://github.com/ahmed-g-gad/apothem/blob/main/SUPPORT.md).

## License & Authors

[MIT](https://github.com/ahmed-g-gad/apothem/blob/main/LICENSE) © [Ahmed G. Gad](https://ahmedgad.com).

The canonical contributor list is at [`AUTHORS`](https://github.com/ahmed-g-gad/apothem/blob/main/AUTHORS). Third-party licenses are cataloged at [`LICENSES/`](https://github.com/ahmed-g-gad/apothem/tree/main/LICENSES) under the [REUSE](https://reuse.software/) specification.

apothem stands on the coding-assistant 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.
