Skip to content

Make CLI quickstart watcher-first #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonathanpopham merged 4 commits into from
Apr 30, 2026
+46 −28
Merged

Make CLI quickstart watcher-first #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c5fef6b
docs: make CLI quickstart watcher-first
jonathanpopham Apr 30, 2026
8348a2d
docs: address quickstart review comments
jonathanpopham Apr 30, 2026
e99712a
docs: clarify agent prompt append behavior
jonathanpopham Apr 30, 2026
2ea3bb5
docs: clarify watcher refresh behavior
jonathanpopham Apr 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 33 additions & 14 deletions cli/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,40 @@
---
title: 'Quickstart'
description: 'Authenticate and run your first analysis'
description: 'Start the live graph watcher'
icon: 'bolt'
---

## 1. Authenticate
## 1. Run Supermodel in your repo

```bash
supermodel login
cd /path/to/your/repo
supermodel
```

Opens your browser, creates an API key, and saves it to `~/.supermodel/config.yaml`. For CI, pass the key directly:
If no config exists, `supermodel` opens the setup flow automatically. It authenticates you, confirms the repo, offers to install the Claude Code hook, and enables `.graph.*` sidecar files.

```bash
supermodel login --token smsk_live_...
After setup, or on any already configured repo, the same command starts the live graph watcher:

```text
[supermodel] [step:1] Building code graph
[supermodel] [step:2] Starting listeners
[supermodel] [step:3] Ready — listening on UDP :7734
```

## 2. Analyze a repo
Leave it running while you code. It refreshes from hook notifications; if you are not using a hook, run `supermodel --fs-watch` to watch local file changes directly. It writes graph sidecars next to source files and cleans generated sidecars when you stop it with `Ctrl+C`.

## 2. Tell your agent the graph files exist

```bash
cd /path/to/your/repo
supermodel analyze
supermodel skill >> CLAUDE.md
# or AGENTS.md, .cursorrules, etc.
```

Uploads the repo, runs call graph + dependency + domain analysis, caches the result locally by content hash, and writes `.graph.*` sidecar files next to each source file.
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`) and tells your agent to read the graph file before the source file.

## 3. Use the results
## 3. Use the live graph

| Goal | Command |
|---|---|
Expand All @@ -36,9 +45,19 @@ Uploads the repo, runs call graph + dependency + domain analysis, caches the res
| Token-efficient context for one file | `supermodel focus path/to/file.go` |
| Print the full graph | `supermodel graph` |

Subsequent commands reuse the cached graph automatically. Pass `--force` to any command to bypass the cache.
These commands reuse the cached graph automatically. Pass `--force` to bypass the cache.

## 4. One-shot analysis

Use `analyze` when you want to build or refresh the graph once and exit instead of keeping the watcher running:

```bash
supermodel analyze
```

`analyze` uploads the repo, runs call graph + dependency + domain analysis, caches the result locally by content hash, and writes `.graph.*` sidecar files next to source files. Add `--no-shards` to skip writing sidecars.

## 4. Configure (optional)
## 5. Configure (optional)

Settings live at `~/.supermodel/config.yaml`. Environment variables override file values.

Expand All @@ -51,4 +70,4 @@ shards: true # set false (or SUPERMODEL_SHARDS=f

## Next

See the [command reference](/cli/commands/analyze) for every command, flag, and example.
See the [`analyze` command reference](/cli/commands/analyze) for one-shot flags and examples.
27 changes: 13 additions & 14 deletions index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ title: Introduction

## CLI quickstart

The fastest path: install the binary and run `setup`. The wizard authenticates you, detects your repo, offers to install the Claude Code hook, and starts the live graph daemon — one command, end to end.
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

Expand All @@ -23,21 +23,16 @@ curl -fsSL https://supermodeltools.com/install.sh | sh

Other options: `npm install -g @supermodeltools/cli` or build from source. See [Installation](/cli/install).

### 2. Run the setup wizard
### 2. Start the live graph watcher

```bash
cd /path/to/your/repo
supermodel setup
supermodel
```

The wizard walks four steps:

1. **Authentication** — opens your browser to create an API key and saves it to `~/.supermodel/config.yaml`.
2. **Repository** — detects the git root and confirms the directory.
3. **Agent hook** — if Claude Code is installed, offers to add a `PostToolUse` hook so `.graph.*` files refresh on every `Write`/`Edit`. Cursor, Copilot, Windsurf, and Aider read the files directly — no hook needed.
4. **Shard mode** — enables writing `.graph.*` sidecars next to your source files.
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.

It then runs the live graph daemon for you. Press `Ctrl+C` to stop.
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

Expand All @@ -48,11 +43,13 @@ 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 setup runs, each source file gets one `.graph.*` sidecar with dependency, call, and impact sections:
After the watcher runs, each source file gets one `.graph.*` sidecar with dependency, call, and impact sections:

```
src/
Expand Down Expand Up @@ -85,13 +82,15 @@ Your agent reads these via `cat` and `grep` like any other file. No prompt chang

### 5. Keep it running

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

```bash
supermodel
```

For one-shot analysis (no daemon), use:
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:

```bash
supermodel analyze
Expand All @@ -109,4 +108,4 @@ Once a graph is cached, every other command reuses it instantly:
| Find usages of a symbol | `supermodel find handleRequest` |
| Token-efficient context for one file | `supermodel focus path/to/file.go` |

See the [command reference](/cli/commands/analyze) for every flag and example.
Start with the [`supermodel` watcher reference](/cli/commands/supermodel) or the [`analyze` one-shot reference](/cli/commands/analyze).
Loading