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
Merged

Make CLI quickstart watcher-first #13

Show file tree
Hide file tree
Changes from 2 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
45 changes: 31 additions & 14 deletions cli/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,38 @@
---
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:
On first run, `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, the same command starts the live graph watcher:
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Align first-run setup wording with command docs

Line 14 currently reads as unconditional behavior, but your command references describe setup as a separate command and daemon mode separately. This contradiction can confuse first-time users about what actually happens when they run supermodel.

Suggested wording tweak 
-On first run, `supermodel` opens the setup flow automatically. It authenticates you, confirms the repo, offers to install the Claude Code hook, and enables `.graph.*` sidecar files.
+If Supermodel is not configured yet, `supermodel` opens the setup flow first. It authenticates you, confirms the repo, offers to install the Claude Code hook, and enables `.graph.*` sidecar files.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
On first run, `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, the same command starts the live graph watcher:
If Supermodel is not configured yet, `supermodel` opens the setup flow first. It authenticates you, confirms the repo, offers to install the Claude Code hook, and enables `.graph.*` sidecar files.
After setup, the same command starts the live graph watcher:
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@cli/quickstart.mdx` around lines 14 - 16, Update the wording that currently
states "On first run, `supermodel` opens the setup flow automatically." to align
with the command docs: clarify that setup is only invoked when no prior
configuration exists (or when running the separate setup command), and that the
live graph watcher (the daemon) only starts either after a completed setup or
when the user explicitly requests daemon mode (e.g., via the daemon flag);
replace the unconditional phrasing with a conditional sentence that mentions the
separate setup command and the daemon/--daemon behavior and keep the subsequent
sentence about starting the live graph watcher conditional on setup completion
or explicit daemon invocation.


```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 updates the graph when files change, writes graph sidecars next to source files, and cleans generated sidecars when you stop it with `Ctrl+C`.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated

## 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.
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 +43,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 +68,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.
23 changes: 9 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`. On first run 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 this is your first run, `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 @@ -52,7 +47,7 @@ The prompt explains the naming convention (`Foo.py` → `Foo.graph.py`), the thr

### 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 +80,13 @@ 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:
For one-shot analysis (no watcher), use:

```bash
supermodel analyze
Expand All @@ -109,4 +104,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