TYPESCRIPT / OSS · CASE STUDY

headless_core.

AI agents, behind one interface.

A core library for Node.js that lets applications work with local CLIs such as Codex, Claude Code, and Grok in a common way.

TypeScriptNode.jsCLI adaptersAbortSignal

example.ts　—　headless_core

const result = await core.run({
  agent: { provider: 'codex' },
  prompt: 'Build something',
  onProgress: onUpdate
});

ILLUSTRATIVE CODE · SEE REPO FOR EXACT API

CONCEPT VISUAL / SCHEMATIC

01 / PROBLEM FRAMING

What problem does it solve?

When every tool differs in how it's invoked, what it returns, how it reports progress, and how it handles timeouts, apps that embed AI agents get complicated. I'm designing a thin common layer that absorbs those differences.

02 / DESIGN DECISIONS

What I chose, and how I built it.

DESIGN NOTE / 01

One shared entry point

Run different local agent CLIs through the same run() API.

DESIGN NOTE / 02

Observe progress

Receive output while it's running via onProgress.

DESIGN NOTE / 03

Control termination and failure

Supports AbortSignal, timeoutMs, and fallback hooks.

DESIGN NOTE / 04

Normalize model settings

Translates differences in models and reasoning effort across providers.

03 / HOW IT WORKS

The big picture.

The app calls run()→Provider adapter→Local agent CLI→Results and progress return

A simplified concept diagram for clarity. See the source code for exact implementation details.

For technical details, the README and source code in the public repository are the primary source.

Read the README and code on GitHub ↗

04 / STATUS & LIMITATIONS

Status and caveats.

headless_core is not a web API server; it's a library that launches local CLIs. See the README for each CLI's permissions, authentication, and security considerations.

Want to try it?

This page is an introduction. Installation steps, requirements, license, and the latest status are in the public repository.

Check out headless_core on GitHub ↗