# Honcho Setup

First-run setup and health check for Honcho memory in Cursor or Grok Bot.

- Repository: https://github.com/plastic-labs/honcho (7877 stars)
- Category: Engineering
- License: AGPL-3.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add plastic-labs/honcho --skill honcho-setup -g -a claude-code -y`
Codex: `npx skills add plastic-labs/honcho --skill honcho-setup -g -a codex -y`
Cursor: `npx skills add plastic-labs/honcho --skill honcho-setup -g -a cursor -y`
Gemini CLI: `npx skills add plastic-labs/honcho --skill honcho-setup -g -a gemini-cli -y`

## Description

First-run setup and health check for Honcho memory in Cursor or Grok Bot. Use when the user asks to set up, connect, sign in to, or check the status of Honcho; when Honcho tool calls return authentication errors; or when the workspace metadata has no user_peer yet.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Honcho setup

Honcho connects as an MCP server over HTTP with OAuth. There is no API key to
paste and no local process to start. Setup is: sign in, pick where memory
lives, record that choice in Honcho so every tool and Bot on the account finds
it.

## Step 1: Sign in

- **Cursor:** open Customize, find the Honcho MCP server, and choose
  Authenticate (or Reconnect). A browser window completes the sign-in.
- **Grok Bot:** tell the user "I need to sign in to Honcho" and follow the
  connect card the Bot shows. Ask the user to complete it in their browser.

Verify by calling `list_workspaces`. An authentication error means the sign-in
did not complete; do not retry other tools until it does.

## Step 2: Choose a workspace

Memory is scoped to a workspace. Ask the user one question:

> Keep Cursor's memory on its own, or share it with another Honcho tool?

First make sure the `cursor` workspace exists: call `create_workspace` with
`workspace_id: "cursor"`. It is get-or-create, so this is safe on every run.

`set_metadata` replaces a resource's whole metadata object. Every write below
is therefore read, merge, write: call `get_metadata`, change only the key in
question, and send the full object back. Never send a single key on its own.

- **On its own:** use the workspace `cursor`. If the `cursor` workspace's
  metadata has a `default_workspace` key from an earlier choice, remove that
  key and write the rest back, or `honcho-memory` will keep using the old
  shared workspace.
- **Shared:** show the user the result of `list_workspaces` and let them pick
  the workspace their other tool uses (for Claude Code the default is
  `claude_code`). Then store the pointer so future conversations find it:
  merge `{"default_workspace": "<chosen>"}` into the `cursor` workspace's
  metadata.

## Step 3: Choose the user's peer

The rest: https://github.com/plastic-labs/honcho/blob/HEAD/integrations/cursor/skills/honcho-setup/SKILL.md