contextsync

The git for organizational context. An open protocol — and a reference implementation — for syncing versioned, permissioned, auditable context between humans and AI agents.

One binary, two modes:

• Run the protocol server locally or on your own infrastructure
• Use the same binary as a CLI client against that server (or any other)

No telemetry, no managed backend, no external LLM calls. SQLite on disk, HTTP and Server-Sent Events on the wire.

Install

npm install -g contextsync

Requires Node.js 20 or newer.

Quickstart

# Terminal 1 — start the server
contextsync start

# Terminal 2 — configure the client, register an actor, write an artifact
contextsync init --server http://127.0.0.1:4111
contextsync actor create --type human --name "Your Name"
contextsync use human-<id-from-previous-output>
contextsync permission grant --actor human-<id> --pattern 'ctx://acme/**' --ops read,write
contextsync artifact create \
  --uri ctx://acme/docs/readme \
  --name "Readme" \
  --message "hello contextsync" \
  --summary "initial"
contextsync artifact get ctx://acme/docs/readme

That is the whole loop: server on one side, a versioned permissioned audited artifact on the other.

Commands

The full command reference is in SKILL.md inside the package, and is also printable:

contextsync skill

Short tour:

contextsync start | migrate | path
contextsync init | use | status | explore | changes
contextsync actor create | list | show
contextsync artifact create | get | update | delete | history | diff | list
contextsync permission grant | list | explain
contextsync subscribe create | list | feed | delete
contextsync provenance list

Run contextsync <command> --help for flags on any subcommand.

Configuration

Server (environment variables)

| Variable | Default | Purpose | | --- | --- | --- | | PORT | 4111 | Listen port | | CTX_BIND_HOST | 127.0.0.1 | Interface to bind. Set to 0.0.0.0 only behind a reverse proxy — auth is trust-based. | | CTX_CORS_ORIGIN | http://localhost:3000 | Comma-separated allowlist, or * (wildcard) | | CTX_DATA_DIR | OS-appropriate (see below) | Root directory for DB + blobs | | CTX_DB_PATH | ${CTX_DATA_DIR}/contextsync.db | Override DB path only | | CTX_BLOB_DIR | ${CTX_DATA_DIR}/blobs | Override blob directory only |

Default CTX_DATA_DIR:

• Linux: $XDG_DATA_HOME/contextsync (falls back to ~/.local/share/contextsync)
• macOS: ~/Library/Application Support/contextsync
• Other: ~/.contextsync/data

Print the resolved paths at any time:

contextsync path

Client

The CLI stores its configuration in ~/.contextsync/config.json. contextsync init writes it; contextsync use <actor_id> updates the acting identity.

Backup and restore

The entire state of a ContextSync server lives in CTX_DATA_DIR. Back it up by archiving the directory while the server is stopped (or quiesced):

contextsync path   # find CTX_DATA_DIR
tar -C "$(dirname "$CTX_DATA_DIR")" -czf contextsync-backup.tgz "$(basename "$CTX_DATA_DIR")"

Restore by extracting back into the same location.

Running as a service

No service file ships yet. For production hosting, run contextsync start under your process manager of choice (systemd, pm2, launchd) with CTX_DATA_DIR and CTX_BIND_HOST set explicitly. Put a reverse proxy (nginx, Caddy) in front if the server needs to be reachable from outside 127.0.0.1.

Security

ContextSync v0.1 authenticates the acting principal with a trust-based X-Actor-Id header only. Any client can claim any actor id. This is adequate for:

• Local development on a laptop bound to 127.0.0.1
• Single-tenant deployments behind an authenticated reverse proxy that injects the header

It is not adequate for public internet exposure. Token-based auth is planned — until then, do not bind to 0.0.0.0 without a front-door.

Agent usage

AI agents should read contextsync skill and drive the CLI in scripted mode (flags, not prompts). The skill file documents the full protocol surface with copy-pasteable flows.

License

Apache-2.0.

Links

• Protocol specification and whitepaper: contextsync-protocol
• Issues and contributions: same repository