claude-headless

Name: claude-headless
Availability: InStock
Author: alxx

Control Claude Code headlessly via NDJSON streams for custom interfaces.

12|2|Updated Mar 17, 2026

Search Tags:#typescript #session-management #subprocess #ndjson #ui-integration #permission-hooks #claude-headless

Ready to run

npx skills add https://github.com/alxxpersonal/forge --skill claude-headless-alxxpersonal

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: claude-headless
Source: https://github.com/alxxpersonal/forge/tree/main/skills/claude-headless
Command: npx skills add https://github.com/alxxpersonal/forge --skill claude-headless-alxxpersonal

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Build custom UIs and applications that control Claude Code running in headless mode, enabling programmatic prompts, streaming responses, and session management without using the interactive CLI.

Core Features & Use Cases

Spawn Claude as a headless subprocess and feed NDJSON prompts over stdin while reading streaming NDJSON events from stdout.
Use permission hooks and session management to support desktop apps, TUI, and web UIs that wrap Claude Code.
Extend with custom UIs, dashboards, or integrations that require a local Claude Code instance.

Quick Start

Launch Claude headless as a subprocess and feed an NDJSON user message to its stdin, then read the streaming NDJSON on stdout to receive the assistant response.

Frequently Asked Questions about claude-headless

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I control Claude Code programmatically without the interactive CLI?▼

You can control Claude Code programmatically by spawning it as a headless subprocess using flags like -p and --input-format stream-json, then feeding NDJSON prompts to stdin and reading streaming NDJSON events from stdout.

Can I embed Claude Code in a custom web UI or desktop app?▼

Yes, embedding Claude Code in a custom web UI or desktop app is possible by using its headless mode to spawn a subprocess, enabling bidirectional NDJSON communication for prompts, streaming results, and tool approvals.

What flags are required to run Claude Code in headless mode?▼

Running Claude Code headless requires spawning flags like -p, --input-format stream-json, --output-format stream-json, --verbose, and --include-partial-messages to enable the NDJSON protocol for bidirectional communication.

How do I handle tool approvals when streaming Claude Code responses via NDJSON?▼

Tool approvals during NDJSON streaming are handled using permission hooks, which allow your custom UI or application to programmatically manage and approve tool requests from the headless Claude Code subprocess.

Does Claude Code headless mode support session management for resuming workflows?▼

Yes, Claude Code headless mode supports session management and optional settings, providing resume options that enable advanced workflows and continuous interactions within your custom UI integrations.

What is the NDJSON protocol used for in Claude Code subprocesses?▼

The NDJSON protocol is used for bidirectional communication in Claude Code subprocesses, allowing you to send user messages over stdin and receive streaming assistant responses and tool events from stdout.