Get Started / Installation

Installation

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

Before you install

Use Node.js 20 or newer.
Install with npm globally, or run on demand with npx.
Configure at least one provider: OpenAI account sign-in, OpenAI API key, or Anthropic API key.
Run Heddle from the repository you want it to inspect, edit, and verify.

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. Check or remove the credential with heddle auth status and heddle auth logout openai.

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"

Choose an auth path

PathBest forNotes

OpenAI account sign-inQuick local setup with ChatGPT/Codex credentialsExperimental; not official OpenAI support.

OpenAI API keyStable OpenAI Platform usageRequired for hosted web search and drift embeddings.

Anthropic API keyClaude model usageHeddle does not support Anthropic consumer subscription OAuth.

Verify installation

Terminal

heddle --version
heddle auth status
heddle ask "Reply with OK"

The first agent run creates workspace-local state under .heddle/, including saved sessions, traces, memory catalogs, uploads, heartbeat tasks, and run records.

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