Quick start

This is the fast path from nothing to a verified harness configuration: install, author the shared profile, materialize one tool's native config, confirm it, and make your first edit. Every command is real and copy-paste runnable, and each step shows what a clean run prints. The install itself lands in under two minutes; editing the profile is the only part that takes as long as you want it to.

By the end you will have a working harness configuration generated from a profile you wrote — and you will know the one command that pushes a profile change back out to one tool or to all of them.

You will use Claude Code as the example harness — it is the installer's default. Swap the adapter name at any step to target a different tool; the harness list has every supported name.

1. Install ApothemCopy Anchor Link

Apothem ships as a self-contained runtime — the engine runs straight from its source tree with vendored dependencies. One command fetches the source, places the engine, and materializes your first harness. It verifies the signed release first, so import the maintainer signing key once before the first install and check that the fingerprint reads 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163:

curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import
gpg --fingerprint 70396FED9C634163

& "$env:ProgramFiles\Git\bin\bash.exe" -c 'curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import && gpg --fingerprint 70396FED9C634163'

Then run the installer:

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

irm https://apothem.ahmedgad.com/install.ps1 | iex

The installer requires a system Python 3.10+, plus git and gpg for the network form. It checks the prerequisites and places the engine under ~/.apothem. When click or rich is missing, it installs the package with your confirmation or on --yes (-Yes on PowerShell) or APOTHEM_AUTO_INSTALL_DEPS=1, and otherwise stops with the pip command to run (see Prerequisites at a glance). On completion it prints a next-steps banner; on POSIX, when the shim's directory is already on PATH, the banner looks like this:

Installation complete.

The 'apothem' command is on your PATH.

Recommended first step — the guided setup (profile -> preview -> install):

  apothem quickstart

The installation guide covers the other install paths — the Claude Code plugin (/plugin marketplace add ahmed-g-gad/apothem then /plugin install apothem@apothem); the VS Code-family and other tool-native extensions; and the on-demand npx form (npx @ahmed-g-gad/apothem <command>) — alongside the environment-variable options.

2. Create the shared profileCopy Anchor Link

apothem profile init writes the smallest schema-valid profile to ~/.config/apothem/profile.yaml. If a profile is already there, as when the installer in Step 1 copied the example, init stops with an error and leaves the file unchanged; pass --force to overwrite it, or keep the file and edit it as shown below. Pass --profile PATH when you keep a project or CI-specific profile elsewhere.

apothem profile init
apothem profile show --json

The scaffold uses fake placeholder identity data and is safe to edit before you install any harness output. show --json reads it back and reports the validated profile with every default filled in, starting with schema_version. The command prints it on one line; it is expanded here:

{
  "schema_version": 1,
  "identity": {
    "name": "Example User",
    "role": "senior software engineer",
    "email": "[email protected]",
    "github": "example-user"
  },
  "preferences": {
    "language": "python",
    "style": "concise"
  },
  "rules": [],
  "seriousness": "PERSONAL_USE",
  "enforcement": {
    "sprints": false,
    "agent_teams": false,
    "multitasking": false,
    "continuous_execution": false,
    "learning_loop": false
  },
  "mcp_servers": {},
  "agent_mcp_servers": {},
  "harnesses": {},
  "exclude_harnesses": [],
  "workspace": {
    "directory_name": ".apothem",
    "scope": "project-local"
  }
}

This is also where a malformed edit surfaces — if the YAML is invalid, show reports it here, before any harness config is written. Make the profile yours with apothem profile edit (opens it in your editor) or set a single key in place:

apothem profile set identity.name "Your Name"

3. Install harness adaptersCopy Anchor Link

Materialize the adapter for your primary harness. This reads your profile and writes that tool's native configuration:

apothem install --harness claude-code

✓ Installed claude-code -> /home/you/.claude/settings.json

Project-scope adapters write their rules file inside a project, so they need a --project PATH; seven of them also write skills and shared rules into folders in your home directory, and --project does not change where those go. Preview any install without writing files using --dry-run:

apothem install --harness cursor --project . --dry-run
apothem install --harness cursor --project .

Install the whole registry-backed set at once with --harness all. Because that selection writes both project-scope and user-scope files, the command prints the concrete targets grouped by location. In an interactive terminal it asks before writing outside the project root. A run with no terminal, a run given --yes, or a run with --format json writes without asking; --dry-run writes nothing. Run the full set with:

apothem install --harness all --project .

See the full harness list for every supported name, and the install reference for the complete option set.

4. VerifyCopy Anchor Link

Materializing is only half the job — verify confirms the harness's expected config files landed and are valid:

apothem verify --harness claude-code

✓ claude-code is verified at /home/you/.claude/settings.json

verify exits non-zero if a managed target is missing, a managed file is empty, or a JSON or YAML config does not parse. Add --profile PATH to also fail when an installed file differs from that profile, which makes verify a drift check; without it, a stale config still verifies. The non-zero exit lets verify serve as a gate in a setup script. For a whole-machine health check across every registered adapter, run:

apothem doctor

doctor checks every installed harness: it must verify, and each hook command its install registered must start. A harness you have not installed is listed but is not a failure, so doctor exits 0 when no check fails, even if only one harness is installed.

5. Your first runCopy Anchor Link

Open the harness you just configured — Claude Code, in this example — and start a session in any project. The profile you set up in Step 2 is now part of that tool's behavior. That is the working first run: one profile, shaping a real session.

When you change the profile later, re-apply it without re-installing:

apothem update --harness claude-code

Name another adapter to re-apply the profile to that tool (add --project PATH for a project-scope adapter), or pass --harness all --project . to re-apply it to every supported harness.

Next stepsCopy Anchor Link

• Add more harnesses — repeat Step 3 per tool.
• Write your first rule — the unit every harness inherits.
• Author a plan — drive a whole mission through the deterministic plan pipeline.
• CLI reference — every command, flag, and exit code.