Get Started / Installation

Installation

Heddle is packaged as a global Node.js CLI. Works on macOS, Linux, and Windows with Node.js 20+.

Global Install

Terminal

npm install -g @roackb2/heddle

Installs the heddle command globally so you can run it from any directory.

Run without global install

Terminal

npx @roackb2/heddle

Provider Authentication

OpenAI — Account Sign-in (experimental)

Terminal

heddle auth login openai

Uses your ChatGPT / Codex account. Not official OpenAI support — use is subject to OpenAI's terms.

OpenAI — API Key

Terminal

export OPENAI_API_KEY="your_key_here"

If both OAuth credential and API key are present, prefer the key with heddle --prefer-api-key.

Anthropic — API Key

Terminal

export ANTHROPIC_API_KEY="your_key_here"

Quick Start

Terminal

# 1. Navigate to any repository
cd /path/to/your/project

# 2. Start interactive chat
heddle

# 3. Try a prompt
# "Summarize this repo and show the main entrypoints."

# 4. Start the browser control plane (optional)
heddle daemon

Optional: Semantic Drift Telemetry

Install cyberloop in the same environment to enable drift-level observability in chat sessions:

Terminal

npm install -g cyberloop