Skip to content

How-to guides

Recipes for getting one specific thing done. Each assumes you already know what you want and shows the shortest way there.

Most of these need nothing installed. Working with memories, agents, chatbots and your team happens in the portal, or by prompting an agent you have already connected. The first group below is only for getting Hadron into a particular editor or terminal — skip it if that is not what you came for.

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.
  • Grant an App access to a connection — delegate scoped, revocable access on a mailbox, calendar or drive connection you own to one App install, check what you have granted, and take it back. Owner-only, with no admin bypass.
  • 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 — make a memory hold records of a fixed shape and refuse ones that don't fit: have your agent draft the schema, save it in the portal, add records against it, and check the ones written before it.
  • Query nodes by their properties — pull out exactly the records that match a condition, by asking your agent or with the portal's Properties filter; then the where predicate end to end.
  • Sort results by a property value — put records in the order you need, by asking your agent (MCP sorts a collection through hadron_find_objects) or with the portal's Sort by property; then sortProperty on GraphQL and the CLI. Missing values sort last.
  • 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 — needs a terminal. 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 — delete a memory in the portal: who can delete which memory, the two you can't delete directly, what deleting an agent or an App does to memories, and why there's no undo.
  • Debug PERMISSION_DENIED errors — someone can't see or change what they should: check their access in the portal (⌘K → Check access), then find the closed gate and open 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.
  • Upload a file in an agent chat — attach a file in an App's agent chat: where it's stored, the limits, scanning, and why an upload is refused.

Chatbots

Build conversational agents and test them.

  • Building a chatbot agent — a chatbot that holds a structured conversation in stages and remembers what each user tells it, built in the portal: the wizard, the Conversation Editor, prompts, extraction, routing rules and publishing. Hosting it in your own app through the Chat API is below.
  • Build a conditional conversation flow — author edge conditions so a stage is skipped when its data is already on file.
  • Chatting with an agent — start a chat from an App's Chats tab, and choose between a private and a shared chat.
  • Test a chatbot with scripted personas — run a scripted user through your chatbot in the portal Tester and get a pass/fail report of where it went.
  • Portal chat testing — manual smoke-test checklist for agent chat in an App.

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.
  • Install and update your Hadron skills — one command puts every skill your memories publish on this machine and keeps it current; what to do when one is refused, skipped or orphaned.
  • Build a Hadron skills plugin — package every skill your memories publish into one installable plugin, install it in Claude Code without git, update and share it.
  • 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.

Agent team

Give your AI coworkers names, and run work that traces back to who did it. A worker is a named casting of a role agent into one team App — Iris, Dara, Tove — driven by a human across many worker sessions. These guides go in order: build the team, get it talking, keep a coordinator running, and recover when the chat session driving a worker loses its context. Those are two different things, and only the chat session is lost — the worker session stays open on the server, which is exactly what makes recovery possible. The model behind all of it is Teams, workers, and sessions.

  • Set up an AI team with your agent — the delegated path, and the one most people want: what to ask a coding agent for, how to check each step actually happened, and the four decisions that stay yours rather than the agent's.
  • Set up an AI team — build a Team Agent that bundles role agents, install it as one App, cast named workers into it, and run coding sessions attributed to a worker and the human who drove it, so a merged PR traces back to its transcript.
  • Run a resident coordinator — host a worker as an always-on Claude Code session fed by the relay sidecar: host layout, the two tokens each operator brings, adding worker N+1, and what survives a crash, a reboot, or a resident going quiet.
  • Work with your team coordinator — zero-installation guide for everyone else: talk to a resident coordinator in the portal team chat, and what to expect from a reply.
  • Manage your team's Channels in the portal — add, rename and delete an App's Channels, choose which workers and agents follow each one (including agents that react only when mentioned), and see what someone actually follows. Portal only, nothing to install; the settings decide attention, never access.
  • Recover after a context compaction — after Claude Desktop compacts the conversation, get your agent back to being the teammate it was — one sentence to the agent; underneath, hadron_whoami and hadron_get_worker, with no second worker session and no takeover. Covers the silent failure: a lost session id posts to the team chat as you, not the worker.
  • Trace a PR back to its session — find which AI teammates worked on a pull request, what each recorded doing, and from which worker sessions, by asking your agent or in the portal's Worklog; the person and model behind a colleague's session need the CLI or the API. Covers both directions of the query, why Session.prNumber is a display label rather than the index, and why the provenance you get out is only ever what the bind recorded.