convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
luuuc

Sense - Grafo de Símbolos para Agentes de IA

luuuc/sense

Índice estrutural local para agentes de IA entendem seu código sem regrep

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que indexa seu repositório localmente e oferece compreensão estrutural via grafo de símbolos, análise de raio de explosão de mudanças e busca semântica. Reduz chamadas de ferramentas em 47%, tokens em 32% e tempo de sessão em 19% para agentes de código como Claude Code, Cursor e Codex CLI.

Instalação

$npx convez-ai luuuc/sense

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
47
Forks
5
Acompanhando
2
Saúde
85%
Último commit
há 1 dia
Versão
v1.16.3
Issues abertas
10
Contribuidores
3

Casos de uso

  • Reduzir consumo de tokens em tarefas de análise de código estrutural
  • Identificar impacto de mudanças via raio de explosão de dependências
  • Encontrar todos os chamadores de uma função sem ler múltiplos arquivos
  • Detecção de código morto via análise de grafo de símbolos
  • Busca semântica por relações entre componentes

Veredito

Sense é uma solução técnica sólida que reduz drasticamente o custo e latência de agentes de IA em repositórios complexos. Funciona offline, sem SaaS, e benchmarks demonstram ganhos reais em eficiência — ideal para fluxos de trabalho onde estrutura de código importa mais que busca textual.

README

A tradução para o português deste README ainda está na fila.

CI CodeQL Go Report Card codecov OpenSSF Best Practices

Sense ⠎⠑⠝⠎⠑

An MCP server for codebase context, built for AI coding agents.

Side-by-side comparison: Without Sense (19 tool calls, 356K tokens, 121s) vs With Sense (5 tool calls, 109K tokens, 48s)

Your AI agent reads 19 files to answer "who calls this function?" because it has the text of your codebase but never the map. It re-derives structure on every task, burns tokens chasing grep chains, and hallucinates dependencies that don't exist. Sense indexes your repo once and serves a symbol graph plus semantic code search over MCP. Claude Code, Cursor, Codex CLI, and any MCP client finish the same task in 10 tool calls instead of 19, on 156K tokens instead of 228K, with the same correctness (bench/).

One binary, one local index, four tools for your AI. No SaaS account, no API key, no cloud dependency.

Sense sits on your machine, has no learning curve, and isn't for you. It's for your AI.

What changes

Measured across 7 real-world codebases (Discourse, Flask, Next.js, Axum, Gin, Javalin, and a private e-commerce repo). Full methodology and raw data: bench/. Head-to-head leaderboard against Serena, Probe, GitNexus, code-search MCPs: docs/bench-leaderboard.svg.

MetricClaude Code (Opus 4.6)Claude Code (Opus 4.6) + SenseChange
Tool calls per task1910-47%
Tokens per task228K156K-32%
Cost per task$0.42$0.31-26%
Session time91s73s-19%
Score per 100K tokens0.190.30+64%
Score per minute0.280.38+37%

Same correctness, dramatically less work. Sense doesn't make the model smarter. It gives the model structural understanding so it stops wasting effort.

Structural tasks

Tasks that require understanding code relationships, not just reading text, are where Sense pulls ahead.

Task typeBaseline+ SenseWhy
Blast radius0.170.25Pre-computed dependency graph vs. manual grep chains
Find callers0.270.33Graph lookup vs. reading dozens of files
Dead code0.000.05Baseline can't do this at all
Semantic search0.360.38Two-stage retrieval (bi-encoder + cross-encoder) with text fallback

Where Sense doesn't help

Sense is structural understanding, not a general search engine. For tasks that are fundamentally text-grep (find a log message, locate a string literal), plain grep is the right tool and Sense adds nothing. Search text fallback (ripgrep) bridges some of this gap, but it's a fallback, not a replacement.

Install

curl -fsSL https://luuuc.github.io/sense/install.sh | sh

Or download the binary for your OS from the latest release, unzip, and move sense somewhere on your PATH.

With Go (1.25+)

go install github.com/luuuc/sense/cmd/sense@latest

Index Your Codebase

cd /path/to/project && sense scan

Parses your code with tree-sitter, extracts symbols and relationships, embeds everything with a bundled ONNX model, and writes a local .sense/ index. Incremental on every run.

Connect Your AI

cd /path/to/project && sense setup

Auto-detects installed AI tools (Claude Code, Cursor, Codex CLI, and OpenCode) and writes each one's integration configs:

  • .mcp.json / .cursor/mcp.json / opencode.json, the MCP server entry for the detected tool (or any MCP client)
  • CLAUDE.md / .cursorrules / AGENTS.md, routing guidance with a tool substitution table, written from a single shared source
  • .claude/settings.json, lifecycle hooks that nudge Claude toward Sense tools
  • .claude/skills/ and .opencode/skills/, workflow skills for exploration, impact analysis, and conventions

No manual setup. Run sense setup and your AI has structural understanding.

Sense also generates .sense/summary.md, a cold-start map of your codebase (top namespaces, hub symbols, entry points, conventions). Your AI reads it at session start and immediately knows the shape of the project. Zero tool calls to orient.

To re-configure after upgrading Sense:

sense setup

Setup & forget

After sense setup, there's nothing left to do. The MCP server your editor already launches watches your working tree in the background and re-indexes changes as they land, so the index stays current whether the edit came from your AI, your own editor, a git pull, or a branch switch. No second process to start, no --watch to remember. The summary regenerates on every scan. Your AI gets faster answers and burns fewer tokens, and you just stop noticing the friction that used to be there.

What Your AI Gets

Four tools for your AI. A full CLI for you. No sprawl.

ToolCapability
sense_graphSymbol relationships, callers, callees, inheritance, tests, dead code
sense_searchHybrid bi-encoder + cross-encoder semantic code search with keyword and text fallback
sense_blastBlast radius, affected code, affected tests, risk score
sense_conventionsDetected project conventions from source

Your AI stops reading 30 files to answer "who calls this?" It stops hallucinating dependencies. It stops writing code that's correct but doesn't match how your team writes code.

Convention detection

Of the four tools, convention detection is the one nobody else does well. AI tools don't just struggle with structure. They struggle with style. They write correct code that doesn't follow how YOUR codebase writes code.

Sense detects patterns from your actual source code: key types and their declarations, framework idioms (Rails associations, Go interfaces, Django models), architectural layers, and naming conventions. Your AI follows these patterns because it sees them, not because it was told about them. Convention detection isn't a feature. It's the thing that makes AI-written code feel like it belongs.

How It Works

Sense parses your codebase with tree-sitter, extracts symbols (functions, classes, modules, methods) and their relationships (calls, imports, inheritance), embeds each symbol with a bundled quantized ONNX model, and stores everything in a local SQLite index at .sense/.

cd /path/to/project && sense scan

From that moment on, your AI can ask structural questions via MCP. These are what your AI calls. You can run them manually for verification. See CLI.md for the full reference.

The MCP server does more than answer queries: for the life of the editor session it watches the working tree with a debounced filesystem watcher and re-indexes changed files in the background, off the request path. A branch switch re-indexes once from a git diff rather than reacting to every file. If you query a file that changed microseconds ago, the server repairs just that file inline before answering, so an edit is never missed. One project indexes at a time — a single-writer lock means a second editor window or a sense scan --watch in a terminal serves reads without double-indexing. Set watch: false in .sense/config.yml to turn the background watcher off.

Performance

Sense disappears into your workflow. Queries resolve in milliseconds, so your AI reasons about structure without ever stalling.

OperationMeasured (p50 / p95)
Graph query0.2ms / 3ms
Blast radius0.1ms / 10ms
Conventions16ms / 16ms
Cold start48ms
Full scan4.9s
Incremental scan2.3s

Measured on Sense's own codebase (382 files, 4,032 symbols). Run sense benchmark on your project for local numbers.

What Sense Is Not

  • Not a code editor or modifier. Read-only is the identity, not a limitation. Sense observes your codebase. It never modifies it. Your editor, your agent, your tools stay in control.
  • Not a token optimizer. Token savings are a side effect of understanding, not the goal. If LLM costs dropped to zero tomorrow, Sense would still be valuable.
  • Not a search engine. Code search by meaning is one of four tools, not the product. The product is structural understanding.
  • Not a feature-count competitor. Four tools is a choice, not a constraint. Your AI doesn't need 102 tools to choose from. It needs a few that work.
  • Not dependent on anything. No API keys. No Ollama. No Docker. No Python. One binary, zero external dependencies.

Supported Platforms

PlatformStatus
Linux amd64Supported
Linux arm64Supported
macOS Apple Silicon (arm64)Supported
macOS Intel (amd64)Supported (legacy)
WindowsSupported using WSL2

Windows native builds are not yet available. Use WSL2 with the Linux binary.

macOS Intel still ships a binary and works, but it requires macOS 10.15 (Catalina) or later and is pinned to an older bundled runtime (ONNX Runtime 1.23.1) because Microsoft dropped macOS x86_64 runtime builds after that version. That dependency is frozen and cannot advance, so Apple Silicon is the recommended Mac target.

Requirements

  • ~60 MB disk for the binary
  • 100-200 MB for the .sense/ index (varies with project size)

Language Support

Sense uses tree-sitter for parsing. It ships with extractors for 13 languages across two tiers:

Full tier. Symbols, calls, inheritance, imports, blast radius, semantic search, and framework-specific inference:

LanguageFramework support
RubyRails (associations, callbacks, routes), Stimulus, Turbo
TypeScript / JavaScriptReact (JSX component calls)
Go-
ERBStimulus, Turbo (cross-language edges to JS controllers)

Standard tier. Symbols, calls, inheritance, imports, blast radius, and semantic search:

LanguageNotes
PythonDjango (models, URL patterns), FastAPI (routes, Depends)
RustStructs, traits, enums, impl blocks
JavaClasses, interfaces, enums, records
KotlinClasses, interfaces, objects
C#Classes, interfaces, structs, namespaces
C++Classes, structs, namespaces (:: scoping)
CFunctions, structs, enums
PHPClasses, interfaces, traits (\ scoping)
ScalaClasses, traits, objects

Java, Kotlin, C#, C++, C, PHP, and Scala use a table-driven generic extractor, each ~25 lines of config rather than a handwritten walker. Python and Rust have dedicated extractors, and Python adds Django and FastAPI inference. See CONTRIBUTING-A-LANGUAGE.md to add a new language, and CONTRIBUTING-A-FRAMEWORK.md to add framework support (plus the dead-code fine-graining that goes with it).

Feedback

File issues at github.com/luuuc/sense/issues.

Development

make build    # build the binary
make test     # run tests
make lint     # run linters
make ci       # all of the above

Contributing

Sense is feature-complete for v1. Outside contributions are accepted in three areas: new languages and frameworks, dead-code fine-graining for a language or framework, and AI-tool integrations. Bug fixes are always welcome; net-new features are not. The full scope and step-by-step guides are in CONTRIBUTING.md:

License

MIT. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados