Metadata-Version: 2.4
Name: apothem
Version: 0.1.2
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: 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
#  Copyright (c) Ahmed G. Gad ----------------------  #
#      Website:   https://ahmedgad.com                #
#      Email:     mailto:me@ahmedgad.com              #
#      Github:    https://github.com/ahmed-g-gad      #
#  Licensed under MIT; see LICENSE for terms -------  #
-->

<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 · 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 take you from zero to a verified install across every harness on the host.

```shell
pipx install apothem
apothem profile init
apothem install --harness all && apothem verify --harness all
```

Every command exits 0 on success, prints a structured JSON summary with `--format json`, and supports `--dry-run` for safe preview. Narrower scopes (`--harness claude-code`, `--harness cursor`, …) target a single harness when you need it; updating and uninstalling live in their own sections below.

## 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` |
| **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["~/.antigravity/<br/>Antigravity"]
    A --> CC["~/.claude/<br/>Claude Code"]
    A --> CO["~/.codex/<br/>Codex"]
    A --> CU["~/.cursor/<br/>Cursor"]
    A --> GE["~/.gemini/<br/>Gemini CLI"]
    A --> GC["~/.github/copilot/<br/>GitHub Copilot"]
    A --> HE["~/.hermes/<br/>Hermes"]
    A --> OW["~/.openclaw/<br/>Open-Claw"]
    A --> OC["~/.opencode/<br/>OpenCode"]
    A --> QW["~/.qwen/<br/>Qwen Code"]
    A --> WI["~/.windsurf/<br/>Windsurf"]
```

Each harness has its own per-harness adapter that:

- **Maps** profile elements (rules, skills, helpers, 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](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 (status: all stable) and their materialization roots:

```text
Antigravity     -> ~/.antigravity/
Claude Code     -> ~/.claude/
Codex           -> ~/.codex/
Cursor          -> ~/.cursor/
Gemini CLI      -> ~/.gemini/
GitHub Copilot  -> ~/.github/copilot/
Hermes          -> ~/.hermes/
Open-Claw       -> ~/.openclaw/
OpenCode        -> ~/.opencode/
Qwen Code       -> ~/.qwen/
Windsurf        -> ~/.windsurf/
```

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
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
```

### Auto-update

For unattended hosts, schedule the update verb in read-only mode. The `--check` flag reports without mutating; add `--apply` only when you've ratified silent fast-forward.

```shell
# Check for upstream changes (read-only, exits 1 when updates pending).
apothem update --check

# Apply available updates non-interactively.
apothem update --apply --harness all
```

| 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/) |

Auto-update never silently discards operator edits — replacements are backed up before the managed surface is refreshed.

## Uninstalling

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

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.
