Skip to content

ADR 0005: The claude-cli backend and its terms

  • Status: Accepted
  • Date: 2026-10-27 (proposed)
  • Accepted: 2026-10-28

Context

The LLM step (ADR 0001) needs a backend. Users with a Claude subscription may want Horae to use it. PLAN.md records that, for Hermes and OpenClaw, the Claude subscription has been "blocked since April 2026" (§1). PLAN's understanding, marked ⚠️ unverified, is that the official claude -p CLI remains available for personal headless use on your own plan (§3.4). This ADR records how Horae approaches it; it is not a legal assessment.

Decision

Horae calls LLMs through backend adapters behind model aliases, including a claude-cli backend that runs the user's own Claude Code, documented as personal use under the user's plan's terms, with anthropic and an API key as the documented default.

  1. Backends are adapters behind model aliases. A pipeline names a model alias (model: default), resolved in horae.yaml. Four backends are planned:
  2. claude-cli: runs the official claude -p --output-format json;
  3. anthropic (API key);
  4. openai-compatible (OpenRouter, Mistral, vLLM);
  5. ollama.
  6. claude-cli runs isolated: an empty, isolated config, an environment allowlist, built-in tools disabled and no user settings. The LLM step has no tools on any backend.
  7. Horae never handles OAuth itself. The claude-cli backend runs the user's own installed and logged-in Claude Code, or uses a CLAUDE_CODE_OAUTH_TOKEN the user created with claude setup-token.
  8. It is documented as "personal use under your plan's terms".
  9. The default backend in the published docs is anthropic with an API key. PLAN.md notes that Max plans include monthly API credits that can fund it (⚠️ unverified, §3.4).
  10. Re-check the policy before v0.1.

Every backend gets the same guarantees from the core: schema-validated output with one repair retry, a cache keyed on (skill version, model, normalized input), a budget per step and per day, and a usage ledger. A de-identification transform can pseudonymize declared fields before any cloud backend.

In the contracts, the backend is recorded per call in the run record (schemas/run-record/v1.json, llm[].backend, one of claude-cli, anthropic, openai-compatible, ollama) together with the concrete model the alias resolved to, skill_version, cached, attempt and usage. The pipeline contract (schemas/pipeline/v1.json) only ever names an alias.

Consequences

Positive

  • If PLAN.md's ⚠️ reading of the terms holds, users with a subscription can use it for personal instances without a separate API bill.
  • Pipelines do not depend on a provider; swapping a backend is a horae.yaml change.
  • Because claude-cli is one adapter, it can be dropped if the terms change, without touching pipelines (§10).

Negative

  • The backend depends on terms Horae does not control. The understanding in PLAN.md (personal headless use of claude -p on your own plan is allowed; third-party products are not allowed to offer claude.ai login) is unverified (⚠️) and may change. Horae makes no claim that a given use is compliant; users are responsible for their plan's terms.
  • Running a CLI as a subprocess is slower and less controllable than an API call, and its JSON output format and flags can change between Claude Code releases.
  • The isolation (env allowlist, tools disabled, no user settings) must be verified against each Claude Code version; a regression could expose user configuration or tools.

Open questions

Alternatives considered

  • Horae handles claude.ai login (OAuth) itself. Rejected: PLAN.md's understanding (⚠️ unverified, §3.4) is that Anthropic does not allow third-party products to offer claude.ai login.
  • No subscription backend, API keys only. Safest with respect to terms, but excludes a use PLAN.md wants to support for personal instances. API keys remain the documented default.
  • A local model only. A small home server cannot run a useful local model (§7); ollama stays available for machines that can.

References