Andrey Kumanyaev
5f565b5ea2
Codex discovers hooks in a hooks.json as well as in inline [hooks] tables in config.toml, and merges the two when both are in the same layer. The inspection behind `gortex doctor` read only config.toml, so a machine whose hooks are configured in hooks.json was reported as having none — and pointed at `gortex install`, which would have written a second declaration of the hooks it already had. Inspect now reads both user-level files and reports a per-file breakdown alongside the merged count, so a zero can no longer be read as "nothing anywhere": doctor prints the files the counts came from, and the doc comment states what is out of scope (the repo layer, which would make the answer depend on the directory doctor ran in). The breakdown is load-bearing rather than cosmetic. The uninstall preview asks for the count in config.toml specifically, because that is the only file removal rewrites and listing it for entries that live elsewhere would promise a deletion that never happens. Doctor also warns when the two files declare the same event, which nothing else on the machine reports except a Codex startup warning nobody attributes to the installer. The unit there is the event, not the file: splitting different events across the two files is a valid configuration and only an event present in both is merged into two runs, so a warning keyed on the files would tell such a user to delete working hooks. The remedy names the file the installer does NOT rewrite, because cleaning the managed one looks like it worked and comes back on the next install. `gortex install` and `gortex init --hooks-only` say the same thing at the moment they would create the duplicate, per configuration layer; both still write their own representation, because the hooks.json entries are the user's and not ours to edit. Also reads `[features] hooks`, the mirror-image defect: hooks that are declared and switched off were diagnosed as untrusted, sending the user through an approval flow that could not have helped. It is reported whether or not anything is configured — installing hooks into a harness that will not run them is no better — and it suppresses the silence rules that would otherwise hand out the trust remedy, including the per-event one, which fires on runs recorded before the switch was flipped.
High-performance and efficient code-intelligence engine for AI agents and IDE
Indexes code into graph and exposes it via CLI, MCP Server, and web UI. Multi-repository support by default.
Single static binary for macOS, Linux, and Windows — no dependency chain, simple installation and use.
High-quality parsing 257 languages/grammars through tree-sitter AST analysis, in-process resolvers, enhanced with compiler-grade resolution for Python, TypeScript / JavaScript, PHP, C#, Go, C, C++, Java, Kotlin, Swift, Zig, Rust, Ruby, Elixir, Ocaml, Haskell, and others - producing a persistent provenance-tiered knowledge graph of functions, classes, call chains, HTTP routes, and cross-service contracts and calls with a strong confidence model. 175 (configurable) MCP tools - use only what you need. Zero dependencies. Plug and play across 19 coding agents. Up to 50× fewer tokens per response. Reproducible benchmarks.
19 AI coding agents (Claude Code, Kiro, Cursor, Windsurf, VS Code / Copilot, Continue.dev, Cline, OpenCode, Antigravity, Codex CLI, Gemini CLI, Zed, Aider, Kilo Code, OpenClaw, Hermes, Oh My Pi, Pi, Kimi) supported out of the box.
One install configures every one detected on your machine — see docs/agents.md.
Gortex Web UI — force-directed knowledge graph visualization
Why it matters
- 50× fewer tokens per response — graph-native lookups beat naive file reads. Agents read just what they need, not the full file, not the 500-line file around it.
- Full development cycle - no 'read file before edit'. Agents ask for sources, tell what to change, and don't waste context of reading noise.
- 257 languages/grammars - every file in the repository reachable; no mix of tools and bloating/hallycinating agents. Three tiers (bespoke tree-sitter, regex, forest-backed signatures) plus Jupyter and Databricks notebooks → docs/languages.md
- Cross-repo by default — N repos in one graph; contracts, references, and call chains span repo boundaries with evidence-gated resolution, contract matching, impact analysis, per-session isolation → docs/multi-repo.md
- Extreamly fast analysis — a precomputed depth-3 reach index turns blast-radius queries into O(seeds × reach) map lookups. Safe to ask "what breaks if I change this?" on every edit. No dozens of tool calls to grasp context.
- Zero external dependencies — single binary, everything in-process. No network, no model download to get started. Install, start daemon, use.
- Agent integrations (20) —
gortex initconfigures every detected coding assistant on the machine → docs/agents.md - 100+ MCP tools, 16 resources, 3 prompts — symbol lookup, call chains, blast radius, dataflow, clone detection, refactoring, code actions → docs/mcp.md
- Semantic search default-on — baked GloVe-50d (3.8 MB embedded), store-native FTS5/BM25 + vector with adaptive alpha fusion, zero deps; opt-in MiniLM / Ollama / OpenAI → docs/semantic-search.md
- Speculative execution —
preview_edit/simulate_chainanswer "what would change if I applied this WorkspaceEdit?" without touching disk - Live editor overlays — push unsaved buffers as a shadow graph; tools read through it. Branching for parallel speculative sessions
- GCX1 wire format — published, round-trippable. An additional −27% tokens vs JSON at same fidelity → docs/wire-format.md
- Long-living daemon — one process serves every IDE window; live fsnotify, an on-disk SQLite graph store, incremental restart, OS-supervised lifecycle
- 9 LLM providers (optional) — local llama.cpp, Anthropic, OpenAI, Ollama, Claude / Codex CLI subprocess, Gemini, Bedrock, DeepSeek → docs/llm.md
- Composable safety —
verify_change,check_guards,audit_agent_configflag broken callers, guard violations, stale docs before they ship - PR review, end to end —
gortex prstriages open PRs (per-PR blast radius, merge-order conflicts via shared communities, AI-ranked queue, reviewer suggestions);gortex reviewemits line-anchored findings with a BLOCK/REVIEW/APPROVE verdict from a graph-grounded rulepack; MCP tools (pr_risk,get_pr_impact,review,review_pack,post_review, …) expose it to agents → docs/cli.md - HTTP server + Web UI — versioned
/v1/*API + MCP 2026 Streamable HTTP; standalone Next.js 15 UI with five 3D graph modes → docs/server.md - Telemetry off by default — opt-in anonymous tool/command counts only (no code, paths, names, or exact counts); nothing transmitted unless you configure an endpoint.
gortex telemetry on|off|status; honoursDO_NOT_TRACK→ docs/telemetry.md
Full catalog of features: docs/features.md. Complete CLI reference: docs/cli.md.
Install
# macOS / Linux
curl -fsSL https://get.gortex.dev | sh
# Windows (PowerShell)
irm https://get.gortex.dev/install.ps1 | iex
Detects OS/arch, verifies SHA256 + cosign, installs to PATH. Re-run to upgrade. Homebrew, .deb / .rpm / .apk, scoop, signed binaries, and from-source builds: docs/installation.md.
Quick Start
gortex install # one-time machine setup (MCP, skills, slash commands)
gortex daemon start --detach # background daemon
gortex track ~/projects/myapp # add a repo
cd ~/projects/myapp && gortex init # per-repo: .mcp.json, hooks, community routing
Your AI assistant now uses graph queries. Full 15-minute walkthrough: docs/onboarding.md.
Cross-Repo API Contracts
Gortex auto-detects API contracts across repos and matches providers to consumers, surfaced via the contracts MCP tool and the web UI Contracts page.
| Contract type | Detection | Provider | Consumer |
|---|---|---|---|
| HTTP routes | Framework annotations (gin, Express, FastAPI, Spring, …) | Route handler | HTTP client calls (fetch, http.Get) |
| gRPC | Proto service definitions | Service RPC | Client stub calls |
| GraphQL | Schema type/field definitions | Schema | Query/mutation strings |
| Message topics | Kafka / RabbitMQ / NATS / Redis pub/sub | Publish calls | Subscribe calls |
| WebSocket | Event emit/listen patterns | emit() |
on() |
| Env vars | os.Getenv, process.env, .env files |
Setenv / .env |
Getenv / process.env |
| OpenAPI | Swagger / OpenAPI spec files | Spec paths | (linked to HTTP routes) |
| Temporal workflows | Go / Java SDK annotations | Activity / workflow function | ExecuteActivity / ExecuteChildWorkflow |
Contracts are normalised to canonical IDs (e.g. http::GET::/api/users/{id}) and matched across repos to detect orphan providers / consumers and mismatches. See docs/contracts.md.
Scale — battle-tested on large repos
Measured on an Apple Silicon laptop with the default CGO build.
| Repository | Files | Nodes | Edges | Index time | Throughput | Peak heap |
|---|---|---|---|---|---|---|
| torvalds/linux | 70,333 | 1,690,174 | 6,239,570 | ~3 min | 300 files/s | 5.07 GB |
| microsoft/vscode | 10,762 | 204,501 | 808,902 | ~1 min | 143 files/s | 580 MB |
| zzet/gortex (self) | 430 | 5,583 | 53,830 | 3.4s | 127 files/s | 52 MB |
Parsing dominates wall time (65–80 %); reference resolution and search-index build scale sub-linearly.
Token savings dashboard
gortex savings reports tokens saved vs naive file reads — per-call, per-session, and cumulative across restarts, priced in USD against the headline model.
Gortex Token Savings
====================
Cost avoided: $168.69 (claude-opus-4) across 1,878 calls · 11,246,094 tokens saved
Today ████████░░░░░░░░ 50.0% saved 9,200 / 18,400 tokens $0.14
Last 7 days ██████████░░░░░░ 62.5% saved 60,100 / 96,200 tokens $0.90
All time ███████████████░ 93.3% saved 11,246,094 / 12,050,716 tokens $168.69
--verbose adds the per-tool breakdown; --json is machine-readable. Full reference: docs/savings.md.
Architecture
gortex binary
CLI (cobra) ──> MultiIndexer ──> Graph store (SQLite, shared, per-repo indexed)
MCP (stdio) ──────────────────> Query Engine (repo/project/ref scoping)
HTTP /v1/* ──────────────────> same tools + /v1/graph + /v1/events (SSE)
Daemon (unix) ──────────────────> shared graph for every MCP client, session isolation
MultiWatcher <── filesystem events (fsnotify, per-repo)
CrossRepoResolver ──> cross-repo edge creation (type-aware)
Persistence ──> the same SQLite store, written as it indexes
Data flow, graph schema (node and edge kinds, multi-repo fields, test taxonomy), persistence model: docs/architecture.md.
Documentation
| Topic | Reference |
|---|---|
| First-time walkthrough | onboarding.md |
| Installation & supply-chain verification | installation.md |
| Full feature catalog | features.md |
| CLI reference | cli.md |
| MCP tools, resources, prompts | mcp.md |
| Multi-repo workspaces | multi-repo.md |
| HTTP server + Web UI + MCP 2026 transport | server.md |
| Cross-repo API contracts | contracts.md |
| Semantic search | semantic-search.md |
| Optional LLM features | llm.md |
| LSP integration | lsp.md |
| Per-community skills & agent usage | skills.md |
| AI agent adapters (20) | agents.md |
| Supported languages (257) | languages.md |
| Token savings | savings.md |
| GCX1 wire format | wire-format.md |
| Architecture & graph schema | architecture.md |
| Evaluation methodology | 04-evaluation/ |
| Telemetry & privacy | telemetry.md |
| Versioning policy | versioning.md |
Building from source
make build # binary with version stamping
make test # go test -race ./...
make lint # golangci-lint
Requires Go 1.26+ and CGO (for tree-sitter C bindings).
License
Apache License 2.0. See LICENSE.md. Copyright 2024-2026 Andrey Kumanyaev me@zzet.org.
Contributing
See CONTRIBUTING.md for guidelines on adding features, language extractors, and submitting PRs.
New contributors are very welcome — join us on Discord and introduce yourself. It's the easiest place to ask questions, check whether someone is already working on something, and get feedback on a design before you write the code.