Codebase

This class provides the main entrypoint for most programs to analyzing and manipulating codebases. It provides a high-level interface to interact with the codebase graph, and provides methods to access and manipulate files, directories, symbols, and other entities in the codebase.

View Source on Github

Attributes

classes

list[ Class ]

List of all Classes in the codebase.

console

Console

current_commit

GitCommit | None

Returns the current Git commit that is checked out in the repository.

default_branch

str

The default branch of this repository.

directories

list[ Directory ]

List all directories in the codebase.

external_modules

list[ ExternalModule ]

Returns a list of all external modules in the codebase.

functions

list[ Function ]

List of all Functions in the codebase.

global_vars

list[ Assignment ]

List of all GlobalVars in the codebase.

imports

list[ Import ]

Returns a list of all Import nodes in the codebase.

interfaces

list[TInterface]

Retrieves all interfaces in the codebase.

language

ProgrammingLanguage

The programming language of the repository.

name

str

The name of the repository.

repo_path

Path

symbols

list[ Symbol ]

List of all top-level Symbols (Classes, Functions, etc.) in the codebase. Excludes Class

types

list[ TypeAlias ]

List of all Types in the codebase (Typescript only).

viz

VisualizationManager

Methods

ai

Generates a response from the AI based on the provided prompt, target, and context.

View Source on Github

Parameters

prompt

str

required

The text prompt to send to the AI.

target

Editable | None

default:None

An optional editable object (like a function, class, etc.) that provides the main focus for the AI's response.

context

Editable | list[ Editable ] | dict[str, Editable | list[ Editable ]] | None

default:None

Additional context to help inform the AI's response.

model

str

default:"gpt-4o"

The AI model to use for generating the response. Defaults to "gpt-4o".

Returns

str

The generated response from the AI.

checkout

Checks out a git branch or commit and syncs the codebase graph to the new state.

View Source on Github

Parameters

commit

str | GitCommit | None

default:None

Hash or GitCommit object to checkout. Cannot be used with branch.

branch

str | None

default:None

Name of branch to checkout. Cannot be used with commit.

create_if_missing

bool

default:False

If True, creates the branch if it doesn't exist. Defaults to False.

remote

bool

default:False

If True, attempts to pull from remote when checking out branch. Defaults to False.

Returns

CheckoutResult

The result of the checkout operation.

commit

Commits all staged changes to the codebase graph and synchronizes the graph with the filesystem if specified.

View Source on Github

Parameters

sync_graph

bool

default:True

Whether to synchronize the graph after committing changes. Defaults to True.

Returns

None

create_directory

Creates a directory at the specified path.

View Source on Github

Parameters

dir_path

str

required

The path where the directory should be created.

exist_ok

bool

default:False

If True, don't raise an error if the directory already exists. Defaults to False.

parents

bool

default:False

If True, create any necessary parent directories. Defaults to False.

Returns

None

create_file

Creates a new file in the codebase with specified content.

View Source on Github

Parameters

filepath

str

required

The path where the file should be created.

content

str

default:""

The content of the file to be created. Defaults to empty string.

sync

bool

default:True

Whether to sync the graph after creating the file. Defaults to True.

Returns

File

The newly created file object.

files

A list property that returns all files in the codebase.

View Source on Github

Returns

list[ SourceFile ] | list[ File ]

A sorted list of source files in the codebase.

find_by_span

Finds editable objects that overlap with the given source code span.

View Source on Github

Parameters

span

Span

required

The span object containing the filepath and byte range to search within.

Returns

list[ Editable ]

A list of Editable objects that overlap with the given span.

from_repo

Fetches a codebase from GitHub and returns a Codebase instance.

View Source on Github

Parameters

repo_name

str

required

The name of the repository in format "owner/repo"

tmp_dir

Optional[str]

default:None

The directory to clone the repo into. Defaults to /tmp/codegen

commit

Optional[str]

default:None

The specific commit hash to clone. Defaults to HEAD

shallow

bool

default:True

Whether to do a shallow clone. Defaults to True

Returns

Codebase

A Codebase instance initialized with the cloned repository

get_class

Returns a class that matches the given name.

View Source on Github

Parameters

class_name

str

required

The name of the class to find.

optional

bool

default:False

If True, return None when class is not found instead of raising ValueError. Defaults to False.

Returns

Class | None

The class with the given name, or None if optional=True and class not found.

get_directory

Returns Directory by dir_path, or full path to the directory from codebase root.

View Source on Github

Parameters

dir_path

str

required

The path to the directory to retrieve.

optional

bool

default:False

If True, return None when directory is not found. If False, raise ValueError.

Returns

Directory | None

The Directory object if found, None if optional=True and directory not found.

get_file

Retrieves a file from the codebase by its filepath.

View Source on Github

Parameters

filepath

str

required

The path to the file, relative to the codebase root.

optional

bool

default:False

If True, return None if file not found. If False, raise ValueError.

ignore_case

bool

default:False

If True, ignore case when checking for file existence. Defaults to False.

Returns

SourceFile | None

The source file if found, None if optional=True and file not found.

get_function

Retrieves a function from the codebase by its name.

View Source on Github

Parameters

function_name

str

required

The name of the function to retrieve.

optional

bool

default:False

If True, returns None when function is not found instead of raising ValueError.

Returns

Function | None

The matching function if found. If optional=True and no match is found, returns None.

get_relative_path

Calculates a relative path from one file to another, removing the extension from the target file.

View Source on Github

Parameters

from_file

str

required

The file path from which the relative path will be computed.

to_file

str

required

The file path (whose extension will be removed) to which the relative path will be computed.

Returns

str

The relative path from `from_file` to `to_file` (with the extension removed from `to_file`).

get_symbol

Returns a Symbol by name from the codebase.

View Source on Github

Parameters

symbol_name

str

required

The name of the symbol to find.

optional

bool

default:False

If True, returns None when symbol is not found. If False, raises ValueError. Defaults to False.

Returns

Symbol | None

The matched Symbol if found, None if not found and optional=True.

get_symbols

Retrieves all symbols in the codebase that match the given symbol name.

View Source on Github

Parameters

symbol_name

str

required

The name of the symbols to retrieve.

Returns

list[ Symbol ]

A list of Symbol objects that match the given name, sorted alphabetically.

git_commit

Commits all staged changes to the codebase and git.

View Source on Github

Parameters

message

str

required

The commit message

verify

bool

default:False

Whether to verify the commit before committing. Defaults to False.

Returns

GitCommit | None

The commit object if changes were committed, None otherwise.

has_directory

Returns a boolean indicating if a directory exists in the codebase.

View Source on Github

Parameters

dir_path

str

required

The path to the directory to check for, relative to the codebase root.

Returns

bool

True if the directory exists in the codebase, False otherwise.

has_file

Determines if a file exists in the codebase.

View Source on Github

Parameters

filepath

str

required

The filepath to check for existence.

ignore_case

bool

default:False

If True, ignore case when checking for file existence. Defaults to False.

Returns

bool

True if the file exists in the codebase, False otherwise.

has_symbol

Returns whether a symbol exists in the codebase.

View Source on Github

Parameters

symbol_name

str

required

The name of the symbol to look for.

Returns

bool

True if a symbol with the given name exists in the codebase, False otherwise.

reset

Resets the codebase by

View Source on Github

Returns

None

set_ai_key

Sets the OpenAI key for the current Codebase instance.

View Source on Github

Returns

None

set_session_options

Sets the Session options for the current codebase.

View Source on Github

Returns

None

should_fix

Returns True if the flag should be fixed based on the current mode and active group.

View Source on Github

Parameters

flag

CodeFlag

required

The code flag to check.

Returns

bool

True if the flag should be fixed, False if it should be ignored. Returns False in find mode. Returns True if no active group is set. Returns True if the flag's hash exists in the active group hashes.

visualize

Visualizes a NetworkX graph or Plotly figure.

View Source on Github

Parameters

G

Graph | go.Figure

required

A NetworkX graph or Plotly figure to visualize

root

Editable | str | int | None

default:None

The root node to visualize around. When specified, the visualization will be centered on this node. Defaults to None.

Returns

None