diff --git a/README.md b/README.md index e7ceb75..f103bfb 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Give your AI coding agent a map of your codebase. -Supermodel CLI connects [Claude Code](https://claude.ai/code), [Codex](https://openai.com/codex), and other AI agents to the [Supermodel API](https://api.supermodeltools.com) — providing call graphs, dependency graphs, dead code detection, and blast radius analysis as live context during your sessions. +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. --- @@ -22,129 +22,147 @@ Supermodel CLI connects [Claude Code](https://claude.ai/code), [Codex](https://o --- -## What It Does - -| Feature | Description | -|---|---| -| **Graph pregeneration** | Analyze your repo upfront so your agent has instant access to call and dependency graphs without waiting mid-task | -| **Dead code detection** | Surface functions and files with no callers across TypeScript, JavaScript, Python, Go, Rust, and more | -| **Blast radius** | Before making a change, show which files and functions would be affected downstream | -| **Token efficiency** | Ship only the graph slices relevant to the current task — not the whole repo — keeping context lean | -| **Agent integration** | Plug directly into Claude Code, Codex, and Hermes as a context tool | - ---- - ## Installation ### macOS ```bash -# placeholder: brew install supermodeltools/tap/supermodel +brew install supermodeltools/tap/supermodel ``` ### Linux ```bash -# placeholder: install script curl -fsSL https://supermodeltools.com/install.sh | sh ``` -### From Source +### From source ```bash git clone https://github.com/supermodeltools/cli cd cli -# placeholder: build instructions +go build -o supermodel . ``` --- -## Quickstart - -### 1. Authenticate +## Quick start ```bash -supermodel login -# Opens your browser for GitHub OAuth +supermodel login # authenticate (browser or --token for CI) +cd /path/to/your/repo +supermodel analyze # upload repo, run analysis, write .graph.* files +supermodel status # confirm auth and cache state ``` -### 2. Pre-generate your graph +--- -```bash -cd /path/to/your/repo -supermodel analyze -# Uploads repo, runs analysis, caches graph locally -``` +## Commands -### 3. Use with your agent +### File mode -**Claude Code:** -```bash -# placeholder: MCP server config or plugin setup -supermodel claude-code install -``` +These commands manage `.graph.*` sidecar files written next to each source file. Agents and MCP tools read these files without making API calls. -**Codex:** -```bash -# placeholder: Codex tool integration -supermodel codex install -``` +| 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 | +| `clean [path]` | Remove all `.graph.*` files from the repository | +| `hook` | Claude Code `PostToolUse` hook — forward file-change events to the `watch` daemon | -**Hermes:** -```bash -# placeholder: Hermes integration -supermodel hermes install -``` +### On-demand analysis ---- +| Command | Description | +|---|---| +| `dead-code [path]` | Find unreachable functions using static analysis (aliases: `dc`) | +| `blast-radius [file]` | Show files and functions affected by changing a file, function, or diff (aliases: `br`, `impact`) | +| `audit` | Codebase health report: circular deps, coupling metrics, high blast-radius files | +| `focus ` | Token-efficient graph slice for a file — imports, callers, types (aliases: `ctx`, `context`) | +| `find ` | Find usages and callers of a symbol across the codebase | +| `graph [path]` | Display the full repository graph (human table, JSON, or Graphviz DOT) | -## Key Commands +### Code tools -```bash -supermodel docs # Generate static architecture documentation -supermodel analyze # Analyze the current repo and cache results -supermodel dead-code # List functions and files with no callers -supermodel blast-radius # Show what's affected if this file changes -supermodel graph # Print or export the graph for the current repo -supermodel status # Show cached graph state and last analysis time -supermodel login # Authenticate with your Supermodel account -supermodel logout # Clear stored credentials -``` +| Command | Description | +|---|---| +| `compact [path]` | Strip comments and shorten identifiers to reduce token usage while preserving semantics (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 | ---- +### Agent integration -## How It Works +| Command | Description | +|---|---| +| `mcp` | Start a stdio MCP server exposing graph tools to Claude Code and other MCP hosts | -1. `supermodel analyze` zips your repository and uploads it to the [Supermodel API](https://api.supermodeltools.com). -2. The API runs static analysis — building a base IR, call graph, and domain classification. -3. Results are cached locally (and on the API) keyed by a content hash of your repo. -4. Your agent tool integration reads from the cache and injects the relevant graph slice into context. +### Auth and config -Graph data is never sent to your AI provider directly — only the slices your agent requests. +| Command | Description | +|---|---| +| `login` | Authenticate with your Supermodel account (browser or `--token` for CI) | +| `logout` | Remove stored credentials | +| `status` | Show authentication and cache status | --- -## Supported Agents +## Configuration -| Agent | Status | -|---|---| -| Claude Code | Planned — [#1](https://github.com/supermodeltools/cli/issues/1) | -| Hermes | Planned — [#2](https://github.com/supermodeltools/cli/issues/2) | -| Codex | Planned — [#3](https://github.com/supermodeltools/cli/issues/3) | +Settings are stored at `~/.supermodel/config.yaml`. Environment variables override file values. + +```yaml +api_key: smsk_... # or SUPERMODEL_API_KEY +api_base: https://... # or SUPERMODEL_API_BASE (default: https://api.supermodeltools.com) +output: human # human | json +files: true # set false to disable .graph.* writing globally (or SUPERMODEL_FILES=false) +``` + +For CI or non-interactive environments: + +```bash +SUPERMODEL_API_KEY=smsk_live_... supermodel analyze +``` --- -## Pricing +## Claude Code integration - +### Hook setup -Usage is metered per analysis. Run `supermodel status` to check your balance. +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 -## Contributing +To expose Supermodel graph tools directly to Claude Code, add the MCP server to `~/.claude/config.json`: + +```json +{ + "mcpServers": { + "supermodel": { + "command": "supermodel", + "args": ["mcp"] + } + } +} +``` -Issues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +Exposed MCP tools: `analyze`, `dead_code`, `blast_radius`, `get_graph`. ---