dotvig

A dependency manager for AI config files — track, diff, and manage config drift.

The Problem

AI tools like Claude Code, Cursor, and Copilot rely on config files — skills, rules, system prompts — that you copy from upstream sources and modify locally. There's no standard way to track where these files came from or whether the upstream has changed. Over time, your local configs drift silently from their sources, and you have no way to know what you're missing or what you've intentionally overridden. dotvig treats your AI config files like dependencies: versioned, traceable, and diffable.

Quick Start

# Install globally
npm install -g dotvig

# Initialize in your project
dotvig init

# Track a file from a GitHub source
dotvig track .claude/skills/commit.md github:anthropics/claude-code/skills/commit.md

# Check status of all tracked files
dotvig status

# Pull upstream updates (fast-forward only)
dotvig pull

# Authenticate for private repos
dotvig auth

Command Reference

dotvig init

Initialize a dotvig manifest in the current directory. Creates .dotvig/manifest.json.

dotvig init

dotvig track <destination> <source>

Start tracking a local file against an upstream source. Copies the source to <destination> and records the origin in the manifest.

dotvig track <destination> <source>

| Argument | Description | | ------------- | --------------------------------------------------------------------------------- | | destination | Local file path to write and track | | source | Source specifier (see Source Specifier Format) |

Options:

| Flag | Description | | ------------ | ---------------------------------------- | | --from-url | Fetch source from an arbitrary HTTPS URL |

dotvig status

Show all tracked files and their drift status relative to their upstream sources.

dotvig status

Output columns: local path, source, last synced, status (current / stale / modified / conflict / missing).

dotvig diff [file]

Show a unified diff between the local file and its upstream source. If [file] is omitted, diffs all tracked files with changes.

dotvig diff [file]

Options:

| Flag | Description | | ------------ | ------------------------------------------ | | --upstream | Show diff against upstream only (default) | | --local | Show local modifications since last sync |

dotvig pull [file]

Pull upstream changes into tracked files. Fast-forward only: updates a file when no local modifications exist and the upstream has changed. If a file has local modifications and the upstream has also changed, it is reported as a conflict and skipped.

dotvig pull [file]

| Argument | Description | | -------- | --------------------------------------------------------- | | file | Optional. Path to a specific tracked file. Omit to pull all tracked files. |

Per-file outcomes: updated (upstream applied), skipped (no upstream change), conflict (local and upstream both changed — resolve manually).

dotvig list

Show all tracked files with their source and sync status. Does not fetch upstream — reads from the local manifest only.

dotvig list

Output columns: local path, source repo and path, branch, last synced date, status.

Options:

| Flag | Description | | --------- | ------------------------------------------ | | --json | Output as JSON for scripting | | --stale | Show only files that are stale |

dotvig untrack <file>

Stop tracking a file. Removes the entry from the manifest but leaves the local file unchanged.

dotvig untrack <file>

| Argument | Description | | -------- | ---------------------------------- | | file | Local path of the file to untrack |

Prompts for confirmation before removing. Use --force to skip the prompt.

Options:

| Flag | Description | | --------- | ----------------------------------- | | --force | Skip confirmation prompt |

dotvig auth

Store a GitHub personal access token for accessing private repositories. The token is saved to ~/.dotvig/auth.json with file permissions 0600. dotvig verifies the token against the GitHub API before saving.

dotvig auth

Options:

| Flag | Description | | ---------- | --------------------------------------- | | --logout | Remove the stored token |

Generate a token at github.com/settings/tokens. The token needs repo scope to read private repository files.

Source Specifier Format

A source specifier tells dotvig where a file originally came from.

GitHub (github:)

github:<owner>/<repo>/<path/to/file>[@<ref>]

| Part | Description | | ------- | ------------------------------------------------------------------------------ | | owner | GitHub username or org | | repo | Repository name | | path | File path within the repo | | @ref | Optional git ref (branch, tag, or SHA). Defaults to HEAD on the default branch |

Examples:

github:anthropics/claude-code/skills/commit.md
github:getcursor/cursor-rules/rules/typescript.mdc@main
github:anthropics/claude-code/skills/[email protected]

URL (--from-url)

Fetch from any public HTTPS URL:

dotvig track .cursorrules --from-url https://raw.githubusercontent.com/getcursor/cursor-rules/main/rules/typescript.mdc

Local

Track a local path — useful for syncing shared configs across a monorepo:

dotvig track packages/api/.claude/settings.json shared/claude/settings.json

Examples

Claude Code skills

Track an upstream skill and detect when it changes:

dotvig init
dotvig track .claude/skills/commit.md github:anthropics/claude-code/skills/commit.md
dotvig status
# .claude/skills/commit.md    github:anthropics/claude-code/skills/commit.md    current

After the upstream skill is updated:

dotvig status
# .claude/skills/commit.md    github:anthropics/claude-code/skills/commit.md    stale

dotvig diff .claude/skills/commit.md
# shows what changed upstream since your last sync

Pulling updates

Pull upstream changes for all tracked files at once:

dotvig pull
# .claude/skills/commit.md      updated
# .claude/skills/review-pr.md   skipped  (no upstream change)
# .cursorrules                   conflict (local and upstream both changed)

Pull a single file:

dotvig pull .claude/skills/commit.md

Resolving conflicts

When dotvig pull reports a conflict, both the local file and the upstream have changed. Resolve manually:

# See what changed upstream
dotvig diff .claude/skills/commit.md

# Edit the local file to incorporate the upstream changes
# ...then re-track to reset the pinned SHA
dotvig untrack .claude/skills/commit.md
dotvig track .claude/skills/commit.md github:anthropics/claude-code/skills/commit.md

Listing stale files

Find all files that have fallen behind their upstream source:

dotvig list --stale
# File                          Source                                              Last synced
# ─────────────────────────────────────────────────────────────────────────────────────────────
# .claude/skills/commit.md      anthropics/claude-code skills/commit.md            2025-01-10

Use --json to pipe into other tools:

dotvig list --stale --json | jq '.[].local_path'

Authenticating for private repos

Store a GitHub token to access private repository files:

dotvig auth
# Enter your GitHub personal access token: ***
# Token verified. Saved to ~/.dotvig/auth.json.

Remove the stored token:

dotvig auth --logout
# Token removed.

Cursor rules

dotvig track .cursorrules github:getcursor/cursor-rules/rules/typescript.mdc@main
dotvig status

Multiple AI tools in one project

dotvig init
dotvig track .claude/skills/commit.md       github:anthropics/claude-code/skills/commit.md
dotvig track .claude/skills/review-pr.md    github:anthropics/claude-code/skills/review-pr.md
dotvig track .cursorrules                   github:getcursor/cursor-rules/rules/react.mdc@main
dotvig track .github/copilot-instructions.md --from-url https://example.com/copilot-base.md

dotvig status
# shows drift status for all four files at a glance

dotvig pull
# pulls upstream changes for all files with no local modifications

Contributing

1. Fork the repo and clone it locally.
2. Install dependencies: npm install
3. Run tests: npm test
4. Build: npm run build
5. Open a pull request with a clear description of the change.

All commands must have unit tests. Code examples in docs must be verified against the actual CLI before merging.

License

MIT © TheSide Agency