claude-code - 💡(How to fix) Fix [DOCS] Subscription quota eligibility for child_process.spawn("claude", ...) from owner-only local backend is undocumented [2 comments, 2 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/headless,https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan

Section/Topic

Subscription billing eligibility for programmatic claude CLI invocation via child_process.spawn from a personal owner-only local backend

Current Documentation

The "Run Claude Code programmatically" page documents claude -p as the official programmatic CLI mode but does not specify whether spawning the CLI from a developer's own backend (Node.js child_process.spawn, etc.) is eligible for Pro/Max subscription quota or counts as a "third-party harness."

The "Using Claude Code with your Pro or Max plan" Help Center article describes how Pro/Max subscription connects to Claude Code in interactive use, but does not address automated invocation patterns from a user-owned local backend.

Public coverage of the April 4, 2026 third-party harness limitation (TechCrunch, Business Insider re: OpenClaw) addresses third-party tools but does not clarify the boundary for owner-only local self-host patterns.

What's Wrong or Missing?

There is no documentation that clarifies whether the following pattern is eligible for Pro/Max subscription quota:

A Pro/Max subscriber writes their own personal local-only backend (e.g., Next.js running on localhost) that invokes the official claude CLI as a child process to integrate Claude Code into a personal dashboard for their own use:

child_process.spawn("claude", [
  "-p", "<short prompt>",
  "--output-format", "stream-json"
])

Specifically, this configuration:

• No ANTHROPIC_API_KEY in shell or child env
• No ANTHROPIC_AUTH_TOKEN, no cloud provider env (Bedrock/Vertex/Foundry)
• No apiKeyHelper in any settings file
• Authenticated via claude login with Pro/Max credentials only
• --bare flag not used
• localhost binding only, no external exposure
• Owner-only, no third-party users, low frequency (manual invocation, not cron/parallel/always-on)

The documentation should clarify whether this is:

(A) Eligible for Pro/Max subscription quota — equivalent to running claude -p directly from terminal, just automated from the user's own backend. (B) Considered a "third-party harness" requiring API key / extra usage billing. (C) A gray area requiring case-by-case clarification.

Without this clarification, individual developers building personal local automation with Claude Code cannot confidently determine whether their setup will incur unexpected API charges or violate terms.

The April 4, 2026 third-party harness coverage created uncertainty about where the boundary lies between "official CLI automation by the same user" and "third-party harness." The current docs do not address this directly.

Related issue: #37686 illustrates the financial risk when this boundary is misunderstood (a Max subscriber incurred $1,800+ in unintended API charges with claude -p and an inherited ANTHROPIC_API_KEY).

Suggested Improvement

Add a section to "Run Claude Code programmatically" or "Using Claude Code with your Pro or Max plan" that explicitly addresses owner-only local automation patterns:

1. Define what counts as "official CLI use" vs "third-party harness" when the user themselves invokes the official claude binary from their own backend.
2. Specify whether child_process.spawn("claude", ...) from a user-written local-only backend is subscription-eligible.
3. Provide a recommended configuration (env, auth, settings) for personal local automation that stays within subscription limits.
4. Cross-reference the third-party harness limitation (April 4, 2026 policy change) and clarify how it does or does not apply to owner-only patterns.

This would help individual developers confidently integrate Claude Code into personal local automation without risking unintended API billing or terms violations.

Impact

High - Prevents users from using a feature

Additional Context

This question arises in the context of building a personal owner-only local dashboard that integrates Claude Code as one of multiple LLM-backed assistants. The dashboard runs entirely on localhost, has no third-party users, and is for the subscriber's own personal use.

Independent technical research conducted before opening this issue:

• The "Authentication" page (https://code.claude.com/docs/en/iam) describes the auth precedence (cloud provider env > ANTHROPIC_AUTH_TOKEN > ANTHROPIC_API_KEY > apiKeyHelper > CLAUDE_CODE_OAUTH_TOKEN > subscription OAuth credentials), which suggests subscription OAuth is reachable when no API-key-related env or settings are present.
• The "Environment variables" page (https://code.claude.com/docs/en/env-vars) explicitly states that ANTHROPIC_API_KEY in env will be used in non-interactive -p mode, resulting in API billing rather than subscription.
• These together imply that a clean env (no API key, no cloud provider env, no apiKeyHelper) should result in subscription routing, but this is inferred rather than stated.

What remains unclear is whether the act of spawning the official claude binary from a user-owned backend changes this routing or attribution, regardless of env cleanliness — i.e., whether Anthropic's internal client fingerprinting or third-party harness detection treats child_process.spawn invocation differently from direct terminal invocation.

Thank you for considering this clarification.