SyncytiumMD

The problem

You use Cursor at work, Claude Code in the terminal, Copilot in pull requests, and three CLI agents on CI. Each one wants its own instruction file. So you maintain four copies of the same rules, they drift, and no agent knows what the others did yesterday.

The idea

Keep the rules once, in .syncytium/, and transpile them into every tool's native format.

.syncytium/          canonical, human-authored, git-tracked  rules/*.md         code style, security, testing, architecture, …  memory/decisions.md  ADRs — why the project is the way it is  HANDOFF.md         live agent baton: who has it, what's next        │        │  syncytium sync        ▼CLAUDE.md   AGENTS.md   GEMINI.md   AGENT.md   CONVENTIONS.md.cursorrules   .clinerules   .roomodes   .windsurfrules   .traerules.cursor/rules/*.mdc          .gemini/antigravity/rules/*.md.github/copilot-instructions.md + .github/instructions/*.instructions.md

Every generated file carries a banner saying where it came from, and syncytium diff --check fails your CI if any of them drift. syncytium clean removes only banner-tagged files — your hand-written rules are never touched.

Quick start

npx syncytium init          # scaffold .syncytium/ (stack auto-detected)npx syncytium sync          # generate every bridge filenpx syncytium graph         # open the 3D knowledge graph in your browser

Requires Node.js 20+. No global install needed; npx works.

What you get

Commands

Run syncytium --help for the full list.

Context

Rules & decisions

syncytium rules [query]                       # search the catalogsyncytium rule add --title "..." --body "..." # add a canonical rulesyncytium rule show <id>                      # inspect onesyncytium rule update <id> --body-file x.md   # edit in placesyncytium rule remove <id>                    # delete + prune generated files
syncytium adr list                            # architectural decisionssyncytium adr add --title "..." --context "..." \                  --decision "..." --consequences "..."syncytium adr show ADR-006syncytium adr remove ADR-006

Multi-agent coordination

syncytium lock acquire --agent "Cursor" --goal "Refactor auth"syncytium lock heartbeat --agent "Cursor"    # extend the leasesyncytium lock statussyncytium lock release --agent "Cursor"
syncytium handoff -i                          # interactive wizardsyncytium handoff --from "Cursor" --to "Claude" \  -s ready_for_review -g "Ship v1" -d "…" -t "…"syncytium log -n 20                           # baton audit trail

Guards

syncytium hook install      # block commits on driftsyncytium hook install --auto-sync   # or just re-sync on every commitsyncytium ci                # .github/workflows/syncytium.yml drift gatesyncytium ci --force        # regenerate an existing workflow

Knowledge graph

syncytium graph                        # 3D WebGL cosmos + vault explorersyncytium graph --category ide         # isolate IDE adapterssyncytium graph --compact              # hide file and tag nodessyncytium graph --no-open --port 4000

The server binds to 127.0.0.1 and rejects non-loopback Host headers (DNS-rebinding guard). It refuses to serve .env*, *.pem, *.key, .git/** and other in-root secrets.

Clicking a tool in the 3D galaxy opens the actual Markdown files it generates: directory targets such as .cursor/rules/ become directory nodes that list their .mdc rules, each file opens in the document panel and is highlighted in 3D, and adapters are marked USED or EMPTY depending on whether their targets exist on disk.

MCP

{  "mcpServers": {    "syncytium": {      "command": "npx",      "args": ["--ignore-scripts", "-y", "-p", "[email protected]", "syncytium-mcp"],      "cwd": "${workspaceFolder}",      "env": {        "SYNCYTIUM_TOKEN": "${SYNCYTIUM_TOKEN}"      }    }  }}

Hardening notes: pin the exact package version instead of @latest, pass --ignore-scripts when launching through npx, keep only the 3-5 MCP connectors a workspace actually needs, and pass any short-lived, read-only credential through the env block rather than command arguments.

Or syncytium mcp if you already have the CLI installed. The server exposes 23 tools, including syncytium_get_context, syncytium_handoff, syncytium_create_rule, syncytium_update_rule, syncytium_remove_rule, syncytium_record_decision, syncytium_sync, syncytium_diff, syncytium_doctor, syncytium_validate, syncytium_validate_fix, syncytium_lock_acquire/release/status, syncytium_get_graph, syncytium_list_trash, syncytium_restore and more. Every input is zod-validated and closed with additionalProperties: false; every property is documented; every stable read tool declares an outputSchema and returns matching structuredContent.

Built-in MCP safety. Every tool advertises MCP readOnlyHint, destructiveHint, idempotentHint and openWorldHint annotations, and the server enforces a per-tool sliding-window rate limit (for example 5 destructive calls per minute). Destructive tools default to dryRun: true; deleting needs dryRun: false and confirm: true. Rules and ADRs are archived under .syncytium/memory/trash/ before removal, so syncytium_restore can undo the operation. syncytium_doctor is strictly read-only. These limits are enforced server-side, so they hold even when a client ignores the annotations.

MCP Registry. The repository root carries a server.json manifest (official registry.modelcontextprotocol.io format) describing the npm package, the stdio transport and the mcp launch argument. The discoverability workflow regenerates llms.txt and llms-full.txt, verifies the manifest against the package (including mcpName), and publishes it with GitHub OIDC - no stored secret and no manual step. A unit test pins the manifest version to package.json so the registry never advertises stale metadata.

.syncytiumignore

Excludes generated targets from both sync and diff. Full gitignore syntax, including **, ?, directory-only patterns and ! negation:

# Don't manage these tools.cursorrules.github/instructions/
# Except this one!.github/instructions/keep.md

Custom adapters

Declare any tool in syncytium.config.json — no code required:

{  "customAdapters": [    {      "id": "zed",      "name": "Zed",      "targetFile": ".rules/zed.md",      "includeHandoff": true,      "includeArchitecture": true    }  ],  "enabledAdapters": ["cursor", "claude", "zed"]}

Library usage

import { SyncytiumEngine } from 'syncytium-md';
const engine = new SyncytiumEngine(process.cwd());await engine.sync();const { hasDrift, summary } = await engine.diff();const graph = await engine.getKnowledgeGraph({ category: 'ide' });

Development

npm installnpm run verify      # typecheck -> build -> 114 tests

See CONTRIBUTING.md and .syncytium/architecture.md.

License

MIT © Miraç Birben