---
title: "Installation"
description: "Requirements, install options, and how to verify that Syngraphe runs."
source: https://syngraphe.dev/getting-started/installation
context-schema-version: 1
---

# 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

::: code-group

```bash [global]
npm install -g syngraphe
```

```bash [one-off]
npx syngraphe status
```

```bash [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`.

```bash
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

```bash
syngraphe --version
syngraphe --help
```

`--help` lists the commands and their flags:

```text
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:

```text
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](https://syngraphe.dev/reference/exit-codes). 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](https://syngraphe.dev/guides/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](https://syngraphe.dev/concepts/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](https://syngraphe.dev/concepts/safety-model) for the guarantees in full.

## Next

- [Quickstart](https://syngraphe.dev/getting-started/quickstart) — a first run, start to finish.