# Vincra

> One global environment for every coding agent. A local TypeScript CLI that keeps global instructions and MCP servers in `~/.vincra`, then projects them into each coding agent's documented user-level configuration. It never edits project-level files.

Vincra is not a cloud service. It runs on the developer's machine, stores portable `${NAME}` environment references instead of secrets, and uses explicit import vs sync directions with hashed drift detection and verified backups.

Full operator reference for coding models: [llms-full.txt](./llms-full.txt)

## Use Vincra when

- The user wants one `AGENTS.md` and one MCP map shared across Codex, Claude Code, Cursor, OpenCode, Devin/Windsurf, and Pi
- The user needs to import an existing agent config, sync Vincra out to other agents, or diagnose drift
- The user asks how to add an MCP server without putting tokens in files

## Do not

- Write project-level `.cursor/`, `AGENTS.md`, or agent config inside a repo
- Store API keys, tokens, or passwords in `mcp.json`; use `${VAR}` and set the variable in the shell
- Run `vincra import` unless that agent should replace the canonical Vincra home
- Run a broad `vincra sync` with `--force` unless the user explicitly wants to overwrite managed drift
- Touch undocumented agent databases or Cursor User Rules files; Cursor rules are a manual paste

## Commands

- `vincra init` — Create `~/.vincra` (`AGENTS.md`, `mcp.json`, `config.json`, `state.json`, `backups/`) without replacing existing files
- `vincra detect` — Detect which supported agents are installed or already configured
- `vincra status` — Show last-verified rules and MCP sync state per agent
- `vincra doctor` — Validate canonical files, backups, env refs, projections, and leftover manual actions
- `vincra diff [agent]` — Compare canonical state with one agent or every agent
- `vincra sync [agent] [--force]` — Project Vincra into one agent or all detected/configured agents
- `vincra import <agent> [--yes]` — Replace canonical Vincra rules and MCP from one agent
- `vincra rules edit` — Back up and open `~/.vincra/AGENTS.md` in `$VISUAL` / `$EDITOR`
- `vincra mcp list` — List canonical MCP servers
- `vincra mcp add <name> --transport stdio|http|sse ...` — Add or replace (`--force`) a server
- `vincra mcp remove <name>` — Back up and remove one canonical server
- `vincra backup` — Snapshot canonical files and every managed target file
- `vincra restore [id] [--yes]` — Verify and restore a backup; omit id for latest
- `vincra --json <command>` — Machine-readable JSON on any command
- `vincra --version` / `vincra --help` / `vincra <command> --help`

Agent IDs: `codex`, `claude`, `cursor`, `opencode`, `windsurf`, `pi`.

## Daily sequence

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

## Direction

```text
agent config  --vincra import-->  ~/.vincra  --vincra sync-->  other agents
```

- `import` makes the named agent the source of truth
- `sync` makes Vincra the source of truth
- `diff` before choosing a direction if the user edited an agent directly
- Broad `sync` stops on `different` unless `--force` or a targeted `vincra sync <agent>`

## Install

```bash
pnpm add --global vincra
# or
pnpm dlx vincra --help
```

Requires Node.js 22.12+. Override the home with `VINCRA_HOME`.

## Docs

- [README](https://github.com/sansynx/vincra#readme)
- [Adapter notes](https://github.com/sansynx/vincra/tree/main/docs/adapters)
- [Security](https://github.com/sansynx/vincra/blob/main/SECURITY.md)
- [npm](https://www.npmjs.com/package/vincra)