Installation

Requirements

Requirement	Version	Why
Node.js	≥ 22.18	The CLI is ESM and uses modern Node built-ins.
Git	any recent	Used to locate the repository root and to read commit dates.

Syngraphe runs on macOS, Linux and Windows. It makes no network calls at runtime.

Install

global

npm install -g syngraphe

one-off

npx syngraphe status

project dev dependency

npm install --save-dev syngraphe

A project-local install is worth considering if you want CI and every contributor to run the same version: the binary is then available as npx syngraphe inside the project without a global install.

The syg shorthand

Installing provides two command names for the same executable: syngraphe and the shorter syg.

syg init
syg check

They are interchangeable. The documentation uses syngraphe throughout, because that is the name the tool is published and referred to under.

Verify

syngraphe --version
syngraphe --help

--help lists the commands and their flags:

Usage: syngraphe [options] [command]

Keeps repository context versioned, current, and understandable by both humans
and coding agents.

Options:
  --scope <path>    Select an existing directory relative to the Git root.
  -v, --version     output the version number
  -h, --help        display help for command

Commands:
  init [options]    Create the repository context and the agent bootstrap files.
  status [options]  Summarize repository context.
  check [options]   Run context integrity checks.
  stats [options]   Report context size, estimated tokens and bloat signals.
  decision          Create and list decision documents.
  state             Create and list state documents.
  history           Create and list history documents.
  help [command]    display help for command

Where it may be run

Every command must run inside a Git working tree. Syngraphe locates the repository root with git rev-parse --show-toplevel and refuses to run outside one:

Not inside a Git repository.
Syngraphe stores repository context in the repository itself, so it must run inside a Git working tree.

That is exit code 2. Commands can be run from any subdirectory: paths are resolved against the repository root by default, never against the working directory. Use --scope <path> to select an existing package directory relative to the Git root; see nested contexts and monorepos.

What it will and will not touch

Syngraphe rejects paths escaping the Git root and detected symlinks or changed parent directories. Its path checks assume a trusted workspace; see the safety model for the limit with hostile concurrent directory changes. It stages complete files before publication. On a first run in a repository, that means .context/, AGENTS.md and CLAUDE.md — and nothing else. See the safety model for the guarantees in full.

Next

• Quickstart — a first run, start to finish.