Quickstart

Get SuperSmart Coder running in your project in under 60 seconds. One install, three commands, and Claude Code gains full knowledge of your codebase.

Prerequisites

macOS, Linux, or Windows with PowerShell
Claude Code installed and working
A code project with at least one supported language

Note

SuperSmart Coder is a zero-dependency binary. No runtime, no Docker, no package manager required. The install script downloads the correct binary for your platform automatically.

Install

Run a single command to download and install the SuperSmart Coder CLI.

Mac / Linux

curl -fsSL https://supersmart.ai/install.sh | sh

Windows (PowerShell)

iwr https://supersmart.ai/install.ps1 | iex

What does the install script do?

The script detects your OS and architecture, downloads the correct binary from releases.supersmart-coder.com, places it in ~/.supersmart-coder/ (Mac/Linux) or %LOCALAPPDATA%\SuperSmartCoder (Windows), and adds it to your PATH. No elevated permissions required.

Initialize a Project

Navigate to your project root and run init. This is a one-time setup per project.

Shell

cd your-project
supersmart-coder init

This creates three files:

File	Purpose
`.mcp.json`	MCP server configuration. Claude Code reads this automatically to discover the 9 tools.
`CLAUDE.md`	Project instructions that tell Claude when to use SuperSmart Coder vs. standard tools.
`.gitignore`	Adds `.supersmart-coder.json` so your local config stays out of version control.

Example .mcp.json

{
  "mcpServers": {
    "supersmart-coder": {
      "type": "http",
      "url": "http://localhost:5000/mcp"
    }
  }
}

Sync Your Codebase

Upload your entire codebase to the server. This parses every source file and builds a structured relationship model.

Shell

$ supersmart-coder sync
Syncing to http://localhost:5000...
Found 1,247 source files
  50/1247 files sent (412 facts created)
  100/1247 files sent (891 facts created)
  ...
Sync complete: 1,247 files → 8,392 facts

Tip

The first sync takes 5 to 30 seconds depending on codebase size. Files are sent in batches of 50 and processed in parallel on the server.

Watch for Changes

Start the file watcher to keep the server in sync as you edit code.

Shell

$ supersmart-coder watch
Watching for changes (server: http://localhost:5000)...
Press Ctrl+C to stop
  [sync] src/auth/handler.go: -4 +6
  [sync] src/models/user.go: -2 +3

The watcher polls every 2 seconds using SHA-256 hashing. Only changed files are sent, with a 300ms debounce to batch rapid edits. Run it in a separate terminal or use nohup to background it.

Note

The install script runs init, sync, and watch automatically. If you used the one-line install, your project is already set up and watching.

Using Claude Code

Open Claude Code in your project directory. It reads .mcp.json on startup and all 9 tools appear automatically.

Shell

$ claude

Then just ask questions. Claude will use the SuperSmart Coder tools when the question involves cross-file knowledge:

> What depends on the User model?

Claude uses: who_uses, impact
Found 47 transitive dependencies across Go, TypeScript, and SQL.

> Are there any circular dependencies?

Claude uses: find_cycles
3 cycles detected across 44K imports.

Tip

Claude Code uses standard grep and read for single-file questions and SuperSmart Coder tools for cross-file questions. The CLAUDE.md file tells it when to use which.

CLI Reference

Command	Description
`supersmart-coder init`	Initialize the current project. Creates `.mcp.json`, updates `CLAUDE.md`, adds to `.gitignore`. Run once per project.
`supersmart-coder sync`	Full sync of all source files. Parses code, extracts relationships, and uploads to the server. Use for initial upload or to force a complete refresh.
`supersmart-coder watch`	Watch for file changes and sync incrementally. Polls every 2 seconds with SHA-256 hashing. Press Ctrl+C to stop.
`supersmart-coder status`	Show connection status, server URL, user ID, and repo ID. Pings the MCP endpoint to verify connectivity.
`supersmart-coder version`	Print the installed version number.

MCP Tool Reference

These 9 tools are registered via MCP and auto-discovered by Claude Code through .mcp.json.

ask

Ask any natural language question about your codebase. The server queries the full relationship model and returns a structured answer. Use this for open-ended questions that span multiple files or services.

"What does the payment service depend on?"

who_uses

Find every caller, importer, or consumer of a given function, class, module, or service. Returns transitive results across all languages.

"Who calls CreateOrder?"

impact

Blast radius analysis. Given a proposed change, returns every service, function, and test that would be affected, transitively.

"What breaks if I change the User model?"

review

Review code changes for architectural issues, inconsistencies, and potential problems. Understands the full context of how the changed code connects to the rest of the system.

"Review these changes for safety issues"

explain

Explain what a function, class, or module does in the context of the larger system. Goes beyond the source code to show how it fits into the architecture.

"Explain the auth middleware and what depends on it"

check_consistency

Find contract violations, naming inconsistencies, and architectural rule violations across the entire codebase.

"Are all public API endpoints behind authentication?"

health

Get codebase health metrics including coupling analysis, dependency hotspots, and architectural complexity scores.

"Which modules have the most dependencies?"

trace

Trace data flow or call chains across function and service boundaries. Follows variables and parameters as they pass through the system.

"Trace userId from API input to database write"

find_cycles

Detect circular dependencies across import, call, and dependency relationships. Returns up to 20 unique cycles with the full chain.

"Find circular dependencies in the Go packages"

Supported Languages

Language / Format	Extensions
Go	`.go`
JavaScript / TypeScript	`.js` `.ts` `.jsx` `.tsx`
Python	`.py`
C#	`.cs`
Java	`.java`
Kotlin	`.kt` `.kts`
Swift	`.swift`
SQL	`.sql`
Protocol Buffers	`.proto`
GraphQL	`.graphql` `.gql`
Terraform	`.tf`
YAML	`.yaml` `.yml`

Special Files

These files are also parsed regardless of extension:

Dockerfile
docker-compose.yml / compose.yml
Jenkinsfile
Chart.yaml (Helm)
package.json, go.mod, pom.xml, requirements.txt, Cargo.toml, Gemfile

Ignored Directories

These directories are automatically skipped during scanning:

node_modules, .git, bin, obj, venv, __pycache__, dist, build, target, .idea, .vs, vendor, coverage, .next, generated

Troubleshooting

Claude Code does not see the SuperSmart tools

Make sure .mcp.json exists in your project root and the server is running. Run supersmart-coder status to check connectivity. Restart Claude Code after creating .mcp.json since it reads the file on startup.

Sync is slow

The first sync parses every file. Subsequent syncs via watch only send changed files, which is much faster. Files larger than 500KB are automatically skipped. If sync is still slow, check that you do not have large generated or vendored directories that are not in the ignore list.

Unsupported file type

Only supported languages are parsed. Other files are silently skipped. If you need support for a language not listed, contact us.

Watch mode uses too much CPU

The watcher uses polling (every 2 seconds) rather than OS-level file watchers for cross-platform compatibility. This is lightweight for most projects. For very large monorepos (50K+ files), consider running sync manually when needed instead of watch.

How do I uninstall?

On Mac/Linux, remove ~/.supersmart-coder/ and the PATH entry from your shell rc file. On Windows, remove the %LOCALAPPDATA%\SuperSmartCoder folder and the PATH entry from your environment variables. In your project, delete .mcp.json, .supersmart-coder.json, and the SuperSmart Coder section from CLAUDE.md.