← Portfolio/free-code

free-code

Code Graph — local symbol index and call-graph navigation.

What is the code graph?

A local, queryable map of every symbol and call edge in your codebase.

The code graph indexes every TypeScript and JavaScript file in your project. It extracts all symbols — functions, classes, methods, interfaces, types, variables, enums — and records which symbol calls which. The result is stored in .code-graph/ at the project root as a set of compact JSON files.

The agent reads the index in milliseconds. Instead of blindly opening files to find a function definition, it asks the code graph. Instead of grepping for callers, it queries the call edges. The index gives the agent a structural understanding of your project from the very first query.

What it indexes

  • Functions (top-level and nested)
  • Classes and their methods
  • Interfaces, type aliases, enums
  • Variables and constants
  • Call edges between symbols (who calls whom)
  • Import edges (which file imports which)

Supported languages

LanguageExtensionsSymbols
TypeScript / JavaScript .ts .tsx .js .jsx .mts .cts .mjs .cjs functions, classes, methods, interfaces, types, enums, variables
Python .py classes, functions, methods, module-level variables
Java .java classes, interfaces, enums, methods (incl. abstract)

TypeScript and JavaScript are parsed with the TypeScript compiler API. Python (indentation-based) and Java (brace-based) use lightweight heuristic extractors — no extra dependencies, no build toolchain.

Incremental by default
Only files that have changed since the last index run are re-parsed. On a large project, incremental updates take a fraction of a second.

Watch: Code Graph in free-code

See the symbol index and call-graph navigation in action.

How it works

From source files to a structural index the agent can query.

  1. Parse. Each source file is parsed into a syntax tree. free-code walks the tree and records every symbol declaration with its kind, file path, and start/end line.
  2. Resolve edges. Call expressions become call edges (symbol → name) and import statements become import edges (file → file). Together these form the graph.
  3. Hash & store. Each file is hashed so the next run can skip anything unchanged. Symbols, edges, hashes, and run metadata are written to .code-graph/ as JSON.
  4. Query. The agent (or you, via slash commands) reads the JSON directly — no language server, no compilation, no network. Lookups are near-instant.
One index per repository
The graph lives next to the code it describes, at the root of each repo. Open a different project and free-code uses that project's own .code-graph/.

Why it's a standout feature

Structural understanding that is local, fast, and free.

Fewer wasted tokens

Without a code graph, an agent finds a function by reading whole files into its context — burning tokens on code it doesn't need. The code graph returns just the symbol and its callees, so prompts stay small and iterations stay fast.

Real impact analysis

Before changing a function, ask the graph who calls it. /codeGraph-callers turns a guess (“is this used anywhere?”) into a concrete list of call sites — the foundation for safe refactors.

Local and private

The index never leaves your machine. No cloud indexing of your repository, no upload of your source. It is just JSON files under your project root that you can inspect, diff, or delete at any time.

Zero-config and instant

No language server to configure, no build step, no daemon. Indexing is incremental and stale files are refreshed automatically in the background when a session starts.

Agent tools

Four tools available automatically in every session once @free/code-graph is installed.

ToolDescription
code_index Build or incrementally update the project index. Accepts an optional force flag to re-parse all files from scratch.
code_symbols Case-insensitive substring search by name or qualified name. Accepts an optional kind filter: function · class · method · interface · type · variable · enum.
code_callers Returns every call site that invokes a named symbol, with file path and line number. Useful for impact analysis and refactor planning.
code_context Returns the full source of a symbol plus its direct callees. Validates that the file has not changed since the last index run; warns if stale.

Commands you can run on any repository

The same four slash commands work in every project you open with free-code.

Each repository gets its own code graph. Open a project, build the index once, and these commands operate against that repo's symbols and call edges:

CommandWhat it does
/codeGraph-index Build or update the repository's index.
/codeGraph-symbols Search the repository's symbols by name.
/codeGraph-callers List every call site of a function or method in the repository.
/codeGraph-context Print a symbol's full source plus its direct callees.
Per-project, automatically
There is nothing to point at a repo — free-code reads and writes the .code-graph/ folder at the root of whichever project the session is running in.

Using the commands

Run code graph operations directly from the editor input.

/codeGraph-index [--force]

Indexes the project and writes the result to .code-graph/. Without --force, only changed files are re-indexed. 

/codeGraph-index           # incremental — only changed files
/codeGraph-index --force   # re-index everything from scratch

When to run: once after cloning, and with --force after large refactors. Day-to-day, stale files are re-indexed automatically in the background on session startup.

/codeGraph-symbols <query> [--kind <type>] [--limit <n>]

Searches for symbols whose name or qualified name contains the query string (case-insensitive, substring match). 

/codeGraph-symbols parseArgs
/codeGraph-symbols handle --kind function
/codeGraph-symbols User --kind class --limit 10
KindMatches
functionTop-level and nested functions
classClass declarations
methodClass methods
interfaceInterface declarations
typeType aliases
variableVariables and constants
enumEnum declarations

/codeGraph-callers <name> [--limit <n>]

Finds all locations in the codebase that call a function or method by name. Returns file path, line number, and the enclosing symbol for each call site. 

/codeGraph-callers syncDefaultExtensions
/codeGraph-callers render --limit 20
Note on common names
Names like save, render, or init may match callers from unrelated classes. Use /codeGraph-context to inspect a caller before trusting the result.

/codeGraph-context <name> [--file <partial-path>]

Returns the full source of a symbol and a list of its direct callees. Validates that the file has not been modified since the last index. 

/codeGraph-context createAgentSessionServices
/codeGraph-context load --file resource-loader

When multiple symbols share the same name, use --file to pick the right one by matching a partial file path.

Typical workflow

How to use the code graph in a real session.

Starting on a new project

/codeGraph-index                     # 1. Index the project once

/codeGraph-symbols parseArgs         # 2. Find a symbol by name
/codeGraph-callers parseArgs         # 3. See everywhere it is called
/codeGraph-context parseArgs         # 4. Read its full source + callees

After a large refactor

/codeGraph-index --force             # Re-index all files from scratch

Automatic background re-indexing

On session startup, free-code checks whether any indexed source files (.ts / .js / .py / .java and friends) have been modified since the last index. If so, it automatically re-indexes in the background — no manual action needed. You will see two notifications: 

⚠️ Code graph index is stale: 5 file(s) modified since last index. Re-indexing in background…

✓ Code graph updated: 3 file(s) re-indexed in 420ms

The re-index is incremental (only changed files). Use /codeGraph-index --force after large refactors to re-parse everything from scratch.

Installation

The code graph is a separate package installed once at the global level.

# From the repository root
npm install -g ./packages/code-graph

Once installed, the four code graph tools (code_index, code_symbols, code_callers, code_context) and their /codeGraph-* slash commands appear automatically in every free-code session. No configuration needed.

Generated files

The index is stored in .code-graph/ at the project root.

.code-graph/
  meta.json      # timestamp of the last index run and aggregate stats
  files.json     # indexed files with hashes and mtimes
  symbols.json   # all symbols: name, kind, file, start/end line
  edges.json     # call edges: from symbol → to name
Add to .gitignore
The index is regenerated on demand and does not need to be committed. Add .code-graph/ to your .gitignore.

All capabilities →  ·  Commands →  ·  Installation →

Developed by Pablo Castañeda