Vincra

One global environment for every coding agent.

Vincra is a local TypeScript CLI that keeps your global instructions and MCP servers in one canonical directory, then safely projects them into each coding agent's documented user-level configuration. It does not modify project-level configuration.

Website · Installation · First-time setup · Daily workflow · Command reference · Supported agents · Contributing · Security

Why Vincra

Without Vincra, every coding agent owns a separate rules file and MCP configuration. Vincra gives you one source of truth, explicit import and sync directions, drift detection, verified backups, and environment-variable references instead of stored credentials.

Existing agent config --vincra import--> ~/.vincra/ --vincra sync--> Other agents
                                           |
                                           +-- AGENTS.md
                                           +-- mcp.json
                                           +-- config.json
                                           +-- state.json
                                           `-- backups/

Installation

Vincra requires Node.js 22.12 or newer and uses pnpm.

Install the published CLI globally:

pnpm add --global vincra@latest
vincra --version

Or run a command without installing it globally:

pnpm dlx vincra --help

Build from source

git clone https://github.com/sansynx/vincra.git
cd vincra
pnpm install
pnpm run build
pnpm link --global
vincra --version

If pnpm says its global bin directory is not in PATH, run pnpm setup, close and reopen your terminal, then run pnpm link --global again.

First-time setup

Start with a new canonical configuration

vincra init
vincra rules edit
vincra mcp list
vincra sync
vincra doctor

vincra rules edit opens ~/.vincra/AGENTS.md in $VISUAL, then $EDITOR. On Windows, Notepad is the expected fallback when neither variable is set. Vincra waits for the editor to close, validates the file, and keeps a backup of the previous rules.

To use another editor for the current PowerShell session:

$env:EDITOR = "cursor --wait"
vincra rules edit

Adopt an existing agent configuration

If Codex already contains the rules and MCP servers you want to keep:

vincra backup
vincra diff codex
vincra import codex
vincra sync cursor
vincra doctor

import replaces the canonical Vincra rules and MCP configuration with the selected agent's global configuration. Review the prompt carefully. sync goes the other direction and makes Vincra authoritative for the selected agent.

Cursor User Rules cannot currently be written through a documented file or CLI. After syncing Cursor MCP settings, copy ~/.vincra/AGENTS.md and paste it into Cursor Settings > Rules. On Windows:

Get-Content "$HOME\.vincra\AGENTS.md" -Raw | Set-Clipboard

Daily workflow

Edit the canonical files, inspect drift, back up, sync, and verify:

vincra rules edit
vincra mcp list
vincra diff
vincra backup
vincra sync
vincra doctor

Useful rules of thumb:

• Run vincra import <agent> only when that agent should replace the canonical Vincra state.
• Run vincra sync <agent> when Vincra should replace that agent's managed rules and MCP map.
• Run vincra diff before choosing a direction if you edited an agent directly.
• Run vincra backup before a broad configuration change.
• Run vincra doctor after every sync and after changing environment variables.

Add MCP servers

Vincra stores portable ${NAME} references, not secret values. Define the referenced variables in your shell or operating-system environment before launching an agent.

Add a local stdio server. Repeat --arg once for every command argument. In PowerShell, keep environment references in single quotes so PowerShell does not expand them before Vincra sees them:

vincra mcp add filesystem --transport stdio --command pnpm --arg dlx --arg @modelcontextprotocol/server-filesystem --arg '${WORKSPACE_ROOT}'

Add a remote HTTP server with a token reference:

vincra mcp add hosted --transport http --url https://mcp.example.com --header 'Authorization=Bearer ${MCP_TOKEN}'

Store a definition without enabling it:

vincra mcp add hosted --transport http --url https://mcp.example.com --disabled

Use --force with mcp add to replace an existing server of the same name. See the adapter notes for transport, OAuth, environment-reference, and disabled-state support in each agent.

The canonical file is ~/.vincra/mcp.json:

{
  "version": 1,
  "servers": {
    "hosted": {
      "transport": "http",
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      },
      "oauth": false,
      "enabled": true
    }
  }
}

Command reference

Every command accepts the global --json option for machine-readable output, for example vincra --json status. Use vincra <command> --help for complete flags.

Command	Purpose
vincra init	Create the canonical Vincra home without replacing existing files.
vincra detect	Detect supported installed or configured agents.
vincra status	Show the last-verified rules and MCP synchronization state.
vincra doctor	Validate canonical files, backups, environment references, agent projections, and known manual actions.
vincra diff [agent]	Compare canonical state with one agent or every supported agent.
vincra sync [agent] [--force]	Project canonical rules and MCP settings into one agent or all detected/configured agents. --force permits broad sync to overwrite managed drift.
vincra import <agent> [--yes]	Replace canonical rules and MCP settings from one agent. --yes skips the interactive prompt.
vincra rules edit	Back up and open the canonical global rules in your configured editor.
vincra mcp list	List canonical MCP servers.
vincra mcp add <name> ...	Add an stdio, HTTP, or SSE server; run vincra mcp add --help for all fields.
vincra mcp remove <name>	Back up and remove one canonical MCP server.
vincra backup	Snapshot canonical files and every managed target file.
vincra restore [id] [--yes]	Verify and restore a backup; omitting the ID selects the latest backup.

Valid agent IDs are codex, claude, cursor, opencode, windsurf, and pi.

Supported agents

Agent	Global rules	MCP	Notes
Codex	Automated	Automated	SSE is skipped; OAuth remains owned by Codex.
Claude Code	Automated	Automated	Supports stdio, HTTP, SSE, and agent-owned OAuth.
Cursor	Manual	Automated	User Rules must be copied through Cursor Settings.
OpenCode	Automated	Automated	Supports stdio and Streamable HTTP.
Devin Desktop / Windsurf	Automated	Automated	Prefers Devin and falls back to legacy Windsurf when detected.
Pi	Automated	Unsupported	Pi has no built-in documented MCP schema.

The exact paths, formats, limitations, and official sources are documented in docs/adapters.

Drift, backups, and credentials

A broad vincra sync operates only on detected or already configured agents. After a successful sync, Vincra hashes the exact managed projection. If a target is changed directly, broad sync stops with different rather than overwriting it unless you explicitly pass --force.

Targeted imports, targeted syncs, MCP edits, rule edits, and restores create backups. Writes are atomic, read back for verification, and rolled back when a write or validation step fails. Unmanaged settings outside an agent's global rules and MCP map are preserved.

Vincra rejects likely plaintext credentials in environment values, authentication headers, command arguments, and URLs. It never stores OAuth tokens. vincra doctor reports missing variables without printing their values and verifies backup manifests and hashes before reporting them healthy.

Servers marked enabled: false retain their definitions and state in Codex, OpenCode, and Devin/Windsurf. Cursor and Claude Code do not document a per-server disabled field in their global MCP maps, so Vincra reports the required manual toggle instead of activating the server or claiming a complete sync.

Set VINCRA_HOME to override ~/.vincra for a portable or test environment.

Troubleshooting

pnpm link --global reports that the global bin directory is not in PATH

Run pnpm setup, restart the terminal, and run pnpm link --global again.

vincra rules edit opened Notepad

That is the Windows fallback. Edit the file, save it, and close Notepad so Vincra can validate the result. Set $VISUAL or $EDITOR before running the command to use another editor.

vincra doctor reports healthy=no

Read each fix: line, run the suggested diff, then deliberately choose import or sync. Manual Cursor rules and manual Cursor/Claude disabled-state toggles remain visible until you complete them.

Remove the global installation

pnpm remove --global vincra

Removing the package does not delete ~/.vincra or agent configuration files.

Development

pnpm install
pnpm run check
pnpm pack --dry-run

Tests use temporary homes and never write to the developer's real agent configuration. Read CONTRIBUTING.md before opening a pull request and report vulnerabilities through SECURITY.md, not a public issue.

License

MIT