# ihme documentation

---

Source: https://lroolle.github.io/ihme-cli/README.md

# ihme

iCloud Hide My Email from the terminal. Make an address for a signup, find it later, turn it off when you are done with it.

```bash
ihme new github.com          # Apple offers a few addresses, you pick one
ihme list --search github    # find it by label, address, or note
ihme deactivate github.com   # stop the mail
ihme export -o backup.csv    # keep your own copy
```

You need iCloud+ and an Apple ID with two-factor authentication. Apple has no public API for this. ihme uses the same web API as icloud.com, and Apple can change it or block it. That is the deal.

[中文说明](https://lroolle.github.io/ihme-cli/README.zh.md)

## Install

macOS on Apple Silicon:

```bash
curl -fL https://github.com/lroolle/ihme-cli/releases/latest/download/ihme_macOS_arm64.tar.gz -o ihme.tar.gz
tar -xzf ihme.tar.gz ihme
sudo install -m 755 ihme /usr/local/bin/ihme
```

Builds for macOS Intel, Linux, and Windows, on arm64 and x86-64, are on the [releases page](https://github.com/lroolle/ihme-cli/releases/latest) with SHA-256 checksums. With Go: `go install github.com/lroolle/ihme-cli/cmd/ihme@latest`.

Then sign in:

```bash
ihme auth login    # Apple ID, password, 2FA code. The session is saved, the password and code are not.
ihme list
```

## Scripts

Every address command takes `--json`. `--jq` runs an installed jq on the result.

```bash
ihme new github.com --json                        # candidates only, reserves nothing
ihme new github.com --address <candidate> --json  # reserve one of them
ihme new github.com --yes --json                  # reserve the first one
ihme list --json --jq '.addresses[].hme'
```

Exit code 2 means sign in again. 1 is everything else.

## Agents

ihme is also a tool for agents. Three ways:

- `ihme agent "find my github address"` runs the built-in assistant on your own model key: Anthropic, DeepSeek, or any OpenAI-compatible endpoint.
- `ihme agent --via codex "find my github address"` uses a coding agent you are already signed in to. Also `claude` and `opencode`. No API key.
- `npx skills add lroolle/ihme-cli -g` gives an outside agent the [skill](https://lroolle.github.io/ihme-cli/skill/SKILL.md). `ihme mcp` is a stdio MCP server.

Anything that changes your account asks you first. The assistant keeps preferences in plain Markdown files. `ihme memory` shows them. An agent run sends the task and the results to the model you picked. Plain commands never talk to a model.

## Docs

- [Commands](https://lroolle.github.io/ihme-cli/docs/usage.md): search, create, edit, tags, export, JSON, errors
- [Agents](https://lroolle.github.io/ihme-cli/docs/agents.md): providers, consent, memory, MCP
- [Roadmap and release notes](https://lroolle.github.io/ihme-cli/ROADMAP.md)
- [Security](https://lroolle.github.io/ihme-cli/SECURITY.md): what is stored, and where
- [Contributing](https://lroolle.github.io/ihme-cli/CONTRIBUTING.md)

## Development

```bash
make check    # vet, test, build
make site     # build the website into _site/
```

Built with [Cobra](https://github.com/spf13/cobra) and [Charm](https://charm.sh/). [MIT](https://lroolle.github.io/ihme-cli/LICENSE). Not affiliated with Apple.

---

Source: https://lroolle.github.io/ihme-cli/README.zh.md

# ihme

在终端里管理 iCloud 隐藏邮件地址。为一次注册生成一个地址，之后按标签找到它，不想再收信了就停掉。

```bash
ihme new github.com          # Apple 给几个候选地址，你选一个
ihme list --search github    # 按标签、地址或备注查找
ihme deactivate github.com   # 停止转发
ihme export -o backup.csv    # 导出一份自己的备份
```

需要 iCloud+ 订阅和开启了双重认证的 Apple ID。Apple 没有公开这个 API，ihme 调用的是 icloud.com 网页版用的同一套接口，Apple 随时可以改动或封掉它。

[English README](https://lroolle.github.io/ihme-cli/README.md)

## 安装

macOS，Apple 芯片：

```bash
curl -fL https://github.com/lroolle/ihme-cli/releases/latest/download/ihme_macOS_arm64.tar.gz -o ihme.tar.gz
tar -xzf ihme.tar.gz ihme
sudo install -m 755 ihme /usr/local/bin/ihme
```

macOS Intel、Linux、Windows 的 arm64 和 x86-64 版本在 [releases 页面](https://github.com/lroolle/ihme-cli/releases/latest)，附 SHA-256 校验值。有 Go 的话：`go install github.com/lroolle/ihme-cli/cmd/ihme@latest`。

然后登录，查看自己的地址：

```bash
ihme auth login    # Apple ID、密码、双重认证码。会话会保存在本地，密码和验证码不保存。
ihme list
```

## 脚本

所有地址相关的命令都支持 `--json`。`--jq` 用本机安装的 jq 处理结果。

```bash
ihme new github.com --json                        # 只生成候选，不预留
ihme new github.com --address <candidate> --json  # 预留其中一个
ihme new github.com --yes --json                  # 预留第一个
ihme list --json --jq '.addresses[].hme'
```

退出码 2 表示需要重新登录，1 是其他错误。

## 给 agent 用

ihme 可以给 agent 用，三种方式：

- `ihme agent "find my github address"`：内置助手，用你自己的模型 key，支持 Anthropic、DeepSeek 和任何 OpenAI 兼容接口。
- `ihme agent --via codex "find my github address"`：用你已经登录的编程 agent，也可以是 `claude` 或 `opencode`，不需要 API key。
- `npx skills add lroolle/ihme-cli -g`：把 [skill](https://lroolle.github.io/ihme-cli/skill/SKILL.md) 装给外部 agent。`ihme mcp` 是一个 stdio MCP 服务。

任何会改动账户的操作都会先问你。助手把偏好记在纯 Markdown 文件里，`ihme memory` 可以查看。agent 模式会把任务和结果发给你选的模型，普通命令不经过任何模型。

## 文档

以下文档为英文。

- [命令说明](https://lroolle.github.io/ihme-cli/docs/usage.md)：查找、创建、编辑、标签、导出、JSON、错误
- [Agent 说明](https://lroolle.github.io/ihme-cli/docs/agents.md)：模型、确认、记忆、MCP
- [路线图与更新记录](https://lroolle.github.io/ihme-cli/ROADMAP.md)
- [安全说明](https://lroolle.github.io/ihme-cli/SECURITY.md)：本地存了什么，存在哪
- [参与贡献](https://lroolle.github.io/ihme-cli/CONTRIBUTING.md)

## 开发

```bash
make check    # vet、测试、构建
make site     # 把网站构建到 _site/
```

基于 [Cobra](https://github.com/spf13/cobra) 和 [Charm](https://charm.sh/)。[MIT](https://lroolle.github.io/ihme-cli/LICENSE) 协议。与 Apple 无关。

---

Source: https://lroolle.github.io/ihme-cli/docs/usage.md

# Command guide

Create, find, edit, and export iCloud Hide My Email addresses from the terminal.

[Install and sign in](https://lroolle.github.io/ihme-cli/README.md#install) before running these commands.

## Commands


```
AUTH
  ihme auth login                Sign in with Apple ID (SRP + 2FA)
  ihme auth status [--json]      Session state
  ihme auth logout               Clear session

LIST & SEARCH
  ihme list                      All addresses (table)
  ihme list --search <query>     Search label, address, or note
  ihme list --active             Only active
  ihme list --tag <tag>          Filter by tag
  ihme list --sort label         Sort by label or date

CREATE
  ihme new <label>               Interactive: pick from ~3 candidates
  ihme new <label> --yes         Script: take first
  ihme new <label> --json        Agent: get candidates without reserving
  ihme new <label> --agent       Embedded agent runs the full procedure

AGENT (built-in, BYOK)
  ihme agent                     Interactive session (inline TUI)
  ihme agent "<task>"            One-shot: "deactivate my old figma alias"
  ihme agent -p "<task>"         Same, via --prompt/-p (also: ihme -p "<task>")
  ihme agent --via claude "<task>"  Harness claude-code/codex/opencode as the
                                 provider (subscription auth, no API key)
  ihme agent --grant auto        Skip consent prompts for this run
  ihme memory                    Inspect the agent's memory graph
  ihme memory search <query>     Search journals and pages
  ihme memory graph              Show topic pages and backlinks

MANAGE
  ihme view <ref>                View details
  ihme edit <ref>                Edit label, note, tags
  ihme copy <ref>                Copy address to clipboard
  ihme deactivate <ref>          Stop receiving mail
  ihme reactivate <ref>          Resume receiving mail
  ihme delete <ref> [--yes]      Permanent deletion (confirms first)

EXPORT
  ihme export                    CSV to stdout
  ihme export --format json      JSON to stdout
  ihme export -o file.csv        To file
  ihme export --search dev       Filtered export

FORWARD
  ihme forward [--json]          Show forward-to address
  ihme forward set <email>       Change it
```

`<ref>` resolves by: anonymousId (full or 6+ char prefix) > email > label (exact) > label (fuzzy).

## JSON and jq

Use `--json` for structured address data; response shapes are documented in `ihme <cmd> --help`. `--jq` calls an installed `jq` executable. Combine it with `--json`. Commands such as `copy`, `version`, and interactive login print human output even when given the global `--json` flag.

```bash
ihme list --json --jq '.addresses[0:5]'
ihme list --search github --json --jq '.addresses[].hme'
ihme list --json --jq '.count'
ihme view github.com --json --jq '.result.hme'
ihme new mysite.com --json | jq '.candidates'
```


## Create without surprises

```bash
ihme new github.com --json                     # generate only
ihme new github.com --address <candidate> --json # reserve your choice
ihme new github.com --yes --json                # reserve the first candidate
```

Replace `<candidate>` with an address returned by the first command. A terminal session with `ihme new github.com` asks you to pick; without a terminal, that same command reserves the first candidate. Use `--json` alone when you only want candidates.

## Tags and notes

```bash
ihme new example.com --tag shopping --note "main account"
ihme list --tag shopping
ihme edit example.com --label Shopping --tag shopping,personal
```

Tags use the `#shopping | main account` note convention shared with the [Hide My Email browser extension](https://github.com/dedoussis/icloud-hide-my-email-browser-extension).

## Lifecycle

```bash
ihme deactivate example.com     # stop forwarding
ihme reactivate example.com     # resume forwarding
ihme delete example.com --yes   # permanently delete an inactive address
```

Deactivate an address before deleting it. Deactivation and reactivation take effect immediately; deletion asks for confirmation unless `--yes` is set.

## Authentication and errors

`ihme auth login` signs in interactively with Apple ID and two-factor authentication. `ihme auth status --json` checks the saved session against iCloud; add `--local` to inspect only the local file.

Exit codes: `0` success, `1` other error, `2` authentication required. A rejected session is refreshed once during an HME call; if Apple still refuses it, run `ihme auth login`. A temporary network or server failure asks you to retry instead.

Session location and stored data are documented in [Security](https://lroolle.github.io/ihme-cli/SECURITY.md). Apple controls rate limits and candidate availability; repeat generation can return the same pool. There is no guaranteed creation quota.

---

Source: https://lroolle.github.io/ihme-cli/docs/agents.md

# Using agents

Run Hide My Email tasks with the built-in assistant, a signed-in coding agent, or an external agent using the CLI.

[Install and sign in first](https://lroolle.github.io/ihme-cli/README.md#install). Direct CLI commands do not need a model or an API key.

## Use a signed-in coding agent

```bash
ihme agent --via codex "find my github address"
ihme agent --via claude "find my github address"
ihme agent --via opencode "which addresses go to netflix?"
```

The selected coding agent must already be installed and signed in. Node.js and `npx` are needed for the Codex and Claude ACP adapters; OpenCode speaks the [Agent Client Protocol](https://agentclientprotocol.com) directly. `--via` currently runs one task at a time. ihme supplies its tools over MCP and handles consent in your terminal.

## Use your own model key

Create `~/.config/ihme/.env` with your provider key and model. For example:

```dotenv
ANTHROPIC_API_KEY=your-key
ANTHROPIC_MODEL=claude-sonnet-4-6
```

DeepSeek uses `DEEPSEEK_API_KEY` and `DEEPSEEK_MODEL`. An OpenAI-compatible provider uses `OPENAI_API_KEY`, `OPENAI_BASE_URL`, and `OPENAI_MODEL`. Use a model available to your account; keep keys out of version control.

Then run:

```bash
ihme agent                              # interactive assistant
ihme -p "find my github address"        # one task, then exit
ihme new github.com --agent              # choose and reserve for this label
```

The run header shows the effective model and thinking effort. `--effort` sets the reasoning effort where the selected protocol supports it; unsupported chat-completions models show `n/a`.

Provider settings also live in `~/.config/ihme/agent.json`. The CLI detects Messages, Responses, or chat-completions APIs from the endpoint and model, retries supported protocol-mismatch failures, and records learned choices per model under `apis`. An explicit top-level `api` setting takes precedence. See the [release history](https://lroolle.github.io/ihme-cli/ROADMAP.md) for compatibility changes.

## Consent and address selection

| Entry point | What it grants |
| --- | --- |
| `ihme agent` or a one-shot task | Mutations ask for consent |
| `ihme new <label> --agent` | One reservation for that label; other mutations ask |
| `--grant auto` | Skip consent prompts for this run |

The consent card shows the proposed change. For a reservation, it includes the selected address, label, note, tags, the reason for the choice, and the rejected candidates. Allow once, deny, allow for the run, or type a reply to redirect the agent. The same gate applies when a coding agent supplies the model. Unattended mutations outside the granted scope are denied.

The [skill](https://lroolle.github.io/ihme-cli/skill/SKILL.md) defines the selection procedure: search for an existing alias, generate candidates, rank the pool, and reserve a choice. The rationale can be as simple as “cleanest of the three.” Recorded preferences guide the ranking; the current request takes precedence.

Candidate refresh is experimental. It reserves and deletes a throwaway address to try to change Apple's repeating pool, so it consumes real API capacity. It requires consent by default and is capped at two refreshes per task. A failed cleanup can leave an address behind. Apple controls whether the pool changes; this is not a bulk generation method.

## Preferences and memory

```bash
ihme memory prefer "Prefer short, easy-to-spell addresses"
ihme memory                             # inspect memory
ihme memory search github
ihme memory graph
ihme memory path                        # locate the files
```

The assistant keeps plain Markdown journals and topic pages. Reservations add history automatically. The `preferences` and `flashcards` pages load into each run; preferences also travel with generated candidate pools, including `ihme new --json`. Relocate memory with `IHME_MEMORY_PATH`, or open the directory in Logseq or Obsidian.

Memory operations report whether a page was created, updated, or reused. Failed writes are reported. Memory can contain account data; do not attach it to bug reports without redacting it.

## Give another agent the skill

```bash
npx skills add lroolle/ihme-cli -g
```

This installs instructions, not the binary. Install ihme and complete `ihme auth login` separately. The [skill](https://lroolle.github.io/ihme-cli/skill/SKILL.md) describes the procedure; [AGENTS.md](https://lroolle.github.io/ihme-cli/AGENTS.md) documents command and response shapes.

For a direct MCP client, launch `ihme mcp` as a stdio server after authenticating. It exposes HME tools and memory instructions. Mutations outside the granted scope require consent; unattended requests are denied.

## Data and implementation

Agent runs send the task and tool results to your selected model provider or coding agent. Results can include aliases, labels, notes, and memory. Direct CLI commands do not invoke an LLM. See [Security](https://lroolle.github.io/ihme-cli/SECURITY.md) for local storage and reporting.

The reusable agent kernel lives in [`pkg/agentkit`](https://lroolle.github.io/ihme-cli/pkg/agentkit/README.md). It provides the Go tool loop, streaming events, consent gates, and provider clients.

---

Source: https://lroolle.github.io/ihme-cli/skill/SKILL.md

---
name: ihme
description: Manage iCloud Hide My Email addresses — list, create, edit, deactivate, export
triggers:
  - hide my email
  - HME
  - icloud email
  - private relay
  - generate email
  - email alias
  - disposable email
tools:
  - ihme
---

# ihme — iCloud Hide My Email CLI

## Setup

Prefer the local checkout when available, so agents use the newest CLI changes:

```bash
# From the root of an ihme-cli checkout
make install
```

`make install` builds `ihme` and copies it to `$GOPATH/bin/ihme`, or to
`~/go/bin/ihme` when `$GOPATH` is unset. Make sure that directory is on `PATH`.

If the checkout is unavailable, install a release:

```bash
# macOS (Apple Silicon)
curl -sL https://github.com/lroolle/ihme-cli/releases/latest/download/ihme_macOS_arm64.tar.gz | tar xz && sudo mv ihme /usr/local/bin/

# macOS (Intel)
curl -sL https://github.com/lroolle/ihme-cli/releases/latest/download/ihme_macOS_x86_64.tar.gz | tar xz && sudo mv ihme /usr/local/bin/

# Linux
curl -sL https://github.com/lroolle/ihme-cli/releases/latest/download/ihme_linux_x86_64.tar.gz | tar xz && sudo mv ihme /usr/local/bin/

# Or via Go
go install github.com/lroolle/ihme-cli/cmd/ihme@latest
```

First run requires `ihme auth login` (interactive — Apple ID + 2FA).

Session lookup uses `IHME_SESSION_PATH` when set; otherwise it reads
`$XDG_CONFIG_HOME/ihme/session.json`, falling back to `~/.config/ihme/session.json`.

`ihme auth status --json` first reads the local session file, then checks whether
that session can currently access iCloud. It includes Apple's `/validate` payload
as `rawResponse`. Use `ihme auth status --local --json` only when you want the
local file/timestamp check without a network request.
`--verbose` only logs method, URL, status, and size.
Current `/validate` success responses are account-info payloads with `dsInfo`
and `webservices`; they may omit a `success` boolean.

## JSON response shapes

```
list --json     → {"addresses":[{anonymousId,label,hme,isActive,createTimestamp,note,...}],"count":N,"hints":{...}}
view --json     → {"result":{anonymousId,label,hme,forwardToEmail,isActive,...},"hints":{...}}
new --json      → {"candidates":["a@icloud.com",...],"label":"...","preferences":["..."],"hint":"ihme new <label> --address <addr>"}
                  (preferences: the user's standing preferences, present only when any are recorded)
new -y --json   → {anonymousId,label,hme,isActive,...}
forward --json  → {"forwardTo":"...","available":[...],"hint":"ihme forward set <email>"}
auth status     → {"loggedIn":true,"appleId":"...","expired":false,"canAccessICloud":true,"rawResponse":{...},...}
deactivate      → {"status":"deactivated","hme":"...","id":"...","hints":{...}}
reactivate      → {"status":"reactivated","hme":"...","id":"...","hint":"..."}
```

## Commands

```bash
# Auth check: local file + current iCloud access
ihme auth status --json

# Local auth file/timestamp only
ihme auth status --local --json

# List and search (hundreds of addresses supported)
ihme list --json --jq '.addresses[0:5]'
ihme list --search netflix --json
ihme list --active --tag dev --json
ihme list --sort label --json

# Create (two-step: generate candidates, then reserve)
ihme new github.com --json                              # step 1: get candidates
ihme new github.com --address abc@icloud.com --json     # step 2: reserve one
ihme new github.com --yes --json                        # one-shot: take first

# View and edit
ihme view github.com --json --jq '.result.hme'
ihme edit github.com --label GitHub --tag dev,work

# Lifecycle
ihme deactivate github.com --json
ihme reactivate github.com --json
ihme delete github.com --yes --json

# Export
ihme export --format json
ihme export --search github --active -o filtered.csv

# Forward-to
ihme forward --json
ihme forward set user@icloud.com
```

## <ref> resolution

All commands accepting `<ref>` resolve in order: anonymousId (prefix >= 6 chars) > email > label (exact) > label (fuzzy).

## Choosing an address

You'll see this address for years — in password managers, email threads, account
settings. It's a mask, but it's still yours. The core test:

**Does it make a picture, and is the picture one you'd keep?**

Two checks, in order:

1. **Can you see it?** Concrete nouns with physicality beat abstractions.
   `hilltop_desert` is a landscape. `pollen_pipe` is an object. `63.fryer.immune`
   is a serial number. Specific things are memorable; categories are forgettable.

2. **Would you keep it?** No deficit words (debts, gristle, paupers), no clinical
   tone (immune, generic, baseline), nothing that carries weight. An address is a
   micro-identity — it shouldn't feel assigned.

Calibration — the bar is keep-worthy, not poetic:

- Taste RANKS a pool; it rarely vetoes one. The expected outcome of every pool
  is "reserve the best," and with three candidates that is almost always round 1.
- A clean, pronounceable address with a normal email shape passes even when it
  makes no vivid picture. `sterner.turning5r` passes: two real words, one dot,
  reads like an address a person could have. Trailing suffix noise (`5r`, `0j`,
  `2k`) is Apple's fingerprint on nearly every candidate — never count it
  against one.
- A candidate FAILS only on an active defect: a deficit or clinical word,
  leading digits (`63.posher_pearly`), unpronounceable gibberish.
- A vivid image or contextual resonance PROMOTES a passing candidate; its
  absence disqualifies nothing. Resonance is discovered, not manufactured — a
  stretch (`turbine.dives` ~ "does energized deep-dives, like the service")
  reads as selling, and selling is bad taste.
- The rationale is one honest sentence in plain register. When the true reason
  is "the only candidate without a defect word," say exactly that; do not
  invent an image to fill the field or restate the verdict in fuller prose.
- If your verdict is "all candidates are weak," you are almost certainly
  misreading the bar — recheck each candidate against this list before even
  considering a refresh.

Bonus (elevates good to great, not a gate):

- **Contextual resonance**: does the address echo something about the service —
  a brand name, a logo shape, a developer handle? `oranges.lobby` for a service
  whose developer is `@oran_ge` and whose logo is an O isn't luck — it's fit.
  Most addresses won't have this. When it's there, it's decisive.

Secondary signals (tiebreakers, not filters):

- **Euphony**: read it aloud. Pleasant vowel/consonant rhythm and natural stress
  help recognition in a list of 300+.
- **No leading digits**: `65.ampere` reads like a form field. Letters first.
- **Separator style**: a distant tiebreaker by default. Never override a better
  image for a separator nobody asked for. `hilltop-desert` beats `relay_strop`
  regardless of format.

A recorded user preference changes the order above. The candidates payload
carries `preferences` (embedded: the `<preferences>` block and every
`generate_candidates` result; shell: the `preferences` field of `ihme new
--json`) — that is the user's standing direction, not a tiebreaker: rank the
candidates that pass the taste test by it, above image, euphony, and separator
defaults. "Dots between words" then beats a cleaner hyphenated candidate. A
preference never rescues a candidate with an active defect, and what the user
says in the current request outranks it.

The best HME addresses feel like they could be a place on a map, a cocktail name,
or an album title — evocative without trying.

## Error handling

Errors include the fix command:
```
Error: <ref> required — an address label, email, or ID
  Usage: ihme deactivate <ref>
  Example: ihme deactivate github.com
```

## Exit codes

- 0: success
- 1: error
- 2: not authenticated (run `ihme auth login`) — from ANY command, not
  just `auth status`

A session that expires mid-command heals itself (one silent re-auth,
then the call is replayed), so a lone 401 never surfaces. Exit 2 means
Apple kept refusing: only an interactive login fixes it.

## Operational guide (for agents)

### Creating an address

1. **Derive the label and search key.** For a URL, use the registrable domain
   without public suffix as the canonical label/search key: `https://atypica.ai/...`
   becomes `atypica`; `https://linear.app/...` becomes `linear`. Drop paths,
   query strings, callback URLs, referral parameters, dates, and campaign text.
   Keep the full URL only as context for the user or note.

2. **Check auth.** Confirm the stored session can access iCloud before generating
   candidates:
   ```bash
   ihme auth status --json
   ```
   If it exits 2 or returns `canAccessICloud:false`, the user must run
   `ihme auth login` interactively.

3. **Check first.** Search for existing addresses before creating:
   ```bash
   ihme list --search <search-key> --json
   ```
   `--search` matches label, address, and note by substring, so search the
   canonical key, then inspect returned labels for the intended service.
   Interpret matches by label, not by search key:
   - An active address with the SAME canonical label is a duplicate: ask
     before creating another (embedded interactive runs: `ask_user`). When
     you cannot ask, an explicit `new <label>` request has already decided
     creation — proceed, and flag the existing duplicate prominently in the
     summary.
   - Addresses for the same service under DIFFERENT labels (older accounts,
     dated labels, per-team variants) are context, never a blocker: mention
     them in the note or summary and continue.

4. **Generate and evaluate.** Get candidates and apply the taste test above:
   ```bash
   ihme new <label> --json
   ```
   When the payload carries `preferences`, rank the passing candidates by
   them first (see "Choosing an address").
   Evaluate each candidate individually — don't let bad neighbors taint a good
   one. A pool with two duds and one strong image is not a "weak pool."
   Reserve the best immediately — rotation and questions are for pools where
   every candidate actively fails, not pools that merely lack a vivid image
   (see Calibration above). When NO candidate passes
   after rotation: interactively (embedded: `ask_user`), offer your top two
   with a one-line reason each and let the user pick; non-interactively,
   reserve the least-bad and say plainly it was a compromise. Embedded runs
   must articulate the verdict: `reserve_address` requires `rationale` (one
   honest sentence on why it wins this pool — an image only if genuinely
   there) plus one `rejected` entry per candidate you passed on, each naming
   its failure — the user judges your pick against these on the consent card.

5. **Reserve with a useful note.** `ihme new` supports `--note`; Apple stores it
   in the address metadata, and `ihme list --search` searches it. Keep notes
   compact and durable: why the address exists, the full signup/origin URL when
   useful, account/workspace context, referrer/invite code, or owner/team. Do not
   put passwords, recovery codes, API keys, cookies, or other secrets in notes.
   ```bash
   ihme new <label> --address <candidate> --note "signup: https://example.com/auth/signup?via=team; workspace: acme" --json
   ```

6. **Refresh the pool only when every candidate actively fails.**
   Apple's generate returns a FIXED pending pool that repeats —
   calling generate again returns the SAME candidates until a slot is
   consumed, so re-generating never helps. But a refresh is NOT free
   either: it reserves and deletes a real address on Apple (mutations
   that count toward rate pressure — repeated churn risks the
   account) and typically swaps only ONE candidate in the pool. It is
   a last resort for a pool with zero keepers, never a reroll for a
   better image.
   - Embedded agent: `refresh_candidates` does the whole maneuver in
     one call (reserve + delete + regenerate). It requires a `reason`
     naming each candidate's active defect, asks the user for consent
     before burning anything, and is capped at 2 per task.
   - Shell: ask the user before rotating, then reserve any candidate,
     delete it, and generate again.
     ```bash
     ihme new <label> --address <throwaway> --json   # consume a slot
     ihme delete <throwaway-id> --yes --json          # clean it up
     ihme new <label> --json                          # fresh pool
     ```
   - If the refreshed pool still has no keeper, stop churning: take
     the least-bad and say plainly it was a compromise. Never ask the
     user to restart the session — you get a fresh budget next request.

7. **Show the result.** State what was reserved and one line on why it was
   picked. If a compromise was made (every candidate actively failed), say so.

### Labels

Use the service or team name as a bare noun. Dates age; names don't.
- Good: `github`, `linear`, `colaos`, `atypica`
- Avoid: `240501_chatgpt openai`, `0315 claude felix 2`, full signup URLs,
  referral/callback parameters

### Tags

Apply from a small controlled set when the user specifies context.
Common tags: `#work`, `#dev`, `#personal`, `#throwaway`, `#team-<name>`.

### Hygiene

`ihme list --sort date:asc` to surface old addresses for audit.
Suggest pruning dead services quarterly.

### Memory

You keep a memory across runs — a plain markdown graph (journals for
what you did, pages per topic, and two pages loaded into every run:
`preferences`, the user's standing direction, and `flashcards`, your
own pins). Use it for continuity:

- **Preferences load themselves.** The `preferences` page is injected
  into every run and repeated beside every candidate pool — you never
  have to recall it. When the user states a lasting preference about
  addresses or accounts ("dots over hyphens", "this is a work
  account"), record it there so the next run ranks by it. Shell:
  `ihme memory prefer <note>`. Embedded: `remember` with topic
  `preferences`.

- **Recall before creating.** Search memory for the service first;
  you may have reserved for it before, and the past note carries the
  account context. Shell: `ihme memory search <service>`. Embedded:
  `recall_memory`.
- **Reservations journal themselves.** Every reserve is written to
  memory automatically, linked to its service page. Never hand-record
  a reservation.
- **Remember durable learnings, sparingly.** When you learn a fact
  about a service worth carrying forward, save one note under the
  service name for on-demand recall. Pin a note of your own to the
  `flashcards` topic only when every future run needs it. Never
  store secrets. Shell: `ihme memory card <note>`. Embedded:
  `remember`.

## Execution adapters

The procedure and taste rules above are shared by two executors; only
the operation mapping differs.

**External agent** (Claude Code etc.): run the shell commands as
written above.

**Harnessed agent** (`ihme agent --via codex|claude|opencode`): you
are a full coding agent driven BY ihme; the operations arrive as MCP
tools from the server named `ihme` (possibly prefixed, e.g.
`mcp__ihme__reserve_address`). Use only those tools for HME work —
never the ihme shell CLI — and follow the Embedded agent column
below. Consent and caps are enforced inside the tools.

**Embedded agent** (`ihme new <label> --agent` for scoped creation,
`ihme agent` for the general interactive assistant): the same file is
embedded in the binary and invoked with the user's task. There is no
shell — operations map to in-process tools:

| Shell command | Embedded tool |
|---|---|
| `ihme auth status --json` | `auth_status` |
| `ihme list --search <key> --json` | `search_addresses` |
| `ihme new <label> --json` (candidates) | `generate_candidates` |
| reserve + delete a throwaway, then generate | `refresh_candidates` |
| `ihme new <label> --address <a> --note <n> --json` | `reserve_address` |
| `ihme deactivate <ref> --json` | `deactivate_address` |
| `ihme edit <ref> ...` | `edit_note` |
| `ihme memory search <query>` | `recall_memory` |
| `ihme memory prefer <note>` | `remember` (topic `preferences`) |
| `ihme memory card <note>` (or editing a page) | `remember` |

Embedded runs enforce the rotation cap (3 generation rounds) and
call budgets in code, and gate mutating actions outside the run's
granted scope behind user consent (`--grant ask`, the default) or
allow them unattended (`--grant auto`). Interactive embedded runs
also expose `ask_user` — one short question, answered on the
terminal, max 3 per run. Non-interactive runs must decide within
the task scope and record assumptions instead of stalling.

---

Source: https://lroolle.github.io/ihme-cli/ROADMAP.md

# Roadmap

Current: **v0.6.4** · [MIT](https://lroolle.github.io/ihme-cli/LICENSE)

## Shipped in v0.6.4 — preferences load themselves

- A preference recorded under `preferences` is loaded into every run
  and included with every candidate pool (`generate_candidates` and
  `ihme new --json` both carry a `preferences` field). It ranks the
  candidates that pass the taste test, above the rubric's
  tiebreakers. It never rescues a candidate with a defect. The
  current request outranks it.
- `remember` under `preferences` reports `alwaysLoaded: true`. The
  run banner shows `Preferences: N loaded`. `ihme memory prefer
  <note>` records one from the shell.
- `ihme mcp` returns the memory block as server `instructions`, so a
  direct MCP client gets it without a task turn.
- A learned wire protocol is stored per model under `"apis"`, never
  in the user's `"api"` pin, so one model's answer no longer locks
  the next. If an older ihme wrote `"api": "completions"` for you,
  delete it.
- Model guessing goes by generation: `gpt-5` and later, the
  `o`-series, `codex`, and `deepseek-v4` and later start on the
  responses API; `gpt-4o` and `gpt-4.1` stay on completions.
- 2FA accepts Apple's 409 with `securityCode.valid: true` and no
  fresh session token (rclone#9730). A wrong code never says valid.
- When both protocols are refused, one error says the model needs an
  API this endpoint does not serve.

## Shipped in v0.6.3 — the session heals itself, and errors say so

- **A 401 mid-command no longer reaches the user.** The mail-domain
  host keeps its own cookies, so it can refuse a session `/validate`
  just cleared — the pre-flight check cannot see that coming. HME
  calls now re-mint once through `accountLogin` (not `validate`,
  which already lied), rebuild the URL from the fresh webservices
  map and dsid, and replay the call; a rejected call changed nothing
  on Apple's side, so replaying is safe even for mutations. One shot
  only, and the fresh cookies land back on disk.
- **2FA survives Apple's 409.** Since ~mid-2026 the securitycode
  endpoints answer 409 to a *valid* code; the acceptance signal is
  the fresh `X-Apple-Session-Token`, not the status. `ihme auth
  login` used to die there (same break as rclone#9488).
- **Errors are a decision, not a dump.** One place renders them
  (`cmdutil.Explain`) and one maps exit codes (`cmdutil.ExitCode`):
  what happened, the cause, the command that fixes it — and exit 2
  for "authenticate" from every command, not just `auth status`.
  Account identifiers (dsid, clientId) are stripped from error text
  and `-v` logs, so a pasted error is safe.
- **Session writes are atomic** (write-then-rename) and `clientId`
  is generated once per installation instead of per invocation.
- **`refresh_candidates` rejoins the consent gate**, and taste stops
  demanding poetry. Net-zero described ACCOUNT state, never API
  pressure, and the per-task cap resets every turn — so a model with
  a miscalibrated bar burned throwaways task after task. The card now
  carries the model's per-candidate verdict; the prompt says taste
  RANKS a pool and rarely vetoes one; the rationale is one honest
  sentence, with an image only when there is one (TASTE.md,
  2026-08-12 and 2026-08-13).

## Shipped in v0.6.0 — harness a coding agent as the provider

- **`ihme agent --via codex|claude|opencode "<task>"`.** The
  provider relationship inverts: ihme is the harness (an [Agent
  Client Protocol](https://agentclientprotocol.com) client,
  `internal/acp` — a hand-rolled v1 subset in the agentkit spirit),
  the coding agent you are already signed in to is the brain. Its
  subscription auth, its models, no API key. The guest gets the HME
  operations back as MCP tools by re-invoking this binary
  (`ihme mcp`, hidden), so the rationale floor, rate caps, and
  memory journaling hold no matter who drives.
- **The consent card does not move to the guest.** Verified live:
  guest permission layers execute mutating MCP tools without asking
  (claude-agent-acp issued zero `session/request_permission` for a
  deactivate). So the scoped-consent gate runs inside the MCP
  server process, and its cards travel over a unix socket to the
  harness terminal — same card, same y/N/a-or-reply protocol; a
  typed reply rides the denial back to the guest as in-turn
  direction. Unattended runs deny mutations with an adaptable
  reason, exactly like the embedded agent.
- **deepseek-v4 as a first-class BYOK provider.** DeepSeek ships
  native /responses support in the v4 generation:
  `DEEPSEEK_API_KEY` + `DEEPSEEK_MODEL=deepseek-v4-flash` is now a
  complete configuration (base URL and key env default per vendor),
  auto-detection starts `deepseek-v4*` on the responses API
  (earlier generations stay on chat completions), and `--effort`
  passes through. Verified live against api.deepseek.com.
- One-shot tasks only for `--via` so far; the interactive REPL
  stays BYOK. Codex/claude adapters are fetched via `npx` on first
  use; opencode speaks ACP natively.

## Shipped in v0.5.0 — claude and codex as first-class providers

- **Native Anthropic Messages API** (`pkg/agentkit/ai/anthropic`):
  point the agent at a Claude model and `ANTHROPIC_API_KEY` +
  `ANTHROPIC_MODEL` is a complete configuration — the base URL
  defaults to Anthropic's endpoint. The shared `--effort` vocabulary
  applies generationally: `output_config` effort on Claude 4.6+
  (where manual budgets are a 400), a manual thinking budget on
  older models. Thinking blocks (signatures included) round-trip
  verbatim and stream live like responses-API reasoning summaries;
  a safety refusal surfaces as an error, never as a clean finish.
- **Auto-detection covers three protocols.** `claude*` models and
  anthropic.com endpoints start on the Messages API; a claude model
  behind an OpenAI-protocol gateway self-heals to chat completions
  on the first 404, and the discovery persists. Codex/gpt-5/o-series
  keep starting on the responses API — codex as a provider already
  worked; now it is documented.

## Shipped in v0.4.0 — agent polish

- **`--prompt`/`-p`.** Direct one-shot execution: `ihme agent -p
  "<task>"`, `ihme --agent -p "<task>"`, or just `ihme -p "<task>"` —
  no interactive prompt first. Positional task words still work;
  giving both is refused, not guessed at.
- **Memory operations are visible.** Reservation-time journaling,
  `remember`, and `recall_memory` each print what actually happened:
  `Memory created/updated for "x"`, `Reused memory for "x"`, and a
  failed write says so instead of staying silent.
- **The run states its configuration.** Every agent run opens with
  `Model:` and `Thinking effort:` as effectively resolved (config
  file, env, flags); effort on chat-completions models is reported as
  not applicable, never echoed as if applied.

## Shipped in v0.3.0 — the agent gets memory and judgment

- **Consent is a conversation.** The consent card carries the
  agent's taste verdict and the candidates it rejected; you can type
  a reply to redirect it, not just allow/deny.
- **Agent memory.** A Logseq-style markdown graph (`ihme memory`)
  the agent keeps across runs — reservations journal themselves,
  topic pages accumulate a service's history, a `flashcards` page
  loads into every run. Plain files, no database.
- **Candidate refresh** *(experimental)*. When a pool is weak and
  Apple keeps returning the same options, the agent burns a
  throwaway (reserve → deactivate → delete) to force a fresh pool.
  Bounded, net-zero on the common path, pending real-world
  validation of Apple's pending-pool behavior.
- **Harness fix.** Per-task rate budgets reset each interactive
  request, so a long session no longer permanently exhausts its
  generation budget.

## Shipped in v0.2.0 — the embedded agent

Not on the original roadmap; it emerged and took the release:

- `ihme new <label> --agent` and `ihme agent` — a built-in BYOK
  assistant over `pkg/agentkit`, a stdlib-only reusable agent kernel
- Scoped consent (a task pre-grants exactly its own scope), inline
  TUI with three-choice consent, live reasoning, loud taste rationale
- Wire-protocol auto-detection (chat completions vs responses API)
- From the session-resilience list, delivered early: session-resume
  failure classification (transient ≠ expired; no more surprise
  sign-in emails), one quiet retry on transport trouble, 15-min
  validation freshness window
- From the agent-native list, delivered differently: taste scoring
  became the agent's mandatory reserve rationale instead of a
  `--taste` flag
- Agent memory (`ihme memory`): a Logseq-style markdown graph the
  agent keeps across runs — reservations journal themselves, topic
  pages accumulate a service's history, a flashcards page loads into
  every run. Plain files, openable in Logseq/Obsidian, no database

## v0.3 — Fix what the review found

| Item | Why |
|------|-----|
| Silent 2FA push failure — log error, fall back to code prompt | Users wait forever when push silently fails |
| Note clearing — send empty field, don't omit it | `ihme edit foo --note ""` is a no-op today |
| `jq` presence check with install hint | "exec: jq: not found" is not actionable |
| CI lint — bump golangci-lint for go1.26 | CI red since v0.1.0, unrelated to code quality |
| `forward set` basic email validation | Server rejects garbage but with a worse message |
| Generate dupe warning when fewer candidates returned | Silent short-count surprises scripts |

## v0.4 — Session resilience (what v0.2.0 didn't cover)

| Item | Why |
|------|-----|
| Lock file for concurrent access | Parallel agent invocations corrupt session.json |

## v0.5 — Agent-native features

| Item | Why |
|------|-----|
| `ihme audit` — surface old addresses, inactive services, missing tags | 326 addresses, 1 deactivated. Hygiene at scale |
| `ihme bulk deactivate --tag throwaway --older-than 6m` | Batch lifecycle for agent-driven cleanup |
| Structured stderr (JSON errors when `--json` is set) | Agents can't parse human error messages reliably |
| Shell completions with dynamic ref completion | Tab-complete labels and IDs for humans |

## v0.6 — Distribution

| Item | Why |
|------|-----|
| Homebrew tap (`brew install lroolle/tap/ihme`) | Primary install path for macOS |
| AUR package | Linux distribution |
| README demo GIF (asciinema) | The README sells; the code ships |
| Issue templates (bug, feature) | Signal maturity, structure contributions |

## v1.0 — Production grade

| Item | Why |
|------|-----|
| `api/` test coverage 16.9% -> 60%+ via recorded HTTP fixtures | Auth flow is the hardest code and least tested |
| API change detection — weekly CI probe against Apple | Undocumented API = silent breakage |
| Keyring integration (macOS Keychain, GNOME Keyring) | Optional alternative to plaintext session JSON |
| Stable JSON output contract (versioned, no breaking changes) | Agents and scripts depend on response shapes |
| Man pages from Cobra | Unix convention |

## Strategic position

Only open-source CLI for iCloud Hide My Email that works end-to-end. pyicloud doesn't do HME. rclone does storage. Go-iClient is a library.

The moat is operational knowledge of Apple's undocumented auth protocol — SRP-6a with custom modifications, mandatory 2FA, trust tokens, CN routing. This breaks without warning and requires re-reverse-engineering.

Optimize for:
1. **Resilience** — sessions that survive, retries that work, change detection
2. **Agent ergonomics** — structured output, taste scoring, bulk ops
3. **Distribution** — people can't use what they can't install

---

Source: https://lroolle.github.io/ihme-cli/AGENTS.md

# AGENTS.md

> Coding agent instructions for [ihme-cli](https://github.com/lroolle/ihme-cli) — iCloud Hide My Email from the terminal.

## What this tool does

`ihme` manages iCloud Hide My Email addresses: create, list, search, edit, deactivate, reactivate, delete, export. It authenticates via Apple's SRP-6a protocol with 2FA support and persists session tokens locally.

## Prerequisites

Binary must be installed and authenticated before use:

```bash
# Install (macOS ARM)
curl -sL https://github.com/lroolle/ihme-cli/releases/latest/download/ihme_macOS_arm64.tar.gz | tar xz && sudo mv ihme /usr/local/bin/

# Install (macOS Intel)
curl -sL https://github.com/lroolle/ihme-cli/releases/latest/download/ihme_macOS_x86_64.tar.gz | tar xz && sudo mv ihme /usr/local/bin/

# Install (Linux x86_64)
curl -sL https://github.com/lroolle/ihme-cli/releases/latest/download/ihme_linux_x86_64.tar.gz | tar xz && sudo mv ihme /usr/local/bin/

# Install (Go)
go install github.com/lroolle/ihme-cli/cmd/ihme@latest
```

Authentication is interactive (requires human input for Apple ID + 2FA):

```bash
ihme auth login
```

Check session before running commands:

```bash
ihme auth status --json
# {"loggedIn":true,"appleId":"...","expired":false,...}
```

If exit code is 2, the user must run `ihme auth login` interactively.

## Commands

Address commands support `--json` for structured output and `--jq <expr>` for filtering (requires an installed `jq`; combine it with `--json`). `copy`, `version`, and interactive login print human output even with the global `--json` flag.

### List and search

```bash
ihme list --json                          # all addresses
ihme list --search netflix --json         # search label, address, or note
ihme list --active --json                 # only active
ihme list --inactive --json               # only inactive
ihme list --tag dev --json                # filter by tag
ihme list --sort label --json             # sort by: label, date, label:desc, date:asc
ihme list --json --jq '.addresses[0:5]'   # first 5
ihme list --json --jq '.count'            # total count
```

### Create (two-step flow)

```bash
# Step 1: generate candidates (does NOT reserve)
ihme new github.com --json
# {"candidates":["a@icloud.com","b@icloud.com","c@icloud.com"],"hint":"ihme new github.com --address <address> --json","label":"github.com"}

# Step 2: reserve a specific candidate
ihme new github.com --address a@icloud.com --json
# {anonymousId, label, hme, isActive, ...}

# One-shot (take first candidate, no choice)
ihme new github.com --yes --json

# With tags and note
ihme new github.com --tag dev --note "main account" --json
```

### View, edit, copy

```bash
ihme view github.com --json
ihme edit github.com --label GitHub --tag dev,work --json
ihme copy github.com                      # clipboard; prints address if unavailable
```

### Lifecycle

```bash
ihme deactivate github.com --json         # stop receiving mail
ihme reactivate github.com --json         # resume receiving mail
ihme delete github.com --yes --json       # permanent deletion
```

### Export

```bash
ihme export --format json                 # JSON to stdout
ihme export -o backup.csv                 # CSV to file
ihme export --search dev --active         # filtered export
```

### Forward-to address

```bash
ihme forward --json                       # show current forward-to
ihme forward set user@icloud.com          # change it
```

## Reference resolution

The `<ref>` argument resolves in this order:

1. Exact anonymousId match
2. anonymousId prefix (>= 6 chars, unique match only)
3. Exact email match
4. Exact label match (case-insensitive)
5. Fuzzy label substring match (single match only)

Ambiguous matches return an error listing the candidates.

## JSON response shapes

```
list --json      {"addresses":[{anonymousId,label,hme,isActive,createTimestamp,note,...}],"count":N,"hints":{...}}
view --json      {"result":{anonymousId,label,hme,forwardToEmail,isActive,...},"hints":{...}}
new --json       {"candidates":["a@icloud.com",...],"label":"...","hint":"..."}
new -y --json    {anonymousId,label,hme,isActive,...}
forward --json   {"forwardTo":"...","available":[...],"hint":"..."}
deactivate       {"status":"deactivated","hme":"...","id":"...","hints":{...}}
reactivate       {"status":"reactivated","hme":"...","id":"...","hint":"..."}
```

JSON output includes `hints` with suggested follow-up commands.

## Error handling

Errors include actionable fix commands:

```
Error: <ref> required — an address label, email, or ID
  Usage: ihme deactivate <ref>
  Example: ihme deactivate github.com
```

Session errors keep that shape and separate Apple's verdict on the
session from Apple having a bad day — the `Fix:` line is the whole
difference:

```
Error: iCloud rejected this session — the saved login is no longer valid
  Cause: listing HME: HTTP 401 from https://p137-maildomainws.icloud.com/v2/hme/list
  Fix: ihme auth login

Error: iCloud is temporarily unreachable — your session is probably still valid
  Cause: validating session: HTTP 502 from https://setup.icloud.com/setup/ws/1/validate
  Fix: run the same command again in a moment
```

A session that expires mid-command is re-minted once and the call
replayed, so a one-off 401 never reaches you. Only a session Apple
keeps refusing exits 2. Error text carries no account identifiers
(dsid, clientId) — safe to paste into a bug report.

## Exit codes

- `0` — success
- `1` — error (check stderr)
- `2` — authentication required — from any command, not just
  `auth status`. Run `ihme auth login`.

## Conventions

- stdout is data, stderr is status — safe to pipe
- `--yes` skips all interactive confirmation prompts
- `--verbose` / `-v` logs HTTP requests to stderr
- Session stored at `~/.config/ihme/session.json` (respects `$XDG_CONFIG_HOME`)
- Override session path with `IHME_SESSION_PATH` env var

---

Source: https://lroolle.github.io/ihme-cli/pkg/agentkit/README.md

# agentkit

A minimal embeddable agent kernel: a provider-neutral loop,
streaming backends for the three wire protocols that matter
(chat completions, responses, Anthropic messages), typed tools, a
pre-execution gate, hard limits, and explicit skill invocation.
Stdlib-only. Designed to be audited in one sitting.

agentkit is not a framework. It holds no sessions, no memory, no
config, no renderer, no consent policy, and no domain logic — those
belong to the embedding application. The first consumer is
`ihme new <label> --agent`; `examples/toyagent` is the minimal one.

## Shape

```
pkg/agentkit              the kernel: loop, tools, gate, limits,
                          events, skill invocation, transcript types
pkg/agentkit/schema       fluent JSON-schema builder (map[string]any)
pkg/agentkit/ai/openai    two Streamers: Client (/chat/completions,
                          the OpenAI-compat lingua franca) and
                          ResponsesClient (/responses, required by
                          reasoning models for function tools)
pkg/agentkit/ai/anthropic one Streamer over the Messages API, with
                          extended thinking (blocks round-trip
                          through Message.Provider — opaque to the
                          kernel, owned by the emitting client)
```

Essential contracts:

```go
type Streamer interface {
    Stream(ctx context.Context, req Request,
           emit func(StreamEvent) error) (AssistantMessage, error)
}

type Tool interface {
    Name() string
    Description() string
    Schema() map[string]any
    Execute(context.Context, json.RawMessage) (json.RawMessage, error)
}

type Gate  func(context.Context, GateRequest) GateDecision
type Skill struct{ Name, Instructions string }

func Run(ctx context.Context, cfg RunConfig, transcript []Message) ([]Message, error)
```

Events are synchronous callbacks, not channels: natural
backpressure, renderer errors propagate (an emit error cancels the
run), no goroutine-leak obligations. Model-stream events arrive
wrapped inside agent lifecycle events (`ModelEvent`) — two
vocabularies, layered. Wrap the callback in a channel if you need
one.

## Embedding

```go
transcript, err := agentkit.Run(ctx, agentkit.RunConfig{
    Streamer: &openai.Client{BaseURL: url, APIKey: key, Model: model},
    System:   executorRules,            // stable rules, NOT the procedure
    Tools:    tools,                    // in-process functions
    Gate:     gate,                     // nil allows everything
    Limits:   agentkit.Limits{},        // zeros take defaults
    OnEvent:  render,                   // nil for silent runs
}, []agentkit.Message{skill.Invocation(task)})
```

A skill is an operational procedure invoked as a task turn — never
baked into the system prompt. The caller owns transcript
persistence: call Run again with more messages to continue.

## Loop invariants

These are the kernel's contract; each has a test.

1. Arguments are validated before gating — the gate never sees garbage.
2. Every tool call passes the gate; interactive consent lives in the
   gate implementation, not the kernel.
3. A denial becomes a tool-result error the model can adapt to.
4. An identical denied call repeated once terminates the run.
5. Tool calls from a length-truncated response are all failed, never
   executed.
6. Malformed argument text and parse diagnostics are preserved; a
   "{}" fallback is never executed.
7. Turns, actual model requests (including retries), and tool calls
   are enforced in code. There is no unlimited mode.
8. context.Context propagates through model calls, gates, and tools.
9. Only transient model failures before meaningful stream output are
   retried; tool executions never retry.
10. Renderer, configuration, consent policy, and domain logic stay
    outside the loop.

## Out of the kernel — by design

Sessions/persistence, compaction, subagents, memory, MCP, TUI,
skill discovery, OAuth, provider registries, reflection schemas,
parallel tool execution, cost accounting beyond request counting.
Each is an application concern; adding them here would trade away
the one property that makes the kernel reusable: you can read all
of it.

## Roadmap — from kernel to general agent, deliberately

The kernel grows one proven need at a time; each item below has a
trigger, not a date. Additions that precede their trigger are scope
creep by definition.

| Next | Trigger |
|---|---|
| structured final output (schema-forced result turn) | a CLI needs machine-readable outcomes richer than transcript + app state |
| transcript persistence helpers (save/load, caller-side) | a REPL needs resume across processes |
| steering (inject a user message mid-run) | an interactive surface wants course-correction without killing the run |
| parallel execution for read-only tools | measured latency pain, never before |
| eval harness (scripted tasks + judge) | tuning prompts/skills against regressions |

Already deliberate, not missing: synchronous callbacks over
channels, sequential tools, learned (not shipped) provider
metadata, consent as a consumer-owned gate, skills as invoked
procedures. The design rationale, review history, and the survey of
prior art (pi, agentcore, agent-sdk-golang) live outside this repo;
the package guard test (`TestImportDirection`) enforces that the
kernel never imports application packages or third-party modules.

---

Source: https://lroolle.github.io/ihme-cli/LICENSE

MIT License

Copyright (c) 2026 lroolle

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

Source: https://lroolle.github.io/ihme-cli/SECURITY.md

# Security

## Local storage

`ihme` stores session tokens, trust tokens, cookies, Apple account identifiers, and webservice URLs in its session file. These are credentials: anyone who obtains them may be able to act on the account.

- macOS / Linux: `~/.config/ihme/session.json` (respects `XDG_CONFIG_HOME`)
- Windows: `%AppData%\ihme\session.json`
- Override: `IHME_SESSION_PATH`

Session writes are atomic and request owner-only file permissions (`0600` on Unix). Protect the file with your operating system's account and filesystem permissions. Atomic writes do not serialize concurrent CLI processes.

The Apple ID password and 2FA codes are not saved. Authentication uses SRP-6a; the password itself is not transmitted. Trust tokens can allow later sign-ins without a new 2FA challenge; Apple controls their lifetime.

## Agent mode

Model keys may be stored in the local ihme configuration or environment. Agent memory contains aliases, labels, notes, preferences, and task history in plain Markdown files. Treat both as private.

Agent tasks and tool results go to your selected model provider or coding agent. Direct CLI commands do not use an LLM. `ihme auth logout` clears the saved Apple session, not model configuration or agent memory.

## Report a vulnerability

Use GitHub's [private vulnerability reporting](https://github.com/lroolle/ihme-cli/security/advisories/new). Include the affected version, impact, and steps to reproduce; omit real tokens and account data. Do not open a public issue with an exploit or credentials.

Security fixes target the latest release. Older versions are not separately maintained; there is no guaranteed response time.

## Service boundary

This is an unofficial client of Apple's undocumented iCloud web API. Apple can change or block access. This project cannot guarantee account availability, rate limits, or continued compatibility.

---

Source: https://lroolle.github.io/ihme-cli/CONTRIBUTING.md

# Contributing

Small fixes and reproducible bug reports are welcome. Open an issue before starting a larger feature so we can agree on the behavior.

## Report a bug

Include your OS, `ihme version`, the command, what you expected, and the redacted error. Do not attach session files, cookies, model keys, or account exports. For vulnerabilities, follow [Security](https://lroolle.github.io/ihme-cli/SECURITY.md).

## Change the code

Install the Go version in `go.mod`, then run:

```bash
make check
```

Use fixtures and local mock servers for tests. A test must not need someone's Apple account or a paid model request. Add a regression test when fixing behavior and state what you actually ran in the PR.

## Change the docs or website

The README is the entry point; `docs/usage.md` and `docs/agents.md` hold the detail. Keep examples consistent with `ihme <command> --help` and label invented demo data.

```bash
make site
python3 -m http.server 8000 --directory _site
```

`site/` contains the landing page. `scripts/build_site.py` copies an explicit set of public files into `_site/`, checks local links, and derives `llms-full.txt` from the root `llms.txt` map. Update that map when an entry point changes. Never put account data, screenshots from real sessions, or local machine paths into the site.

The Pages workflow checks pull requests and publishes changes on `main`. A deployment succeeds only after the public `build.json` identifies the deployed commit. Generated site output stays out of source control.