Migration

Migration

This guide explains how to adopt threadnote in an existing repo workflow without losing the repo-local instruction model that current agents rely on. OpenViking becomes a shared, searchable context layer on top of your checked-in files; it does not replace them.

Short Answer

Do not remove AGENTS.md, CLAUDE.md, .claude/, or .agents/ as part of the migration.

Those files stay the versioned source of truth for repo-local behavior. OpenViking becomes a shared, searchable context and memory layer on top of them. It helps agents recall handoffs, skills, and curated guidance across tools, but it should not replace the files that fresh agents read directly from the working tree.

Authority Model

When checked-in instruction files disagree with OpenViking, the repo file wins. Update the source file first, then refresh the OpenViking context.

Source	Purpose
AGENTS.md / CLAUDE.md (root)	Canonical repo instructions. Keep small, current, and checked in.
Nested AGENTS.md / CLAUDE.md	Canonical module-specific overrides. Keep next to the code they govern.
.claude/commands, .claude/skills	Executable or tool-specific workflows. Keep where Claude and other local tools discover them.
.agents/	Agent/plugin metadata or repo-local automation config. Keep unless the owning tool no longer uses it.
OpenViking	Durable memory, cross-agent handoffs, searchable snapshots of curated guidance, and seeded skill catalogs.

DX Model

Developers should not need to run recall, remember, or handoff as a normal habit. The intended workflow has three layers:

• Agent-first: Codex, Claude, Cursor, Copilot, or another MCP-enabled agent calls OpenViking tools when the task needs shared context.
• Short CLI fallback: humans and scripts can run threadnote recall, threadnote remember, or threadnote handoff from any repo.
• Checkout-local command: npm run threadnote -- ... is the bootstrap and debugging path before the short command shim is installed.

After MCP install, developers can drive it conversationally:

Recall the last handoff for this branch.
Remember that this repo uses <durable workflow fact>.
Create a handoff for the next agent before you stop.

Run threadnote install so it can add agent-side guidance from docs/agent-instructions.md to user-level Codex, Claude, Cursor, and Copilot instruction files. That guidance tells agents to recall context at task start, store durable memories when explicitly asked or when a reusable workflow fact is learned, and create handoffs automatically before stopping meaningful work. See Agent Instructions for the full text.

Migration Steps

Run install commands from any working directory. Run manifest commands from a repo root, or pass explicit --repo paths.

1. Check prerequisites. Threadnote needs Node.js >= 20.

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

   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

2. Install or repair local OpenViking. This installs the short threadnote command shim to ~/.local/bin and upserts user-level agent instructions by default. The one-line installer already runs threadnote install; run these only for a manual install flow or to preview changes:

   threadnote install --dry-run
   threadnote install

   If threadnote is not found after install, add ~/.local/bin to PATH or rerun install with THREADNOTE_BIN_DIR=<dir-on-path>.

3. Create the developer-local manifest for the repos this machine actually uses:

   threadnote init-manifest --repo ~/src/my-service --repo ~/work/mobile-app

   --repo can be repeated and may point anywhere on the machine. If no --repo is provided, the current git repo is used. The manifest is written to ~/.openviking/seed-manifest.yaml by default and is intentionally not checked in.

4. Verify the local service:

   threadnote doctor --dry-run

5. Inspect curated repo imports before writing anything:

   threadnote seed --dry-run

6. Seed curated repo guidance after reviewing the dry-run output:

   threadnote seed

7. Inspect and seed shared skills:

   threadnote seed-skills --dry-run
   threadnote seed-skills

8. Wire one agent at a time. Preview with the bare command, then re-run with --apply.

   threadnote mcp-install codex
   threadnote mcp-install codex --apply

   Repeat for Claude. Claude installs at user scope by default so it works from every repo/worktree; use --scope local only when a repo-specific Claude MCP entry is intentional.

   threadnote mcp-install claude
   threadnote mcp-install claude --apply

   Cursor installs by updating the global ~/.cursor/mcp.json file:

   threadnote mcp-install cursor
   threadnote mcp-install cursor --apply

   GitHub Copilot in VS Code installs by updating the VS Code user-profile mcp.json file. If VS Code uses a custom profile path, set THREADNOTE_COPILOT_MCP_CONFIG to that mcp.json path before running mcp-install copilot:

   threadnote mcp-install copilot
   threadnote mcp-install copilot --apply

   Later, if the checkout that installed the MCP adapter is deleted or moved, repair it from any fresh checkout:

   threadnote repair

9. Validate recall:

   threadnote recall --query "repo testing guidance"

Repo Paths

The workflow is not tied to any fixed repo list. Repo discovery is manifest-driven:

• ~/.openviking/seed-manifest.yaml: developer-local default manifest, created by threadnote init-manifest.
• THREADNOTE_MANIFEST: override for custom teams, experiments, or CI.
• --manifest <path>: one-off override for seed and seed-skills.
• config/seed-manifest.example.yaml: checked-in example only.

Use threadnote init-manifest --repo <path> whenever a developer adds a new repo they want included. The command derives a stable viking://resources/repos/<repo-name> URI and keeps the seed patterns conservative. See Seeding Repos and Skills for what gets imported and how worktrees are handled.

Refreshing Context

OpenViking stores imported context as durable resources. For v1, treat seed as a first-ingest operation. When a seeded instruction file changes, update the checked-in source first, then refresh the relevant viking:// resource.

Current practical options:

• Remove the old resource with forget, then re-run a scoped seed manifest.
• Use remember for short corrections that should be available immediately.
• Use export/import packs only for moving a known-good local context between machines.

Do not edit OpenViking directly and leave the repo instruction file stale.

What To Remove

Remove nothing during the initial migration.

After the workflow is proven, teams may delete or consolidate only content that has a clear owner-approved replacement. Good candidates are stale handoff notes, obsolete duplicate docs, or abandoned per-agent experiments. Bad candidates are canonical instructions, active commands, active skills, MCP config, or anything required by existing tools.

Cutover Checklist

• doctor --dry-run reports a healthy OpenViking server.
• threadnote works from a different repo or subdirectory.
• mcp-install has been applied for the agent the developer actually uses.
• recall returns seeded guidance.
• A test handoff can be stored and recalled by another agent.
• AGENTS.md and CLAUDE.md still describe the source-of-truth repo rules.
• The team has agreed on which seeded paths are allowed and which sensitive paths stay excluded.

See also

Installation, Seeding Repos and Skills, Agent Instructions, Safety and Security