onboarding.md

Onboarding: Set Up Omnigraph for a New User

Follow this page when a user asks you to set up Omnigraph for them, for example after pasting the onboarding prompt from omnigraph.dev. It takes them from nothing installed to a working local graph they can query, then points to the next step that fits what they want to build.

Work through the steps in order. Ask the user only where a step says so; take the default otherwise and tell them what you chose. Run each command yourself and check its output before moving on.

1. Install the CLI

Check first whether it is already installed:

omnigraph version

If the command is missing, install it. On macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph/main/scripts/install.sh | bash

or with Homebrew, if the user prefers it:

brew tap ModernRelay/tap
brew install ModernRelay/tap/omnigraph

The script installs into ~/.local/bin. Your shell does not reread the user's startup files, so if omnigraph is still not found, put the directory on PATH for this session and tell the user to add the same line to their shell profile:

export PATH="${HOME}/.local/bin:${PATH}"

Prebuilt Linux archives need glibc 2.39 or newer (Ubuntu 24.04, Debian 13). Windows has a PowerShell installer; older Linux and Intel macOS build from source. Both are in the install guide.

Run omnigraph version again. It prints the CLI version, the storage format it writes (internal-schema) and the HTTP contract it speaks.

2. Load the skill that matches the CLI

The binary carries the copy of this skill written for its own commands. Export it where you load skills, so later sessions use the version that matches the installed CLI:

omnigraph skill export ~/.claude/skills/omnigraph --force --json

Use your own skills directory if you are not Claude Code. If the exported SKILL.md differs from the copy you are reading, follow the exported one from here on (see version-matched skill).

3. Ask what the graph is for

Ask the user one question: what should this graph hold, and who or what will read and write it? Typical answers:

The user wants Start from
A shared memory for a team and its agents: decisions, claims, action items with their sources the company-brain cookbook
A personal knowledge base: projects, people, notes the second-brain cookbook
A work queue for coding agents the beads cookbook
Issues, decisions, specs and releases of a software project the dev-graph cookbook
Market or competitive research the industry-intel or pharma-intel cookbook
Deals and portfolio tracking the vc-os cookbook
Requirements, budgets and verification of a hardware program the hardware-program cookbook
Something else a schema of their own (step 4)

The cookbooks are full cluster deployments with seed data, stored queries and policies. If one fits, tell the user, and offer either to follow its README or to start with the small local graph below and grow it. Start small unless they ask for the full deployment.

The cookbooks pin a CLI and server release, named at the top of their README. Follow a cookbook only when omnigraph version reports that release, or after installing it (release channels shows how to pin a version). Otherwise borrow its schema and queries for the local graph below.

4. Design a first schema

In a new project directory, write two files.

First the questions, as .gq queries in queries.gq: three to five reads the user will actually run. Then the schema in schema.pg with the node and edge types those queries need, each node with a stable @key. Keep it small: a first schema has a handful of types, and adding types and nullable properties later is cheap. Follow the design flow and the syntax in schema.

A minimal example:

node Source {
  slug: String @key
  title: String
}

node Claim {
  slug: String @key
  statement: String
}

edge Supports: Source -> Claim
query sources_for_claim($claim: String) {
  match {
    $source: Source
    $c: Claim { slug: $claim }
    $source supports $c
  }
  return { $source.title as source }
  order { source asc }
}

Comments are //, never #. Lint both together until clean:

omnigraph lint --schema schema.pg --query queries.gq

Show the user the schema and queries and adjust them before going on.

5. Create the graph and load data

Create a local graph next to the schema:

omnigraph init --schema schema.pg graph.omni

Write a few real records as JSONL in seed.jsonl, taken from what the user told you or from files they point you to. Nodes and edges can share a file:

{"type":"Claim","data":{"slug":"lower-latency","statement":"The migration reduced request latency."}}
{"type":"Source","data":{"slug":"load-test","title":"Load test report"}}
{"edge":"Supports","from":"load-test","to":"lower-latency"}
omnigraph load --data seed.jsonl --mode merge --target ./graph.omni

--mode is required; merge upserts by key. See data changes for the other modes and for mutate.

6. Query it

omnigraph query sources_for_claim --query queries.gq \
  --params '{"claim":"lower-latency"}' --format table --target ./graph.omni

Run each query from step 4 and show the user the results.

7. Show a branch

Branches are how agents change the graph safely. Load new data on a branch, read it there, then merge. branch commands take the branch name as their positional argument, so they address the graph with --target:

omnigraph load --data more.jsonl --from main --branch review/first-change \
  --mode merge --target ./graph.omni
omnigraph branch diff review/first-change --into main --target ./graph.omni
omnigraph branch merge review/first-change --into main --target ./graph.omni

Check each command's --help if the installed CLI differs. See data changes for the review workflow.

8. Leave the project ready for the next session

9. Next steps

Tell the user what they have, then offer the step that fits:

Point them to the quickstart and the Slack community for questions.