Skip to content

Rewrite README: outcome-led headline, how it works, works with any agent #57

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
greynewell merged 1 commit into from
Apr 7, 2026
+82 −45
Merged

Rewrite README: outcome-led headline, how it works, works with any agent #57

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
127 changes: 82 additions & 45 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,60 @@
# Supermodel CLI

[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)](#installation)
[![Website](https://img.shields.io/badge/web-supermodeltools.com-blueviolet)](http://supermodeltools.com)
[![API](https://img.shields.io/badge/API-api.supermodeltools.com-blue)](https://api.supermodeltools.com)
Your AI agent knows your entire codebase — not just the files it's looking at.

Give your AI coding agent a map of your codebase.
Supermodel maps every file, function, and call relationship in your repo and writes a `.graph` file next to each source file. Your agent reads them automatically via grep and cat. No prompt changes. No extra context windows. No new tools to learn.

Supermodel CLI connects AI coding agents to the [Supermodel API](https://api.supermodeltools.com), providing call graphs, dependency graphs, dead code detection, and blast radius analysis as context during your sessions. It operates in two modes: **file mode**, which writes `.graph.*` sidecar files next to your source so agents can read them at any time, and **on-demand analysis**, which runs targeted queries against the graph without touching the filesystem.
```bash
curl -fsSL https://supermodeltools.com/install.sh | sh
```

---

## Links
## How it works
Comment on lines +3 to +13
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 7, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

Missing demo visual in the hero flow (objective miss).

Line 3 onward rewrites the headline well, but the README still lacks the demo GIF/screenshot requested in issue #53. Adding a short terminal capture (supermodel watch stats + agent using .graph data) would close that objective and likely improve conversion.

🧰 Tools
🪛 LanguageTool

[style] ~5-~5: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ompt changes. No extra context windows. No new tools to learn. ```bash curl -fsSL...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 3 - 13, The README hero is missing the demo visual
requested in issue `#53`; add a short terminal GIF or screenshot showing
`supermodel watch` output plus the agent reading `.graph` files to demonstrate
the flow — embed it in the hero section right after the rewritten headline (the
block starting at line 3), include alt text and a one-line caption like "Live
demo: supermodel watch + agent using .graph files", and ensure the image file
(GIF/PNG) is added to the repo and referenced by its filename so the README
renders the demo.


| | |
**1. Map your codebase**
```bash
supermodel watch
```
Uploads your repo to the Supermodel API, builds a full call graph, and writes `.graph` files next to every source file. Stays running to keep files updated as you code.

**2. Your agent reads the graph automatically**

`.graph` files are plain text. Any agent that can read files — Claude Code, Cursor, Copilot, Windsurf — picks them up automatically through its normal file-reading tools. No configuration needed on the agent side.

**3. Ask anything**

Your agent now has full visibility into your call graph, imports, domains, and blast radius — for every file in the repo, not just the ones open in the editor.

---

## Works with any AI agent

`.graph` files are plain text read via grep and cat. There is no agent-specific integration required.

| Agent | Setup |
|---|---|
| **Website** | [supermodeltools.com](http://supermodeltools.com) |
| **API Docs** | [api.supermodeltools.com](https://api.supermodeltools.com) |
| **Dashboard** | [dashboard.supermodeltools.com](https://dashboard.supermodeltools.com) |
| **Twitter / X** | [@supermodeltools](https://x.com/supermodeltools) |
| **Contact** | [abe@supermodel.software](mailto:abe@supermodel.software) |
| **Claude Code** | Run `supermodel watch`; install the hook for live updates (setup wizard handles this) |
| **Cursor** | Run `supermodel watch`; `.graph` files appear in context when you open any source file |
| **GitHub Copilot** | Run `supermodel watch`; open `.graph` files in the editor to include them in context |
| **Windsurf** | Same as Cursor |
| **Aider** | Run `supermodel watch`, then pass `--read '**/*.graph.*'` to include all graph files |
| **Any other agent** | Run `supermodel watch` — if it can read files, it can read `.graph` files |

For live updates in Claude Code, add this hook to `.claude/settings.json`:

```json
{
"hooks": {
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{"type": "command", "command": "supermodel hook"}]
}]
}
}
```

The `supermodel setup` wizard installs this automatically if Claude Code is detected.

---

Expand All @@ -30,12 +66,14 @@ Supermodel CLI connects AI coding agents to the [Supermodel API](https://api.sup
brew install supermodeltools/tap/supermodel
```

### Linux
### Linux / macOS (curl)

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

Runs the setup wizard automatically on first install when attached to a terminal.

### From source

```bash
Expand All @@ -49,10 +87,9 @@ go build -o supermodel .
## Quick start

```bash
supermodel login # authenticate (browser or --token for CI)
supermodel setup # authenticate + configure (runs automatically after install)
cd /path/to/your/repo
supermodel analyze # upload repo, run analysis, write .graph.* files
supermodel status # confirm auth and cache state
supermodel watch # generate graph files and keep them updated
```

---
Expand All @@ -61,12 +98,12 @@ supermodel status # confirm auth and cache state

### File mode

These commands manage `.graph.*` sidecar files written next to each source file. Agents and MCP tools read these files without making API calls.
Manages `.graph.*` sidecar files written next to each source file. Agents read these without making API calls.

| Command | Description |
|---|---|
| `analyze [path]` | Upload repo, run full analysis, write `.graph.*` files (use `--no-files` to skip) |
| `watch [path]` | Generate graph files on startup, then keep them updated incrementally as you code |
| `watch [path]` | Generate graph files on startup, then keep them updated incrementally |
| `clean [path]` | Remove all `.graph.*` files from the repository |
| `hook` | Claude Code `PostToolUse` hook — forward file-change events to the `watch` daemon |

Expand All @@ -85,9 +122,9 @@ These commands manage `.graph.*` sidecar files written next to each source file.

| Command | Description |
|---|---|
| `compact [path]` | Strip comments and shorten identifiers to reduce token usage while preserving semantics (aliases: `pack`, `minify`) |
| `compact [path]` | Strip comments and shorten identifiers to reduce token usage (aliases: `pack`, `minify`) |
| `docs [path]` | Generate a static HTML architecture documentation site |
| `restore` | Build a project context summary to restore Claude's understanding after a context compaction |
| `restore` | Build a project context summary to restore Claude's understanding after context compaction |

### Agent integration

Expand All @@ -99,12 +136,23 @@ These commands manage `.graph.*` sidecar files written next to each source file.

| Command | Description |
|---|---|
| `setup` | Interactive setup wizard — authenticate, configure file mode, install Claude Code hook |
| `login` | Authenticate with your Supermodel account (browser or `--token` for CI) |
| `logout` | Remove stored credentials |
| `status` | Show authentication and cache status |

---

## Add a badge to your README

```markdown
[![Supermodel](https://img.shields.io/badge/supermodel-enabled-blueviolet)](https://supermodeltools.com)
```

[![Supermodel](https://img.shields.io/badge/supermodel-enabled-blueviolet)](https://supermodeltools.com)

---

## Configuration

Settings are stored at `~/.supermodel/config.yaml`. Environment variables override file values.
Expand All @@ -124,32 +172,9 @@ SUPERMODEL_API_KEY=smsk_live_... supermodel analyze

---

## Claude Code integration

### Hook setup

The `hook` command forwards file-change events from Claude Code to the `supermodel watch` daemon so graph files stay current as your agent edits code. Add the following to `.claude/settings.json`:

```json
{
"hooks": {
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{"type": "command", "command": "supermodel hook"}]
}]
}
}
```

Then start the daemon in your repo:

```bash
supermodel watch
```
## MCP setup

### MCP setup

To expose Supermodel graph tools directly to Claude Code, add the MCP server to `~/.claude/config.json`:
To expose Supermodel graph tools directly to Claude Code via the Model Context Protocol, add the server to `~/.claude/config.json`:

```json
{
Expand All @@ -166,4 +191,16 @@ Exposed MCP tools: `analyze`, `dead_code`, `blast_radius`, `get_graph`.

---

## Links

| | |
|---|---|
| **Website** | [supermodeltools.com](http://supermodeltools.com) |
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 7, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Use HTTPS for the website link.

Line 198 uses http://supermodeltools.com while the rest of the doc is HTTPS. Prefer HTTPS here for consistency and trust.

Proposed fix 
-| **Website** | [supermodeltools.com](http://supermodeltools.com) |
+| **Website** | [supermodeltools.com](https://supermodeltools.com) |
📝 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
| **Website** | [supermodeltools.com](http://supermodeltools.com) |
| **Website** | [supermodeltools.com](https://supermodeltools.com) |
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 198, Update the website link in README.md to use HTTPS
instead of HTTP: replace the string "http://supermodeltools.com" with
"https://supermodeltools.com" so the table row "| **Website** |
[supermodeltools.com](http://supermodeltools.com) |" consistently uses HTTPS and
matches the rest of the documentation.

| **API Docs** | [api.supermodeltools.com](https://api.supermodeltools.com) |
| **Dashboard** | [dashboard.supermodeltools.com](https://dashboard.supermodeltools.com) |
| **Twitter / X** | [@supermodeltools](https://x.com/supermodeltools) |
| **Contact** | [abe@supermodel.software](mailto:abe@supermodel.software) |

---

*Questions? Open an issue or email [abe@supermodel.software](mailto:abe@supermodel.software).*
Loading