caveat-cli

library0.14.10jsnpmunverified

Long-term memory CLI for Claude Code and Codex that surfaces markdown+SQLite FTS5 entries via MCP and agent hooks. Installs as a global npm CLI tool (v0.14.10) with auto-setup for Claude Code and optional Codex hook integration. Key differentiators: no central shared DB — knowledge is git-based and peer-to-peer; uses SQLite FTS5 for full-text search; caches community repos locally; exposes 6 MCP tools for read/write/pull operations. Requires Node >=22.5 and macOS or Linux.

productivity ai-ml

npm install caveat-cli

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CAVEAT-CLI

caveat-cli

productivityjavascriptv0.14.10

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

caveat (CLI command)

✓ caveat init

✗ caveat-cli init

The package installs the `caveat` binary; do not call `caveat-cli`.

caveat (programmatic use)

✓ import { cli } from 'caveat-cli'

✗ const caveat = require('caveat-cli')

Package is ESM-only; no CommonJS require.

MCP server (register)

✓ claude mcp add --scope user --path /usr/local/bin/caveat

✗ npm run caveat-serve

MCP server is registered automatically by `caveat init`. Manual registration path depends on install location.

Installs Caveat globally, initializes state without Claude integration, creates a personal markdown entry, indexes it, and searches for content via FTS5.

npm install -g caveat-cli caveat init --skip-claude cd ~/.caveat/own && mkdir -p entries echo '# My entry - **tags:** #example - **problem:** The error X happens when Y - **fix:** Do Z ' > entries/my-entry.md caveat pull --no-community caveat search 'error X'

Debug

Known issues

breakingSince v0.7 there is no `caveat push` command — sharing is done via plain git to a team repo.

fix

Use `git push` from your knowledge repo directory (default ~/.caveat/own) instead of `caveat push`.

affects: >=0.7

deprecatedThe `codex-sidecar` subcommands are semi-supported; official Codex integration is via `caveat codex-hook install`.

fix

Run `caveat codex-hook install` for Codex hooks; sidecar may be removed in a future release.

affects: <0.14.10

gotchaCaveat requires Node.js >=22.5. Using older versions will fail to install or run.

fix

Upgrade Node.js to v22.5 or higher via nvm or brew.

affects: >=0.14.0

gotchaOn macOS with Homebrew Node, the hook installation attempts to use `/opt/homebrew/bin/node`. If Node is elsewhere, hooks may break after Homebrew updates.

fix

Ensure `/opt/homebrew/bin/node` exists and points to your current Node binary, or use a version manager like nvm with a stable path.

affects: >=0.1

gotchaNo central DB is auto-subscribed — you must explicitly add community repos with `caveat community add <url>` to see other people's entries.

fix

Run `caveat community add <github-url>` for each team repo you want to include.

affects: >=0.7

Errors

Common errors & fixes

Error: Cannot find module 'sqlite3'

SQLite3 native module not installed (missing build tools or platform incompatibility)

fix

Ensure build-essential (Linux) or Xcode CLT (macOS) are installed, then reinstall: `npm install -g caveat-cli --build-from-source`

Error: Failed to register MCP server: command not found: claude

claude CLI (Claude Code) not installed or not in PATH

fix

Install Claude Code: `npm install -g @anthropic-ai/claude-code` and ensure it's in PATH, or run `caveat init --skip-claude` to skip MCP setup.

Error: EACCES: permission denied, mkdir '/Users/user/.caveat'

Home directory permission issue or user data directory locked

fix

Ensure ~/.caveat is writable. Run `chmod 755 ~` if needed, or move to a different location via `--home` flag.

Error: cannot open database: FTS5 not available

SQLite3 build does not include FTS5 extension

fix

Reinstall sqlite3 with FTS5 support: `npm rebuild sqlite3 --build-from-source` or install system SQLite3 with FTS5 enabled.

Upgrade

Version history

0.14.10latest on npm

Audit

Dependencies

noderequiredRequires Node.js >=22.5 for runtime

sqlite3requiredUses SQLite FTS5 for indexing and search

Agent activity

42 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/kitepon-rgb/Caveat ↗

packagecaveat-cli ↗

homepagehttps://github.com/kitepon-rgb/Caveat ↗