Headless Claude Code

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: instruction override, no behavioural pass.

that can't be pre-seeded is the **bypass-permissions safety warning** — CC always shows

assistant/CLAUDE.md

assistant/src/approvals/CLAUDE.md

assistant/src/notifications/CLAUDE.md

assistant/src/runtime/CLAUDE.md

gateway/CLAUDE.md

Audit 0.4.1 · source sha 19bc86343b63 · 14 Oct 2026Report an issue or request a re-scan

• Publishervellum-ai GitHub organizationOwner of the repository this skill is read from
• Source foldervellum-ai/vellum-assistant/skills/headless-claude-codeThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict19bc86343b63A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Reference guide for running Claude Code in third-party headless, container, and CI environments. Covers auth strategies, interactive mode pitfalls, tmux orchestration, root user workarounds, and git auth without SSH…

---
name: headless-claude-code
description: Reference guide for running Claude Code in third-party headless, container, and CI environments. Covers auth strategies, interactive mode pitfalls, tmux orchestration, root user workarounds, and git auth without SSH agents or keychains
compatibility: "Any environment running Claude Code headlessly"
metadata:
  emoji: "🖥️"
  vellum:
    category: "development"
    display-name: "Headless Claude Code"
    avoid-when:
      - "Setting up or authenticating Claude Code inside a Vellum assistant: the ACP skill owns that path"
---

# Headless Claude Code

Running Claude Code outside a desktop terminal — in Docker containers, CI runners, cloud
VMs, or orchestrated by another process — is full of undocumented friction. This guide
covers everything we've learned getting CC to work reliably in these environments.

---

## 1. Authentication

CC tries multiple auth strategies in a fixed priority order. Understanding this chain is
the key to headless auth.

### Priority Order (highest → lowest)

1. **Cloud provider ambient credentials** — AWS Bedrock, GCP Vertex (auto-detected)
2. **`ANTHROPIC_AUTH_TOKEN`** — raw bearer token for Anthropic's API
3. **`ANTHROPIC_API_KEY`** — direct API key (pay-per-token, no Pro subscription features)
4. **`apiKeyHelper`** — executable that prints a token to stdout (set via `--settings`)
5. **`CLAUDE_CODE_OAUTH_TOKEN`** — OAuth token (Pro/Team subscription)
6. **`/login`** — interactive browser OAuth dance (unusable in headless)

### Recommended: `apiKeyHelper`

The most flexible headless strategy. Point CC at a script that returns a valid token:

```json
{
  "apiKeyHelper": "/path/to/your-auth-script"
}
```

Pass it via `--settings /path/to/settings.json` on launch. CC calls this script whenever
it needs a token, so it handles rotation naturally.

**Example helper** (reads from a credential vault):

```bash
#!/bin/bash
# Prints the OAuth token to stdout. CC calls this on demand.
your-vault-cli get anthropic-oauth-token
```

The script MUST:

- Print exactly one token to stdout (no trailing newline issues — CC trims)
- Exit 0 on success
- Be executable (`chmod +x`)

### `setup-token` (One-Time OAuth Bootstrap)

If you have a browser _somewhere_ (your laptop, a jump host), you can bootstrap OAuth
credentials into a headless machine:

```bash
# On the headless machine:
claude setup-token
# Prints a URL and waits for a token

# Open that URL in any browser, complete the OAuth flow.
# The token is saved to ~/.claude/ and CC uses it going forward.
```

This is good for initial setup but tokens expire. For long-running environments,
`apiKeyHelper` with a refresh mechanism is more robust.

### `CLAUDE_CODE_OAUTH_TOKEN` env var

Set a Pro/Team subscription OAuth token directly:

```bash
export CLAUDE_CODE_OAUTH_TOKEN="oat-..."
claude
```

This is the simplest headless auth method and works in both `-p` mode and interactive
mode. The main limitation: no automatic refresh. When the token expires, CC dies.

**Caveat**: on first launch in interactive mode, CC may still show the login method
picker even with this env var set. Complete onboarding once (see Section 2) and
subsequent launches will use the token without prompting.

### What NOT to Use

- **`ANTHROPIC_API_KEY`** works but bills per-token (no Pro subscription). Fine for CI
  where you want predictable billing; bad for long interactive sessions.
- **`/login`** (the interactive browser flow) requires a real browser. In containers,
  this hangs or errors. The whole point of this guide is avoiding it.

---

## 2. First-Run Onboarding & Interactive Prompts

CC has several interactive prompts that block on first launch. In headless environments
where no human is watching, these are silent killers.

### The Onboarding Gauntlet

On first launch, CC may prompt for:

1. **Theme selection** — light/dark/system theme picker
2. **Trust dialog** — "Do you trust the files in this directory?"
3. **Bypass-permissions warning** — safety acknowledgment (when using `--dangerously-skip-permissions`)
4. **OAuth login** — browser-based auth (if no token is configured)

Each of these blocks the process waiting for input. In a tmux session or piped context,
CC just hangs silently.

### Pre-Seeding `.claude.json` (Skip Almost Everything)

CC stores onboarding and trust state in `$HOME/.claude.json`. Pre-populate it to skip
all skippable prompts:

```python
import json, os

config_path = os.path.expanduser("~/.claude.json")
config = {}

# Skip theme picker + welcome screen
config["hasCompletedOnboarding"] = True

# Pre-accept workspace trust per directory
config["projects"] = {
    "/workspace/my-repo": {
        "hasTrustDialogAccepted": True
    }
}

with open(config_path, "w") as f:
    json.dump(config, f, indent=2)
```

This eliminates the theme picker, welcome screen, and trust dialog. The only prompt
that can't be pre-seeded is the **bypass-permissions safety warning** — CC always shows
it when `--dangerously-skip-permissions` is used. Auto-accept it with:

```bash
# After launching CC in tmux, wait for it to render, then:
sleep 5
tmux send-keys -t session_name Down    # Select "Yes, I accept"
tmux send-keys -t session_name Enter
```

### Why Not `-p` (Print Mode)?

`claude -p "prompt"` seems ideal for headless use, but it has critical limitations:

- **Buffers ALL output** until completion — no streaming, no progress visibility
- **No session continuity** — each invocation is a fresh session with no memory
- **No mid-flight interaction** — can't course-correct or add context

Interactive mode in tmux is better for anything beyond one-shot queries. You get
streaming output, session continuity, and can inject follow-up prompts via
`load-buffer`/`paste-buffer` (see Section 3).

---

## 3. tmux Orchestration

For persistent headless sessions, tmux is the right primitive. But the integration has
sharp edges.

### Prompt Injection: `load-buffer` + `paste-buffer`, NOT `send-keys`

**This is the single m

Excerpt, first 6,001 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-14
   !CAUTION C 79 / 100

   first audit · source 19bc86343b63

Questions about Headless Claude Code

• github.com/vellum-ai/vellum-assistant/tree/main/skills/headless- — the audited source at commit 19bc86343b63 and every finding aboveObserved · 14 Oct 2026

Spotted something wrong? Report a correction · Methodology