index.mdx

title	Introduction

Hit the endpoints directly. Best for SDKs, services, and CI integrations. A local binary that analyzes your repo and writes graph sidecars next to your source files. Best for day-to-day work in the terminal.

CLI quickstart

The fastest path: install the binary, go to your repo, and run supermodel. If no config exists, it handles setup automatically; after that it starts the live graph watcher.

1. Install

curl -fsSL https://supermodeltools.com/install.sh | sh

Other options: npm install -g @supermodeltools/cli or build from source. See Installation.

2. Start the live graph watcher

cd /path/to/your/repo
supermodel

If no config exists, supermodel launches setup automatically. It authenticates you, confirms the repo, offers to install the Claude Code hook, and enables writing .graph.* sidecars next to source files.

Then supermodel builds the graph and stays running as the live watcher. Press Ctrl+C to stop and clean generated sidecars.

3. Tell your agent the sidecars exist

Pipe the awareness prompt into your agent's instructions file:

supermodel skill >> CLAUDE.md
# or AGENTS.md, .cursorrules, etc.

Use >> to append to existing instructions instead of replacing them. If the Supermodel block is already present, skip this step or remove the old block before running it again.

The prompt explains the naming convention (Foo.py → Foo.graph.py), the three sections inside each sidecar ([deps], [calls], [impact]), and tells the agent to read the sidecar before the source file.

4. What you get

After the watcher runs, each source file gets one .graph.* sidecar with dependency, call, and impact sections:

src/
├── login.go
└── login.graph.go     ← deps, calls, impact, domains, and blast radius

Example output shape from a generated graph file:

// cmd/login.graph.go
// [deps]
// imports     internal/auth/doc.go
// imports     internal/auth/handler.go
// imported-by main.go

// [calls]
// init → LoginWithToken    internal/auth/handler.go:109
// init → Login             internal/auth/handler.go:29

// [impact]
// risk        MEDIUM
// domains     CoreConfig · SupermodelAPI
// direct      1
// transitive  1
// affects     main.go

Your agent reads these via cat and grep like any other file. No prompt changes, no extra context windows.

5. Keep it running

The bare supermodel command is the live graph watcher. Run it any time you want graph files to stay fresh as you code:

supermodel

Live refreshes are driven by hook notifications. If you are not using a hook, run supermodel --fs-watch to watch local file changes directly.

For one-shot analysis (no watcher), use:

supermodel analyze

6. What to do with the graph

Once a graph is cached, every other command reuses it instantly:

Goal	Command
Find unreachable functions	supermodel dead-code
See what a change impacts	supermodel blast-radius path/to/file.go
Codebase health report	supermodel audit
Find usages of a symbol	supermodel find handleRequest
Token-efficient context for one file	supermodel focus path/to/file.go

Start with the supermodel watcher reference or the analyze one-shot reference.