Onboarding
& reference.

Two commands per machine, two per repo. Runs natively on macOS, Linux and Windows, amd64 and arm64. Setup is split between a user-level install (once per machine) and a per-repo init (once per repo) — codebase-agnostic stuff lives in ~/.claude/, ~/.gemini/, etc., so it isn't duplicated into every repo.

Install the binary.

The installer detects your OS and arch, downloads the signed release archive, verifies SHA256 against checksums.txt (and cosign if installed), installs the binary, and puts it on your PATH. Re-runs upgrade in place. No silent sudo.

# preferred — one line, signed (macOS / Linux)
$ curl -fsSL https://get.gortex.dev | sh

# windows (powershell)
$ irm https://get.gortex.dev/install.ps1 | iex

# homebrew · scoop (windows)
$ brew install zzet/tap/gortex
$ scoop install gortex

# package managers (linux)
$ apt install ./gortex_amd64.deb
$ dnf install ./gortex_amd64.rpm
$ apk add --allow-untrusted ./gortex_amd64.apk

# go install (CGO required for tree-sitter)
$ go install github.com/zzet/gortex/cmd/gortex@latest

$gortex install

One-time machine setup. Writes user-level MCP wiring + skills + slash commands so they aren't duplicated into every repo.

$ gortex install                      # interactive-free
$ gortex install --start --track     # also spawn the daemon and track cwd
$ gortex install --no-hooks          # skip user-level hook installation

Files written:

• ~/.claude.json — MCP server config for Claude Code
• ~/.claude/skills/gortex-* — 19 model-invoked tool-usage skills
• ~/.claude/commands/gortex-*.md — 19 slash commands (discovery · refactor · review)
• ~/.claude/agents/gortex-*.md — 2 sub-agents (gortex-search, gortex-impact) with a graph-only tool allowlist
• ~/.gemini/antigravity/ — Knowledge Items
• (optional) user-level Claude Code hooks

Wire up your repo.

Per-repo init detects every coding agent in scope and writes the right config. It also generates per-community SKILL.md files so Claude Code can auto-route to the right cluster of code.

$ cd ~/projects/myapp
$ gortex init                             # writes .mcp.json, CLAUDE.md, hooks
$ gortex init --analyze                   # also index first for a richer CLAUDE.md
$ gortex init --no-skills                 # skip community-routing generation
$ gortex init --skills-min-size 5 --skills-max 10
$ gortex init --hooks-only                # (re)install repo-local hooks only
$ gortex init --no-hooks                  # full init, skip hooks

Files written per repo:

• .mcp.json — workspace MCP wiring
• .claude/settings.json + settings.local.json
• CLAUDE.md — codebase overview + community routing
• .claude/skills/generated/ — per-community SKILL.md
• marker-guarded community block in every other detected agent's instruction file (AGENTS.md, .windsurfrules, GEMINI.md, .cursor/rules/gortex-communities.mdc, etc.)

Pick a deployment shape.

Same binary, three modes. mcp for one editor over stdio. server for an HTTP API. daemon for one shared graph across every editor window.

# Run the MCP server standalone (auto-detects daemon via stdio)
$ gortex mcp --index /path/to/repo --watch
$ gortex mcp --no-daemon --watch          # explicit embedded mode

# HTTP API on :4747
$ gortex server --index .
$ gortex server --auth-token "$GORTEX_SERVER_TOKEN"

# Daemon lifecycle
$ gortex daemon start --detach          # spawn in background
$ gortex daemon status                  # PID, uptime, memory, tracked repos, sessions
$ gortex daemon stop                    # graceful shutdown + final snapshot
$ gortex daemon restart
$ gortex daemon reload                  # re-read config, pick up new/removed repos
$ gortex daemon logs -n 50

# Auto-start at login (launchd on macOS, systemd --user on Linux)
$ gortex daemon install-service
$ gortex daemon service-status
$ gortex daemon uninstall-service

# Expose the MCP 2026 Streamable HTTP transport on the daemon
$ gortex daemon start --http-addr 127.0.0.1:7411 --http-auth-token "$TOK"

Global config + per-repo config.

Gortex uses a two-tier config: a global file at ~/.config/gortex/config.yaml for projects and the repo roster, and a per-repo .gortex.yaml for guards, excludes, and local overrides.

~/.config/gortex/config.yaml

projects:
  api:
    repos:
      - path: ~/projects/api-server
        workspace: api
      - path: ~/projects/api-client
        workspace: api
  infra:
    repos:
      - path: ~/projects/terraform
active_project: api
daemon:
  socket: ~/.gortex/server.sock
  log_file: ~/.gortex/daemon.log

./.gortex.yaml

workspace: api           # the hard graph boundary for cross-repo work
project:   api           # optional sub-bucket inside workspace
excludes:
  - "vendor/**"
  - "node_modules/**"
  - "**/*.generated.go"
guards:
  - name: no-internal-from-external
    kind: boundary
    deny: { from: "pkg/**", to: "internal/**" }
  - name: handler-tests-must-co-change
    kind: co-change
    paths: ["handlers/*.go", "handlers/*_test.go"]

One graph. Many repos.

Every node and contract is keyed on a workspace slug — the hard graph boundary for cross-repo work. Two repos that should pair their contracts (an HTTP server and the client that calls it, a Kafka producer and its consumer) must declare the same workspace: in their .gortex.yaml. Otherwise contract matching stops at the boundary and they look like orphans.

Slug resolution precedence

1. RepoEntry.workspace in ~/.config/gortex/config.yaml — overrides everything. Ideal for OSS / read-only repos where you don't want to leave an artifact in the tree.
2. workspace: in the repo's own .gortex.yaml — the default for first-party repos.
3. The repo prefix — fallback when neither is set, so each unconfigured repo gets its own isolated workspace.

Track / untrack

$ gortex track ~/projects/backend
$ gortex track ~/projects/frontend --workspace api
$ gortex untrack backend

# List every tracked repo — head SHA, last-indexed time, staleness flag
$ gortex repos
$ gortex repos --json

# Per-repo status + daemon-wide status share the same command — it picks
$ gortex status

Multi-server roster

Let the daemon route to additional Gortex servers (local sockets or remote HTTPS).

$ gortex daemon server list
$ gortex daemon server add work --url https://gortex.work.example --auth-token-env WORK_TOK
$ gortex daemon server remove work

On gortex server, the --workspace and --scope-project flags filter both indexing and queries. gortex server --workspace api only loads repos that resolve to api; a typo'd value errors out at startup rather than producing an empty graph.

Workspace + project slugs

Manage workspace assignments without hand-editing every .gortex.yaml.

$ gortex workspace list                                # show what each tracked repo declares
$ gortex workspace set backend api                     # write workspace=api to backend's .gortex.yaml
$ gortex workspace set upstream-lib api --global       # OSS-friendly: pin in ~/.config/gortex/config.yaml
$ gortex workspace set-all api --root ~/projects/work --yes

Excludes — the layered ignore list

The effective exclude list is layered (builtin → the repo's own .gitignore → global → repo entry → workspace). The repo's .gitignore is respected by default — opt out per-workspace with respect_gitignore: false. The walk also honors per-directory .gortexignore and ripgrep's .ignore / .rgignore. Each layer reports its source so you know where a rule came from.

$ gortex config exclude list                          # show all layers with provenance
$ gortex config exclude add pkg/generated             # default target: workspace .gortex.yaml
$ gortex config exclude add '**/*.bak' --global       # write to ~/.config/gortex/config.yaml
$ gortex config exclude add testdata/ --repo backend  # write to a RepoEntry
$ gortex config exclude remove pkg/generated

Auto-detected. Auto-wired.

Run gortex init and Gortex auto-detects every coding agent in scope, then writes the right config files. See docs/agents.md for the full adapter matrix and per-agent schema notes.

The hooks that quietly do the right thing.

Gortex installs four Claude Code hooks (and equivalents for other agents that support them). Each one degrades silently when the server is unreachable.

Every subcommand at a glance.

Setup

Run

Operate

Round-trippable compact text instead of JSON.

17 list-shaped MCP tools accept format: "gcx" on input — and known clients (Claude Code, Cursor, VS Code, Zed, Aider, Kilo Code, OpenCode, OpenClaw, Codex) get it served by default. Returns a published, round-trippable text format instead of JSON. format: "toon" is the second-tier fallback (~10–15% smaller than JSON, lossy but human-friendly) for clients that don't yet speak GCX.

• Median −27.4% savings vs JSON (tiktoken cl100k_base) · −27.3% under Claude Opus 4.7 · best case −38.3% · 100% round-trip integrity
• Tools that support it: search_symbols, find_usages, analyze, contracts, batch_symbols, get_callers, get_call_chain, get_dependencies, get_dependents, find_implementations, find_overrides, get_class_hierarchy, get_file_summary, get_editing_context, smart_context, flow_between, find_clones
• Spec: docs/wire-format.md
• Reproducible bench harness: bench/wire-format/

Standalone reference implementations (MIT)

• github.com/gortexhq/gcx-go — Go decoder/encoder
• github.com/gortexhq/gcx-ts — TypeScript, npm @gortex/wire

# In your tool call
smart_context({ task: "refactor watcher", format: "gcx" })

# Decoding in Go
$ go get github.com/gortexhq/gcx-go

# Decoding in TS
$ npm install @gortex/wire

Sigstore-signed. SLSA Level 3.

Every release is keyless-signed with cosign, attested with SLSA-3 build provenance, and tracked by OpenSSF Scorecard. VirusTotal: 0/91. The installer verifies SHA256 against checksums.txt by default; if cosign is on your $PATH, it also verifies the cosign signature.

# Manual verification
$ cosign verify-blob \
    --certificate-identity-regexp "https://github.com/zzet/gortex/.github/workflows/release.yml" \
    --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
    --signature gortex_darwin_arm64.tar.gz.sig \
    --certificate gortex_darwin_arm64.tar.gz.pem \
    gortex_darwin_arm64.tar.gz

# SLSA provenance
$ slsa-verifier verify-artifact \
    --provenance-path multiple.intoto.jsonl \
    --source-uri github.com/zzet/gortex \
    gortex_darwin_arm64.tar.gz

Full instructions: docs/installation.md#verifying-releases.

Where to read more.

The deepest docs live in the repo and ship with each release. They are versioned with the binary, so main always matches the build you'd download today.