Gkg

Global Knowledge Graph (GKG)

Overview

GKG provides semantic code analysis tools for exploring and understanding codebases. It indexes projects to enable fast symbol lookup, reference finding, and structural analysis.

Quick Start

Run from the opencode config directory (required for dependencies). Use --raw with JSON for parameters:

cd /home/hazeruno/.config/opencode && bun skills/gkg/scripts/gkg.ts <command> --raw '<json>'

Core Commands

list-projects

List all indexed projects in the knowledge graph.

cd /home/hazeruno/.config/opencode && bun skills/gkg/scripts/gkg.ts list-projects

index-project

Rebuild the knowledge graph index for a project.

cd /home/hazeruno/.config/opencode && bun skills/gkg/scripts/gkg.ts index-project \
  --raw '{"project_absolute_path":"/path/to/project"}'

search-codebase-definitions

Find functions, classes, methods, constants across the codebase.

cd /home/hazeruno/.config/opencode && bun skills/gkg/scripts/gkg.ts search-codebase-definitions \
  --raw '{"search_terms":["functionName","ClassName"],"project_absolute_path":"/path/to/project"}'

get-references

Find all usages of a symbol across the codebase.

cd /home/hazeruno/.config/opencode && bun skills/gkg/scripts/gkg.ts get-references \
  --raw '{"absolute_file_path":"/path/to/file.ts","definition_name":"myFunction"}'

read-definitions

Read complete implementation of definitions.

cd /home/hazeruno/.config/opencode && bun skills/gkg/scripts/gkg.ts read-definitions \
  --raw '{"definitions":[{"names":["myFunc"],"file_path":"/path/to/file.ts"}]}'

get-definition

Go to definition for a symbol on a specific line.

cd /home/hazeruno/.config/opencode && bun skills/gkg/scripts/gkg.ts get-definition \
  --raw '{"absolute_file_path":"/path/to/file.ts","line":"const result = myFunc()","symbol_name":"myFunc"}'

repo-map

Generate a compact API-style map of repository structure.

cd /home/hazeruno/.config/opencode && bun skills/gkg/scripts/gkg.ts repo-map \
  --raw '{"project_absolute_path":"/path/to/project","relative_paths":["src","lib"]}'

import-usage

Analyze import usages across the project.

cd /home/hazeruno/.config/opencode && bun skills/gkg/scripts/gkg.ts import-usage \
  --raw '{"project_absolute_path":"/path/to/project","packages":[{"import_path":"react"}]}'

Common Workflows

Refactoring Impact Analysis

1. Use search-codebase-definitions to find the symbol
2. Use get-references to find all usages
3. Review each usage location before making changes

Understanding Unfamiliar Code

1. Use repo-map to get project structure overview
2. Use search-codebase-definitions to find relevant functions
3. Use read-definitions to read implementations

Tracing Dependencies

1. Use import-usage to find where packages are imported
2. Use get-references to trace function call chains

Resources

scripts/

• gkg.ts - CLI tool for all knowledge graph operations

references/

• api_reference.md - Detailed parameter documentation for each command