Metadata-Version: 2.4
Name: apothem
Version: 1.1.0
Summary: Harness-agnostic configuration, hooks, rules, skills, and tooling — materialized into each AI tool's native config directory via per-harness adapters.
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/Gad360/apothem
Project-URL: Issues, https://github.com/Gad360/apothem/issues
Project-URL: Discussions, https://github.com/Gad360/apothem/discussions
Project-URL: Changelog, https://github.com/Gad360/apothem/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/Gad360/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.0
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: jsonschema>=4.21
Provides-Extra: dev
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.11.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.6.0; extra == "dev"
Requires-Dist: hypothesis>=6.100.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: mkdocs-mermaid2-plugin>=1.1.1; extra == "docs"
Requires-Dist: pymdown-extensions>=10.21.3; extra == "docs"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2.0; extra == "docs"
Requires-Dist: mkdocs-static-i18n>=1.3.0; extra == "docs"
Requires-Dist: mkdocs-minify-plugin>=0.8.0; python_version < "3.14" and extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.26.0; python_version < "3.14" and extra == "docs"
Requires-Dist: mike>=2.1.0; python_version < "3.14" and extra == "docs"
Requires-Dist: mkdocs-rss-plugin>=1.14.0; python_version < "3.14" and extra == "docs"
Requires-Dist: mkdocs-redirects>=1.2.0; python_version < "3.14" and extra == "docs"
Requires-Dist: mkdocs-glightbox>=0.4.0; python_version < "3.14" and extra == "docs"
Requires-Dist: mkdocs-macros-plugin>=1.0.0; python_version < "3.14" and extra == "docs"
Requires-Dist: mkdocs-include-markdown-plugin>=6.0.0; python_version < "3.14" and extra == "docs"
Provides-Extra: security
Requires-Dist: bandit[toml]>=1.7.0; extra == "security"
Requires-Dist: pip-audit>=2.7.0; extra == "security"
Provides-Extra: release
Requires-Dist: build>=1.2.0; extra == "release"
Requires-Dist: twine>=5.0.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/Gad360           #
#  Licensed under MIT; see LICENSE for terms ------  #
-->

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Gad360/apothem/main/assets/logo-dark.svg">
    <img src="https://raw.githubusercontent.com/Gad360/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://pypi.org/project/apothem/"><img alt="PyPI" src="https://img.shields.io/pypi/v/apothem?color=10B981&label=pypi"></a>
  <a href="https://www.npmjs.com/package/@gad360/apothem"><img alt="npm" src="https://img.shields.io/npm/v/@gad360/apothem?color=10B981&label=npm"></a>
  <a href="https://github.com/Gad360/apothem/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Gad360/apothem/actions/workflows/ci.yml/badge.svg?branch=main"></a>
  <a href="https://github.com/Gad360/apothem/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/github/license/Gad360/apothem?color=0F172A"></a>
  <a href="https://www.python.org/downloads/"><img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-0F172A"></a>
  <a href="https://apothem.ahmedgad.com/"><img alt="Website" src="https://img.shields.io/badge/website-apothem.ahmedgad.com-10B981"></a>
  <a href="https://github.com/Gad360/apothem/releases"><img alt="Release" src="https://img.shields.io/github/v/release/Gad360/apothem?color=10B981"></a>
  <a href="https://securityscorecards.dev/viewer/?uri=github.com/Gad360/apothem"><img alt="OpenSSF Scorecard" src="https://api.securityscorecards.dev/projects/github.com/Gad360/apothem/badge"></a>
</p>

<p align="center">
  <a href="#install">Install</a>
  &nbsp;·&nbsp;
  <a href="#quick-tour">Quick tour</a>
  &nbsp;·&nbsp;
  <a href="#features">Features</a>
  &nbsp;·&nbsp;
  <a href="#supported-harnesses">Harnesses</a>
  &nbsp;·&nbsp;
  <a href="https://apothem.ahmedgad.com/">Website</a>
  &nbsp;·&nbsp;
  <a href="CHANGELOG.md">Changelog</a>
  &nbsp;·&nbsp;
  <a href="CONTRIBUTING.md">Contributing</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.** Every destructive operation routes through a per-file confirmation; nothing is silently overwritten.
- **Built for review.** The full pipeline — `/plan-spec → /plan-generate → /plan-review → /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. Timestamped backups at `~/.apothem/backups/`. Zero orphans. `--no-backup` opts into permanent deletion.

</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-confirmed destructives
Every delete / rename / overwrite routes through a per-file confirmation prompt. No silent destruction. `--yes` opts into batch acceptance.

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

### 📦 Eight distribution channels
PyPI · npm · Homebrew · WinGet · Scoop · AUR · curl-piped POSIX · PowerShell-piped Windows. Pick whichever your team already uses.

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

Three commands take you from zero to a verified install across every harness on the host.

```shell
# 1. Initialize your shared profile (one-time setup).
apothem profile init

# 2. Install the profile into every supported harness.
apothem install --harness all

# 3. Verify what each harness sees.
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` |
| **npm / Node (any OS)** | `npm install -g apothem` &nbsp;·&nbsp; `npx apothem` |
| **macOS / Linux (Homebrew)** | `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` &nbsp;·&nbsp; `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` |

> **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 at [`docs/brand/asset-palette-rationale.md`](docs/brand/asset-palette-rationale.md).

## 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/`](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` — example unit at [`docs/runbooks/scheduled-update.md`](https://apothem.ahmedgad.com/runbooks/scheduled-update/) |
| **Windows** | Task Scheduler — example task XML at the same runbook |

Auto-update never silently overwrites operator edits — every destructive step still routes through the per-file confirmation surface unless `--yes` is set.

## Uninstalling

```shell
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.).

## Website

The Apothem project website at [**apothem.ahmedgad.com**](https://apothem.ahmedgad.com/) is a comprehensive nine-section facade, not a docs-only destination. The marketing landing page surfaces the install matrix, feature pillars, harness lineup, and a colour-keyed architecture diagram; nested sections cover end-user documentation, technical reference, per-harness pages, architecture deep-dives, the plan pipeline plus audit fortress, project surfaces (security · brand · runbooks · engineering), and community routing.

| Section | What you'll find |
|---|---|
| [Home](https://apothem.ahmedgad.com/) | Marketing landing — value proposition, install in one line, harness map, feature pillars, CTAs |
| [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 five-stage `/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 |

## 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. |
| Project website | Nine-section comprehensive facade at [apothem.ahmedgad.com](https://apothem.ahmedgad.com/); 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 release proofs; signed Homebrew formula + Scoop manifest + WinGet manifest. |

## Contributing

Contributions are welcomed. The short version:

1. Read [`CONTRIBUTING.md`](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`](SECURITY.md) for the coordinated-disclosure protocol.

## Community

| Channel | Purpose |
|---|---|
| [GitHub Discussions](https://github.com/Gad360/apothem/discussions) | Open-ended questions, workflow patterns, proposal socialization |
| [GitHub Issues](https://github.com/Gad360/apothem/issues) | Defects, concrete feature requests, anchored clarification questions |
| [Security](https://github.com/Gad360/apothem/security) | Private Vulnerability Reporting (see [`SECURITY.md`](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`](SUPPORT.md).

## License & Authors

[MIT](LICENSE) © [Ahmed G. Gad](https://ahmedgad.com).

The canonical contributor list is at [`AUTHORS`](AUTHORS). Third-party licenses are cataloged at [`LICENSES/`](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.
