headless-agents

Run Claude Code, Gemini CLI, and Codex headlessly through one Node API.

Install

npm install headless-agents

Build the package before local use if you are working from source:

npm run build

Basic Use

import { runAgent } from 'headless-agents';

const result = await runAgent({
  model: 'claude-sonnet-4-6',
  prompt: 'Reply with exactly OK',
  workdir: '/absolute/path/to/project',
});

console.log(result.stdout);

Use From Another Project

If this package is published to npm:

import { runAgent } from 'headless-agents';

If your main project installs directly from GitHub:

{
  "dependencies": {
    "headless-agents": "git+https://github.com/hjyeo30/headless-agents.git"
  }
}

Then in the main project:

import { runAgent } from 'headless-agents';

Publish To npm

For public npm publishing, an unscoped package name like headless-agents can be used if the name is available.

For private npm publishing, use a scoped package name such as:

{
  "name": "@your-scope/headless-agents"
}

Then publish from the package root:

npm publish

If you want a scoped package to be public instead, use:

npm publish --access public

If your main project uses a local checkout:

{
  "dependencies": {
    "headless-agents": "file:../headless-agents"
  }
}

Then in the main project:

import { runAgent } from 'headless-agents';

Provider Notes

• Claude supports --output-format json
• Gemini supports --output-format json
• Codex does not use Claude-style --output-format json

Docs

• Usage
• Architecture