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, Anthropic API key, or a local Ollama server.
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"

Local Ollama

Terminal

ollama list
heddle --model ollama/llama3.2:latest ask "Reply with exactly: ok"

Start Ollama locally, then choose an installed chat model with the ollama/ prefix. Local models can vary in tool-calling quality, so review traces and diffs carefully.

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.

Local OllamaLocal-first experiments and private model runsNo hosted provider API key required; tool calling depends on the selected model.

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: local models

If you use Ollama, Heddle can run without a hosted provider API key. The terminal and browser model selectors can show installed Ollama chat models when Ollama is running.

Terminal

ollama list
heddle --model ollama/llama3.2:latest ask "Reply with exactly: ok"
heddle chat --model ollama/llama3.2:latest

Optional: Semantic Drift Telemetry

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

Terminal

npm install -g cyberloop