Skip to content

Authoring a harness adapter

This guide walks through creating a apothem harness adapter from scratch, using the HarnessAdapter protocol.

Prerequisites

Step 1: Create the adapter package

mkdir apothem-myadapter
cd apothem-myadapter

# pyproject.toml
[project]
name = "apothem-myadapter"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["apothem>=0.1.0"]

[project.entry-points."apothem.harnesses"]
my-harness = "apothem_myadapter.adapter:MyHarnessAdapter"

Step 2: Implement the adapter

# src/apothem_myadapter/adapter.py
from pathlib import Path
from apothem.harnesses.base import HarnessAdapter

class MyHarnessAdapter(HarnessAdapter):
    name = "my-harness"
    display_name = "My Harness"

    def install(self, profile: Path, scope: str = "user") -> None:
        claude_md = (profile / "CLAUDE.md").read_text()
        # Translate CLAUDE.md to native format
        native_config = self._translate(claude_md)
        dest = self._resolve_dest(scope)
        dest.write_text(native_config)

    def verify(self, profile: Path) -> list[str]:
        dest = self._resolve_dest("user")
        if not dest.exists():
            return [f"Native config not found at {dest}"]
        return []

    def uninstall(self, scope: str = "user") -> None:
        self._resolve_dest(scope).unlink(missing_ok=True)

    def _translate(self, claude_md: str) -> str:
        # Implement translation logic here
        return claude_md  # passthrough for illustration

    def _resolve_dest(self, scope: str) -> Path:
        if scope == "user":
            return Path.home() / ".myharness" / "config.md"
        return Path.cwd() / ".myharness" / "config.md"

Step 3: Install and test

pip install -e .
apothem install --harness my-harness
apothem verify --harness my-harness

Step 4: Add to pyproject.toml docs

Document the harness in docs/harnesses/my-harness.md following the harness page template.

Step 5: Submit for inclusion

Open a pull request at the apothem repository with: - The adapter package (or a link to it) - The docs page - A verification test at tests/packaging/test_myadapter_install.py