Onboarding
& reference.

Two commands per machine, two per repo. Runs on macOS and Linux, amd64 and arm64. Windows support is planned. 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 tarball, verifies SHA256 against checksums.txt (and cosign if installed), drops the binary in $HOME/.local/bin, and adds it to your shell rc. Re-runs upgrade in place. No silent sudo.

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

# homebrew
$ brew install zzet/tap/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-* — tool-usage skills
• ~/.claude/commands/gortex-*.md — slash commands
• ~/.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

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

# 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 composed of four layers (builtin → global → repo entry → workspace). 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 three 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.

13 list-shaped MCP tools accept format: "gcx" on input. Returns a published, round-trippable text format instead of JSON.

• Median −27.4% tiktoken savings vs JSON · 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, get_file_summary, get_editing_context, smart_context
• 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.