Skip to content

How-to guides

Task-oriented recipes. A how-to guide answers "how do I X?" for a reader who already knows what they're trying to do.

The guides are grouped by what you're working on. If you only care about one feature area, jump straight to its group.

Getting started

Get Hadron into the tool you work in, and set up keys and providers. Do this once.

  • Add Hadron as a Connector in Claude (Settings) — the recommended path for Claude apps: add it once as a Connector from Settings, sign in with OAuth, and it works across claude.ai and the desktop app.
  • Add Hadron to Claude Code (OAuth) — the shortest path: register the Hadron MCP server and sign in with OAuth in three steps. No API keys, no skills.
  • Install Hadron with the install script — one-liner setup for .mcp.json + the Hadron Spec Kit extension in a coding-agent project.
  • Install Hadron in Claude Desktop — OAuth-based install: paste the MCP URL, sign in once in the browser, no copy-paste of secrets. Production + local-dev (cloudflared) paths.
  • Install in Cursor — add Hadron as an MCP server in Cursor via OAuth, and use Cursor Rules to pin an App per project.
  • Install Hadron in VS Code — same OAuth flow for VS Code's built-in MCP support.
  • Install in OpenCode — add Hadron as a remote MCP server in OpenCode via OAuth, with the AppKey alternative and a local-dev tunnel.
  • Install the hadron CLI — Homebrew/archive/Go install, browser or token sign-in, and pointing AI agents at the CLI.
  • Install the macOS menu bar app — build Hadron for Mac from source, sign in with OAuth, and browse memories, task nodes, and search from the menu bar.
  • Install the Chrome extension — add the browser extension, sign in with OAuth, and clip the authenticated page or a local file into a memory, and run task nodes from the toolbar.
  • Configure your LLM provider — pick a provider (Anthropic, OpenAI, GLM, AWS Bedrock), enter a key, test it.
  • Manage your API keys — mint user-scoped API keys for scripts and CLI tools, see every key issued on your account (portal + OAuth), and revoke leaked keys instantly.

Administration

Run your organization and support its members — for Admins and Owners.

  • Impersonate a member for support — see Hadron as another member of your organization sees it: a read-only, org-scoped, time-limited session for diagnosing access problems, from the portal or the CLI.

Platform & operations

Extend and self-host the platform — advanced, for operators and tool builders.

  • Add a capability tool — extend the platform with a new stateless sidecar tool: the service shape, the thin server-side client with typed GraphQL errors and graceful degradation, env config, internal-only deployment, and a new-tool checklist.
  • Harden a capability tool's outbound requests — when a tool dials a user-supplied URL, guard the egress against SSRF and DNS rebinding: refuse private address space, require https for public hosts, and pin the validated IP to close the rebinding window.
  • Configure AWS SageMaker for vector embeddings — point your Hadron server at an existing SageMaker endpoint for the RAG vector index: env vars, a dedicated IAM principal, and verification.
  • Run local LLMs with llama.cpp — the free, offline dev backend for the RAG vector index on macOS / Apple Silicon: a local nomic-embed-text endpoint, plus chat models with one-line start/stop scripts.

Memory

Manage the knowledge graph itself — the core every other feature builds on.

  • Adding nodes to a memory — add nodes from the portal UI, including the auto-slug behavior, advanced types, and conflict / validation errors.
  • Add a memory to an App — put a memory in an App's reach: create a new App-scoped app/personal/private memory, or attach an existing free-standing one (which keeps its URN, class, and owner).
  • Give a memory a structured schema — declare a Memory.schema with typed, required, and enum fields, tag nodes with an objectType, and see non-conforming writes rejected. Schema-on-write, non-retroactive.
  • Query nodes by their properties — the where predicate end to end: an eq leaf, an and/or tree, number/datetime casts, objectType faceting, and composing with keyword or vector search.
  • Sort results by a property value — order findNodes by a properties/data JSON path with sortProperty (GraphQL, the CLI's --sort-property, or the portal's Sort by property; not MCP); missing values sort last; it overrides the sort enum.
  • Store and query records with the object store — the friendly path: createObject / findObjects / updateObject / deleteObject (GraphQL + MCP) to CRUD flat { id, type, ...fields } records, with match/where/sort and merge-on-update.
  • Work with objects from the CLI — the hadron object command group: treat a memory as a small database of typed records (create/get/update/find/delete), with merge-on-update and the "which layer?" call between object and node.
  • Maintaining a memory — keep nodes accurate as reality shifts: the three ways a node goes bad, validating against ground truth, pruning the dead, and the caretaker role.
  • Sync a memory from a Git repo — back a memory with a GitHub repo: layout, auth, sync mechanics, and conflict handling.
  • Use Obsidian to view/edit memory — open a synced or exported memory repo as an Obsidian vault, with the Front Matter Title plugin to make citation-numbered nodes readable.
  • Share a memory with someone — grant one person reader or writer access to a personal-class memory: who may be a grantee (id, email, handle, or URN), the org-membership audience rule, and how to revoke — or leave a memory shared with you.
  • Private, encrypted memories — encrypt a private memory so its content is readable only by you, with a passphrase-derived key the server never stores: the promise, the costs, and the encrypt / unlock / lock flows.
  • Deleting a memory — remove a memory through the portal's Danger-zone affordance, who's authorized for which memory class, and how soft-delete and recovery work.
  • Debug PERMISSION_DENIED errors — decision tree for memory-access errors: find the closed gate, run a diagnostic query, fix it.

AI automation

Build and run headless agents and multi-node automations.

  • Building an agent — set up memories, expose an agent through an app, configure it for AI tools.
  • Build a branching automation — wire a multi-node headless run that classifies an input, branches on an extracted confidence score, and acts on the urgent branch by creating a task node.
  • Call external MCP tools from a flow — register an external Model Context Protocol server, browse the tools it advertises, and let a headless run call them, with the policy chain and action budget governing every call.
  • Monitor a web page — give an agent a durable, GET-only watch on a URL: expose the web_poll tools, start a watch with HTML or JSON conditions, choose a fire policy and TTL, and handle the INTEGRATION run that wakes when a condition trips.
  • Allow your agent to ask for uploads — enable the asset-upload tool on an agent and verify the end-to-end flow.

Chatbots

Build conversational agents and test them.

AI coding

Use Hadron from a coding agent — slash commands, guided sessions, skills, and specs.

  • Use Hadron slash commands in Claude Code — install the hadron plugin for explicit /hadron:h-task, /hadron:hadron_search, and /hadron:h-open-node commands. Needs the OAuth connector as a prerequisite.
  • Run a guided coding session — use the 6-phase guided-session pattern in Claude Code with a worked end-to-end example.
  • Export a task node as a Claude Code skill — publish any task node as a SKILL.md that Claude Code auto-triggers; the node stays the source of truth (edit and re-export). Covers the required claudeSkill properties and the by-hand procedure.
  • Manage product specs with a coding agent — for the spec owner, no tooling required: ask a coding agent to find, change, and create specs in plain language, and keep the one decision that is genuinely yours — amend or supersede.
  • Read and cite product specs — find the rule that governs a behaviour: search a spec corpus by meaning, resolve a citation, follow the provisions it inherits, and spot a retired spec.
  • Maintain product specs — the write side: scaffold a corpus with hadron spec, share provisions through contracts, lint against the rubric, and supersede without renumbering.
  • Amend a spec — change a spec that already exists: decide whether to amend or supersede, edit the body and abstract together, and find specs whose abstract has drifted from their body.
  • Set up an agent team chat — coordinate multiple AI agents and humans on a shared task through a Hadron-backed chat: server-ordered messages, a runnable kickoff prompt, and optional push delivery into live Claude Code sessions.
  • Set up an AI team with personas — build a Team Agent that bundles named Worker Agents, install it as one App, and run coding sessions attributed to a persona and a human, so a merged PR traces back to its transcript.