Pre-release

This release is a pre-release and may not be stable for production use.

OpenTrace

Index any codebase into a knowledge graph — then query it with AI via MCP.

OpenTrace parses source code with tree-sitter, extracts classes, functions, imports, and call relationships, and stores the result in an embedded graph database. The graph is queryable through a built-in MCP server, so tools like Claude Code can search, traverse, and understand your codebase structure.

Install

pip install opentraceai

Or run directly with uv:

uvx opentraceai index .

Requires Python 3.12+.

Quick Start

1. Index a codebase

opentraceai index /path/to/repo

This parses every supported file, extracts symbols and relationships, and writes the graph to .opentrace/index.db.

$ opentraceai index ~/projects/myapp
Opening database at .opentrace/index.db ...
Indexing /home/user/projects/myapp ...
  1284 nodes, 3421 relationships, 187 files, 95 classes, 412 functions
Done in 4.2s.

2. Query via MCP

Start a stdio MCP server against the indexed database:

opentraceai mcp

The database is auto-discovered by walking up from the current directory to the git root, looking for .opentrace/index.db. You can override with --db <path>.

Claude Code

Add OpenTrace to Claude Code as a plugin, or configure it manually in your project's .mcp.json:

{
  "mcpServers": {
    "opentrace": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opentraceai", "mcp"]
    }
  }
}

MCP Tools

Tool	Description
`search_graph`	Full-text search across nodes by name or properties
`list_nodes`	List nodes by type (Class, Function, File, etc.)
`get_node`	Get a node's full details and immediate neighbors
`traverse_graph`	Walk relationships from a node (outgoing, incoming, or both)
`get_stats`	Graph statistics — node/edge counts broken down by type

Supported Languages

Full extraction (symbols + calls + imports)	Structural extraction (symbols only)
Python, TypeScript/JavaScript, Go	Rust, Java, Kotlin, C#, C/C++, Ruby, Swift

Config and data files (JSON, YAML, TOML, Protobuf, SQL, GraphQL, Bash) are indexed as file nodes.

CLI Reference

`opentraceai index [PATH]`

Index a local codebase into a LadybugDB knowledge graph.

Option	Default	Description
`PATH`	`.`	Directory to index
`--db`	`.opentrace/index.db`	Database path
`--repo-id`	directory name	Repository identifier
`--batch-size`	`200`	Items per write batch
`-v, --verbose`	off	Debug logging

`opentraceai mcp`

Start a stdio MCP server exposing graph query tools.

Option	Default	Description
`--db`	auto-discovered	Database path
`-v, --verbose`	off	Debug logging

`opentraceai stats`

Display graph statistics (node/edge counts by type).

Option	Default	Description
`--db`	auto-discovered	Database path
`--output`	`text`	Output format (`text` or `json`)

`opentraceai serve`

Start an HTTP server exposing the graph database as a REST API.

Option	Default	Description
`--db`	auto-discovered	Database path
`--host`	`127.0.0.1`	Bind address
`--port`	`8787`	Bind port
`-v, --verbose`	off	Debug logging

`opentraceai query QUERY_STRING`

Run a Cypher or full-text search query against the graph database.

Option	Default	Description
`--db`	auto-discovered	Database path
`-t, --type`	`cypher`	Query language (`cypher` or `fts`)
`--limit`	`100`	Max rows (FTS only)
`--output`	`table`	Output format (`table`, `json`, or `jsonl`)

`opentraceai export [OUTPUT]`

Export the graph database as a .parquet.zip archive.

`opentraceai import ARCHIVE`

Import a .parquet.zip archive into the graph database.

`opentraceai impact FILE_PATH`

Analyze the blast radius of changes to a file.

`opentraceai config`

Read or write project configuration (.opentrace/config.yaml). Subcommands: set, get, show, path.

`opentraceai login` / `logout` / `whoami` / `refresh`

Authenticate with api.opentrace.ai.

Development

uv sync          # Install dependencies
uv run pytest    # Run tests
uv run ruff check src/ tests/   # Lint
uv run ruff format src/ tests/  # Format

Part of OpenTrace

This package is the CLI/MCP component of OpenTrace, an open-source platform for mapping system architecture into knowledge graphs. The full project also includes a browser-based graph explorer at oss.opentrace.ai.

License

Apache License 2.0

Release files for opentraceai 0.4.0.dev2964

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for opentraceai 0.4.0.dev2964
File	Size	Uploaded
opentraceai-0.4.0.dev2964.tar.gz	244.0 kB	Apr 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for opentraceai 0.4.0.dev2964
File	Interpreter	ABI	Platform	Reset
opentraceai-0.4.0.dev2964-py3-none-any.whl 124.7 kB Apr 14, 2026	Python 3	none	any	Details

Total release size: 368.7 kB

Release files / opentraceai-0.4.0.dev2964.tar.gz

Download URL	opentraceai-0.4.0.dev2964.tar.gz
Size	244.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`bb91435170678969f0f8a795ff447396449f54755e57bb8a248aeabdf10d0166`
BLAKE2b-256 checksum How to use checksums	`cfbfd8bc74d3096d0a1ec515c80e8671c845cf0090146a6ecda82a562aeace87`
Upload date	Apr 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/opentrace/opentrace
Publishing commit: github.com/opentrace/opentrace/tree/34dca6f85c562ac412a89b4a2f2be8d9aff8317c

Workflow

Publishing configuration: github.com/opentrace/opentrace/blob/34dca6f85c562ac412a89b4a2f2be8d9aff8317c/.github/workflows/publish-preview.yml
Publishing logs: github.com/opentrace/opentrace/actions/runs/24395263454/attempts/1

Artifact

Subject: opentraceai-0.4.0.dev2964.tar.gz
SHA-256 checksum: bb91435170678969f0f8a795ff447396449f54755e57bb8a248aeabdf10d0166 Verifying attestations

Release files / opentraceai-0.4.0.dev2964-py3-none-any.whl

Download URL	opentraceai-0.4.0.dev2964-py3-none-any.whl
Size	124.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f528c7449e991922fae5f93711ebecae62538b2272bb4f5c326a48e7bec6665f`
BLAKE2b-256 checksum How to use checksums	`c00e51c08f4b60d12a5e140f6ff130d9a07b18dbb159c052ffb7c80d02333ba1`
Upload date	Apr 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/opentrace/opentrace
Publishing commit: github.com/opentrace/opentrace/tree/34dca6f85c562ac412a89b4a2f2be8d9aff8317c

Workflow

Publishing configuration: github.com/opentrace/opentrace/blob/34dca6f85c562ac412a89b4a2f2be8d9aff8317c/.github/workflows/publish-preview.yml
Publishing logs: github.com/opentrace/opentrace/actions/runs/24395263454/attempts/1

Artifact

Subject: opentraceai-0.4.0.dev2964-py3-none-any.whl
SHA-256 checksum: f528c7449e991922fae5f93711ebecae62538b2272bb4f5c326a48e7bec6665f Verifying attestations