Installation

Installation

Threadnote is a thin local workflow around OpenViking. Installing it sets up the OpenViking Python environment, a threadnote command shim, user-level agent instructions, and the local server bound to 127.0.0.1:1933. Everything is local-first: nothing leaves the machine unless you explicitly run share publish.

Prerequisites

• Node.js >= 20. Threadnote ships as the threadnote npm package.
• A Python installer for OpenViking. Threadnote installs openviking[local-embed] using the first available of uv (preferred), then pipx, then python3 -m pip install --user.
• On fresh macOS and modern Linux, when neither uv nor pipx is found the installer offers to brew install uv, because pip install --user is refused under PEP 668 on Homebrew and system-managed Python.

You can force a specific Python installer at any time:

threadnote install --package-manager uv
threadnote install --package-manager pipx
threadnote install --package-manager pip

One-Line Install

curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.sh | sh

This installs the published package from npm and runs threadnote install. It does not use an npm postinstall hook, because setup writes local machine config and should be an explicit action.

threadnote install does the following:

• Installs openviking[local-embed]==0.3.12 (via uv, pipx, or pip --user) if a working install is not already present.
• Creates ~/.openviking config files if they are absent.
• Writes the threadnote command shim.
• Upserts user-level agent instructions (see below) without replacing your personal content.
• Starts the local OpenViking server and checks its health so problems surface immediately.

Use --no-start to skip starting the server and the health check. Use --force to reinstall OpenViking at the pinned version even when a working install is already present.

Confirm the install is healthy:

threadnote doctor --dry-run

Forcing a Runtime

The installer normally runs under Node. Pipe THREADNOTE_RUNTIME to force bun or deno:

curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.sh | THREADNOTE_RUNTIME=bun sh
curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.sh | THREADNOTE_RUNTIME=deno sh

Manual Install

If you prefer to install the package yourself:

npm install --global threadnote
threadnote install
threadnote doctor --dry-run

Preview the actions first with threadnote install --dry-run.

PATH Note

install writes a small command shim to ~/.local/bin/threadnote by default. If ~/.local/bin is not on your PATH, either add it, or set THREADNOTE_BIN_DIR to a directory that is already on PATH before running install:

THREADNOTE_BIN_DIR=~/bin threadnote install

The shim lets you run threadnote from any repo or working directory. See Configuration for the full list of environment variables.

Wire Up Agents (MCP)

Make each agent you use aware of Threadnote. mcp-install prints the commands and config it would write by default; pass --apply to actually change agent config. Run it only for the agents you actually use.

Agent	Where config lands
Codex	codex mcp add threadnote -- threadnote-mcp-server
Claude Code	user-scope Claude MCP config by default (--scope local/--scope project to override)
Cursor	global ~/.cursor/mcp.json
GitHub Copilot (VS Code)	VS Code user-profile mcp.json (override with THREADNOTE_COPILOT_MCP_CONFIG)

# Preview
threadnote mcp-install codex
threadnote mcp-install claude
threadnote mcp-install cursor
threadnote mcp-install copilot

# Apply after review
threadnote mcp-install codex --apply
threadnote mcp-install claude --apply
threadnote mcp-install cursor --apply
threadnote mcp-install copilot --apply

Claude installs at user scope by default so the same OpenViking MCP server is available from any repo or worktree. Use --scope local or --scope project only when you intentionally want repo-scoped Claude config.

The default install uses the bundled stdio adapter (threadnote-mcp-server), because OpenViking 0.3.12 does not expose a native /mcp HTTP route:

codex mcp add threadnote -- threadnote-mcp-server
claude mcp add threadnote -- threadnote-mcp-server

Only use --native-http against an OpenViking build that actually exposes /mcp:

threadnote mcp-install claude --native-http --apply

Open a fresh agent session after installing MCP so the new server registration loads. See Agent Instructions for what the agents are told to do once they can reach Threadnote.

Agent Hooks (Optional, Opt-In)

The instruction files are the cross-agent guidance floor and rely on the agent to comply. For deterministic moments where the agent should not have to remember, Threadnote can also install agent-side hooks. These exist for Claude Code only today; Codex, Cursor, and Copilot hook installs are no-ops that print a clear explanation.

• PreCompact auto-stores a handoff snapshot for the current repo right before Claude compacts the conversation, so the next turn can recall it even if the agent forgot to write a handoff manually.
• SessionStart preloads the latest handoff/feature memory for the current repo into the new session, and prints a one-line [threadnote] vX.Y.Z available; run threadnote update banner when the installed version is behind. Set THREADNOTE_AUTO_UPDATE=1 to skip the banner and have the hook spawn threadnote update --yes in the background instead; the new version takes effect on the next session.

Install them per agent:

threadnote install-hooks claude --dry-run          # preview the change
threadnote install-hooks claude --apply            # add managed entries to ~/.claude/settings.json
threadnote install-hooks claude --remove --apply   # remove them again

Or opt in at install time and let Threadnote drive every supported agent in one shot:

threadnote install --with-hooks

Managed entries are tagged "_threadnote": "managed" so repair and uninstall can rewrite or remove only those entries without touching your own hooks.

Updating

Update the package and refresh local shims, user instructions, and MCP config with one command:

threadnote update

Check without changing anything:

threadnote version
threadnote update --check
threadnote update --dry-run

threadnote version prints the installed version, the latest npm version, and GitHub release notes. threadnote update updates the package, then runs repair so shims and MCP config point at the new version.

Useful flags:

Flag	Effect
--check	Only report whether a newer version is available.
--dry-run	Print update and repair commands without running them.
--yes	Accept applicable post-update memory migrations without prompting.
--no-post-update	Skip post-update migration prompts.
--force	Run the package-manager update even if this version is already current.

Threadnote also runs an opportunistic npm version check when you run human-facing commands such as doctor, start, install, or repair. The check is cached under THREADNOTE_HOME and is disabled in CI or when THREADNOTE_NO_UPDATE_CHECK or NO_UPDATE_NOTIFIER is set.

Some releases include post-update memory migrations. threadnote update runs the new package's migration prompt after repair, explains what will change, and asks before applying. Applied migrations are tracked by id under THREADNOTE_HOME and are safe to rerun. See Migration for the migration commands.

After updating, restart Cursor, Copilot, Codex, Claude, or open a fresh agent session so MCP tools reload.

Repair

If the package or checkout that originally installed threadnote has moved or been deleted, run:

threadnote repair

repair rewrites the threadnote shim and reinstalls the stdio MCP adapter for available agents, so every launcher path and agent MCP config points at the current checkout. It also repairs generated config files and starts OpenViking if its health is failing. Memories live under THREADNOTE_HOME/data and are never affected by a moved checkout.

Uninstall

threadnote uninstall --dry-run
threadnote uninstall

uninstall removes the Threadnote shim, MCP config, launchd config, and managed user instruction blocks. Local memories under THREADNOTE_HOME are preserved by default. To delete all OpenViking data too:

threadnote uninstall --erase-memories

See also

• Configuration
• Seeding Repos and Skills
• Agent Instructions
• Troubleshooting