Use Node 22+ for terminal clients; hosted chats need no local runtime. Server/development baseline is Node 24. See delivery evidence for tested host versions and provider gates.
Grove Cloud is at usegrove.cloud, with API origin
https://api.usegrove.cloud. Grove Open Source is the self-hosted edition.
ChatGPT and Claude web
Add Grove's remote /mcp endpoint as a custom OAuth connection, approve the exact
pending client in Grove Settings → Connections, then return to your chat and test
save/recall. Follow the hosted-chat guide for host-specific setup,
permissions and current qualification limits. No CLI or session-start hook runs in
either web chat; the Claude Code and Codex packages below are separate integrations.
CLI
npx @miniaxolotl/grove connect
Run inside your project, with your agent installed and on PATH. Grove detects a
single installed agent or offers a terminal choice. Use connect opencode,
connect claude or connect codex to select explicitly, including in scripts.
The command selects Cloud automatically, reuses valid credentials, and opens
account creation or sign-in if needed. The same browser continues to a contextual
approval page. New connections propose all permission and scope checkboxes selected:
read/save/delete, Personal and all current/future notebooks. Review and uncheck
unwanted access under Customize access before approving. Existing connections
preserve their saved choices. Approval can also create/link the current project.
Leave the terminal open. It waits up to ten minutes for approval, checks the effective
grant, performs a bounded read when permitted, and installs the native integration.
Follow the activation step: OpenCode V2 reloads watched configuration automatically,
Claude Code supports /reload-plugins, and Codex needs a restart. This verifies API
access; use the first-memory prompt to confirm the host has loaded Grove.
--json reports recallVerified, restartRequired, hostVerified: false and
nextStep; progress and native installer output go to stderr.
Repeat the same command after interruption or installation failure. Existing grants are reused without widening them; a new project requires a new owner approval. Cancelled or expired requests get a fresh link. Revoked OAuth connections require fresh authorization and approval. Named API keys must already cover the project; they cannot ask the browser to widen their own permissions. Transient polling errors reconnect automatically. A second project cannot replace an outstanding approval; finish or cancel it in Connections before proceeding.
For Grove Open Source, add --url https://YOUR-GROVE-API, or explicitly set
GROVE_API_URL. The API's SITE_URL selects your approval website. A plain connect
defaults to Cloud, even if another origin was configured previously. This command
requires the API/website migration described in Cloud onboarding.
For a persistent grove command, install @miniaxolotl/grove globally. Existing
init, login, status and project commands remain supported. init uses the
older dashboard-approval workflow; a login with no grant reports awaiting-grant.
status checks the API, not whether the host has loaded its plugin.
Diagnose installation and startup
grove doctor --client opencode
grove doctor --client claude --json
grove doctor --client codex --probe --json
Without --probe, diagnosis reads local executable/configuration/credential state
only. It does not start the agent, contact Grove, open sign-in, create telemetry
state or change configuration. Missing or unreadable credentials are distinguished
from an unavailable runtime or malformed configuration; existing credentials are
never deleted to repair a startup problem.
--probe starts only a separate packaged Grove bridge, initializes it and lists its
tool catalog, then makes an authenticated /v1/me request. It does not call memory
tools or write notes. Normal OAuth refresh may update saved credentials. Bridge/API
checks each have a five-second deadline, plus bounded transport teardown.
Results identify their context: cli, bridge_probe or host. A probe is not the
running agent session: hostVerified remains false and host readiness is unknown.
Check Grove in the agent's MCP/plugin interface after activation. Exit status is
nonzero for failed requested/local prerequisite checks; optional unverified hooks
do not prevent explicit tools from working. status --json retains its existing
API-access meaning, and setup now reports API verification separately from host activation.
Typical diagnostic codes include client_missing, artifact_missing,
invalid_config, credential_store_unavailable, sign_in_required,
awaiting_grant, bridge_start_failed, unreachable and api_version_unsupported.
For credential-store errors, repair file access/integrity before signing in again.
For an unpatched OpenCode spawn node error, restart the actual host with Node on
its PATH or update Grove; changing PATH in a tool shell does not repair a running host.
Running grove alone in a terminal starts guided setup; grove --help shows usage.
Fresh login and init default to Cloud when no origin is configured.
For a browser on another machine, grove connect opencode --no-browser prints the link
without launching a browser. The loopback callback must still reach the CLI host.
For a named, scoped headless key created in Connections:
# Supply the key via stdin from your credential manager, not a chat or argument.
grove login --client claude --url https://api.usegrove.cloud --key-stdin
Services may set GROVE_API_URL and GROVE_API_KEY together. Credentials are bound
to API origin, agent and account in $XDG_CONFIG_HOME/grove (default
~/.config/grove), with 0600 files and atomic replacement. GROVE_CONFIG_HOME
can select a dedicated installation. Never set it to a shared project directory.
The active origin is selected per agent so connecting another agent to a
self-hosted instance does not switch your Cloud agent's endpoint.
grove logout --client … revokes the connection and clears local credentials;
it reports when remote revocation could not be confirmed. grove pause/resume
control automatic hooks. GROVE_PRIVATE=1 disables automatic recall locally.
Explicit user-directed tools remain available. Server Settings separately control
automatic recall and capture. A response already sent to a host cannot be recalled.
OpenCode V2
grove connect opencode merges only the Grove entry in the global JSON/JSONC
plugins array. Comments, unrelated plugins and MCP entries are preserved.
{ "plugins": ["@miniaxolotl/grove-opencode-plugin"] }
The V2 plugin registers its packaged stdio MCP bridge, a memory skill and a bounded
context hook through the V2 APIs. The bridge reuses OpenCode's executable (with
Bun runtime mode for compiled hosts), so desktop/background launches do not need
node on PATH. It does not add a second Grove server if one is
already configured. No V1 hook or handwritten MCP transport remains. Plugin option
private: true or session metadata private: true also disables automatic recall.
OpenCode reloads watched configuration automatically; check its MCP tools and
use /reload if Grove has not appeared. grove uninstall --client opencode removes
only the matching plugin entry; it does not delete memories or credentials.
Claude Code
The native host must have Node.js 22 or newer on PATH for the packaged MCP and SessionStart commands. A shell's version-manager setup may not reach desktop hosts.
npx @miniaxolotl/grove connect claude
# Native installation alone:
claude plugin marketplace add miniaxolotl/grove
claude plugin install grove@grove --scope user
The npm marketplace package includes .claude-plugin/plugin.json, .mcp.json,
skills, the SessionStart hook and prebuilt executables. Run /grove:setup if the
connection is not configured. Hook output is structured additionalContext, with
a 1.5-second automatic-memory deadline. Failures leave the host usable; writes
always report their actual result. grove uninstall --client claude calls the
native targeted plugin uninstall.
Run /reload-plugins in an existing session or start a new session to load Grove.
Codex
The actual host needs Node.js 22+ on PATH for the packaged MCP and optional hooks.
Codex can filter inherited environment variables: normal saved Grove credentials
are the qualified setup path. Check custom credential-store/environment settings
in the actual host rather than forwarding an entire environment or copying keys
into project configuration. Optional hooks must be reviewed/trusted in Codex.
Do not rely on GROVE_PRIVATE=1 alone when the host filters it: grove pause
persists the local automatic-memory pause that the bridge can read. Verify the
store used by that host; a CLI-only environment flag does not establish session privacy.
npx @miniaxolotl/grove connect codex
# Native installation alone:
codex plugin marketplace add miniaxolotl/grove
codex plugin add grove@grove
The portable package includes plugin.json, mcp.json, the OpenAI onboarding
skill, memory skill, optional SessionStart hook and prebuilt executables. It works
without npm lifecycle scripts or user compilation. Review/trust hooks in the host;
support varies by surface. CLI/plugin tools remain available without hooks. This
is a local/team marketplace package, not a submitted public-directory plugin.
grove uninstall --client codex calls codex plugin remove grove@grove.
Other MCP clients
Use remote Streamable HTTP https://api.usegrove.cloud/mcp with OAuth or an API key,
or configure the local command:
{ "command": "grove", "args": ["mcp", "--stdio"] }
First run grove login --client cli. grove --help prints help. The bridge
uses the official MCP SDK and the authenticated HTTP API. Stdout is protocol-only.
Scope and capture
All integrations share the note-writing policy: concise, human-readable CommonMark/GFM, useful structure without forced templates, correct notebook/kind and faithful edits. MCP content documentation explicitly requires the complete intended body when editing, not just a changed passage. Packaged skills are generated from the runtime guidance; hosts can cache metadata until refreshed. This adds no automatic writes, format rejection or changes to privacy/permissions.
Connected agents can search/read exact notes, partially edit them, inspect history,
move notes, archive/restore, delete and list/create/rename/move notebooks. Ask for an
action in ordinary language; the agent discovers IDs and checks current versions.
For example: “Move these notes into Gardening” or “Restore the archived checklist.”
update_memory preserves omitted metadata; remember remains the full-save contract.
Both honor paused automatic capture. Deletion hides retained history and has no
ordinary Undo; notebook subtree lifecycle is available only to the owner website
session. See the complete tool reference.
Git HTTPS/SSH origins normalize to git:host/owner/repository, stripping credentials,
query data and .git. Local-only repositories use a hash of their common Git
directory, shared across worktrees. Non-Git tasks default to personal scope.
GROVE_PROJECT_IDENTITY and GROVE_PROJECT_NAME explicitly override local identity.
Hooks retrieve a compact active profile and never persist raw chat/tool output.
Skills guide the agent to save only confirmed context. Automatic saves must set
capture: "automatic"; user-requested saves are explicit. Handoffs use stable task
IDs and versioned updates. Recall results are untrusted reference data, not system
instructions. No importance decay, stale-memory pruning or compaction deletion runs.