Harness integrations

Derived from the honeycomb knowledge base, captured 2026-06. Written for an external practitioner. ("Harness" is honeycomb's term for a coding assistant it plugs underneath.) Confirm any version-specific detail, including the exact event names and config paths per assistant, against your installed version.

#The concept

honeycomb does not try to be another agent shell. It runs underneath the coding assistants people already use and gives them one shared memory layer. The hard part is that every assistant exposes a different extension surface, and they share almost nothing at the integration layer. The answer is to write the memory logic once inside the daemon and wrap it per assistant with a thin shim. Adding an assistant means writing a shim and a connector, not a memory engine.

honeycomb wires six assistants: Claude Code, Codex, Cursor, Hermes, pi, and OpenClaw. Each reaches the daemon through the same surfaces, and the daemon, the only process that touches storage, does the real work behind every one.

#Three surfaces, one daemon

An assistant reaches honeycomb through three kinds of surface, all thin clients of the daemon. None touch storage directly.

• A connector is install-time. It runs once during honeycomb setup or honeycomb connect <harness>, patches the assistant's config, writes the compiled hook handlers, links team skills into the assistant's locations, and registers the MCP server where the assistant speaks MCP. Connectors never run at session time.
• A hook is a lifecycle event the assistant fires that calls the daemon. Hooks are how capture and automatic recall happen.
• An MCP server is the on-demand tool surface a registered server a harness invokes to ask for memory operations explicitly.

flowchart TD
    setup["honeycomb setup / connect"] --> connector["Connector (install-time): patch config, write handlers, link skills, register MCP"]
    connector --> files["Config plus hook handlers on disk"]
    session["Assistant session"] --> hooks["Lifecycle hooks (thin clients)"]
    session --> mcp["MCP tools (on demand)"]
    files --> hooks
    hooks --> daemon["honeycomb daemon"]
    mcp --> daemon
    daemon --> store[(Storage)]

#The connector contract

Every per-assistant connector is a subclass of a shared base. The base owns install and uninstall and all the shared mechanics; a subclass overrides only four small seams: where the assistant keeps its hook config, which compiled handlers to write, where to link skills, and the native event-name map. All filesystem access goes through an injectable seam, so a connector is testable against an in-memory filesystem and a real config directory is never touched in a test.

Two invariants make a connector safe to run repeatedly:

• Idempotent. Every honeycomb config entry is stamped with a sentinel field. On re-install, the connector filters its own prior entries out by that sentinel, appends fresh ones, and writes the config only if the serialized bytes changed. A no-change re-run writes nothing, so the assistant's hook-trust fingerprint is unchanged and no re-trust dialog appears. This is why honeycomb setup is safe to run on every upgrade.
• Foreign-safe. A third-party hook never carries the sentinel, so honeycomb never reclaims it. Install preserves foreign entries verbatim; uninstall removes only honeycomb's entries and only honeycomb's skill links. A real directory or a foreign symlink at a target path is left untouched.

#Capability detection

Each connector reports whether its assistant is installed by checking that the assistant's config root exists on disk. The CLI drives the registry off that probe: honeycomb setup wires every detected assistant, honeycomb connect <harness> wires exactly one, and honeycomb uninstall reverses only honeycomb's footprint for one assistant or for every detected one.

#The support matrix

Each assistant wires the same logical lifecycle events through its own mechanism; the shim normalizes the native event names and payloads into the daemon's shared shape.

The differences are real but shallow: native event names and payload fields vary, and the context channel is model-only on some assistants and user-visible on others, so each shim normalizes before handing off and renders the context block through its assistant's channel.

#The hook lifecycle

Each assistant maps its native events onto a shared set of logical events. A blank in one assistant's column does not mean a gap in coverage: OpenClaw, for example, batches capture across the whole conversation at the end of a run rather than per event, producing the same rows the daemon would have written incrementally; pi reads its session-start context from a static marker block rather than a live event.

Every hook is a thin client: it reads the credential, normalizes the payload, and makes a local request to the daemon. The hook builds no SQL, holds no storage handle, and decides no scope. The cross-assistant logic (the session-start sequence, capture, the browse intercept, session end, context rendering) lives in a shared core that every shim routes through, so a Cursor shell tool and a Claude Code bash tool reach the same shared intercept.

#The session-start auto-pull seam

The session-start step that makes team collaboration feel live is the auto-pull. On every session start the hook asks the daemon to pull the latest team skills and portable assets. Both pulls are idempotent (a re-pull of a version already on disk writes nothing), fail-soft (any error, daemon down, non-200, refused socket, or timeout, is swallowed so session start is never blocked), and time-budgeted (a short abort timer, so a hung daemon never delays the first turn). Both honor a kill switch (HONEYCOMB_AUTOPULL_DISABLED=1 for skills, HONEYCOMB_ASSET_AUTOPULL_DISABLED=1 for assets). This is why a teammate's freshly mined skill or promoted asset becomes visible within seconds of publication.

#The browse intercept

Before a tool runs, the pre-tool hook looks for memory-path tool calls and rewrites the result from the daemon's response: cat or Read on a path becomes a direct row read, grep or Glob becomes a hybrid search, ls becomes a path-prefix listing, and find becomes a path-pattern query. Write and edit on a memory path are denied with guidance to use the CLI instead, and commands the browse layer cannot model are rewritten to a harmless no-op. Coverage differs by assistant (some intercept the shell tool, some terminal tools only, some have no intercept), but the normalized shape means the same daemon-backed intercept applies wherever it runs.

#MCP registration at install

For assistants that speak MCP, the MCP server is registered during install so its tools appear in the assistant's native tool list, with no separate "add an MCP server" step for the user. The server ships as a self-contained bundle and is registered as a stdio entry; the daemon additionally serves an HTTP transport for HTTP-speaking clients. The tool surface is documented in the MCP tools reference.

#Identity sync

A workspace AGENTS.md file is the source of truth for operating instructions, and the daemon's file watcher syncs it into each assistant's identity file, each copy stamped do-not-edit. A manual re-sync is available through the harnesses-regenerate route.

#Where to read next

• Architecture overview: how the surfaces fit the daemon.
• Capture and memory: what the hooks feed.
• MCP tools reference: the on-demand tool surface.
• CLI reference: setup, connect, and uninstall.