Andrey Kumanyaev
275780299a
A tool call is bounded by a transport deadline; when it fires, boundHandler
answers the client and lets the handler keep running. agents.AtomicWriteFile
takes no context, so a handler that had already reached its rename committed to
disk anyway — and the caller was told only "the work may still complete in the
background, so treat any side effect as unknown".
That single message covered two opposite outcomes. A client reading it as
"nothing happened" retried, or fell back to its own editor, and applied the same
logical change twice.
Split the two states and make both observable:
- Every disk commit registers in a durable ledger BEFORE the write and is
stamped terminal immediately after it, so a receipt exists for any mutation
that is still reachable.
- commitFileMutation adds a cancellation gate between registration and the
write. Stopping there is a guarantee that nothing was written, not a guess;
the remaining window is one atomic rename wide and is covered by an
in_flight receipt.
- The abandoned-call error now reports what actually landed — committed with
path and new_sha, not_applied, or genuinely unknown — plus a machine-readable
mutation_commit={...} tail. Read tools keep the original wording.
- Edit responses carry disk_status and graph_status as independent fields:
bytes reaching disk and the graph catching up are different questions with
different failure modes.
- mutation_status (facade: change/receipt) queries a receipt by id,
mutation_id, or path for 30 minutes, refreshing a still-pending graph state
rather than answering from a stale snapshot.
- edit_file / write_file / edit_symbol take an optional mutation_id
idempotency key, mirroring batch_edit's transaction_id: the same key with the
identical edit replays the original result instead of writing twice, and a
different edit under the same key is refused.
rename_symbol and the batch symbol/file edits register in the same ledger; a
coordinated rename now stops at its first cancelled write instead of attempting
every remaining file.
The agent preset's tools/list ceiling is re-based 28200 -> 28400 for the
mutation_id parameter on the two edit tools (148 bytes measured); the preset
itself did not grow.
Fixes #548
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.