How zeeeepa/graph-sitter works
Project type and purpose
• This is a full-stack, scriptable code-manipulation platform (“Graph-sitter”) implemented in Python.
• It exposes:
• A core library (src/graph_sitter) for parsing codebases into ASTs and graphs.
• A suite of CLI tools (src/graph_sitter/cli, src/gscli, src/contexten/cli) for codemods, codegen, LSP, notebooks, etc.
• A codemod framework (src/codemods) with canonical and eval modules.
• An agent/extension layer (src/contexten, src/graph_sitter/extensions) for integrating with AI agents, GitHub, Slack, Linear, Modal, SWEbench.
• Build and packaging (Dockerfile, pyproject.toml, GitHub Actions workflows).
File structure
• Top-level “src” splits into:
• graph_sitter (core parsing, codebase graph, Cython extensions, configs, types, visitor patterns).
• codemods (framework for writing and evaluating code transforms).
• contexten (AI-agent orchestration, CLI commands, API clients, auth).
• gscli (global CLI wrapper).
• gsbuild (packaging/build entrypoint).
• “docs” and “examples” illustrate API usage and full-stack examples (frontend + backend).
• “tests” covers unit and integration tests for CLI, core, SDK, codemods, agents, extensions.
• CI/CD defined in .github/workflows and scripts for linting, type-checking, testing, releasing.
README for additional insights
• Describes primary abstractions: Codebase, Agent, Task.
• Highlights dependencies: Tree-sitter (parsing), rustworkx (graph algorithms).
• Shows usage patterns: instantiate Codebase, traverse functions, perform edits, run an AI agent via REST.
Main components
a. Frontend/CLI layer
• gs (global entrypoint)
• graph-sitter CLI commands (init, create, run, lsp, notebook)
• contexten CLI (agent, create, deploy, run, serve)
b. Agent/API layer
• Agent class (src/contexten/agents)
• REST API client (modal.run base_url)
c. Core processing engine
• File discovery & parsing (Tree-sitter bindings in src/graph_sitter/tree_sitter_parser.py)
• AST & graph construction (codebase, multigraph, rustworkx)
• Semantic analyses (type analysis, import/export resolution)
• Transactions & edits (transaction_manager, codemod runner)
• Incremental recomputation sub-system
d. Extensions & plugins
• Language plugins (python, typescript, core/plugins)
• External integrations (GitHub, Slack, Linear, Modal, SWEbench)
• LSP server & protocol handler
e. I/O & external dependencies
• File system I/O
• Cython-compiled modules (src/graph_sitter/compiled)
• Config management (hatch.toml, pyproject.toml, configs models)
• Docker environment & UV toolchain
Relationships and interactions
• CLI → Core: invokes parsing, codebase build, codemod runner
• Agent → REST API → Core: submits tasks, polls status
• Core → Tree-sitter & rustworkx: builds ASTs and graphs
• Core → Extensions: dispatches language-specific or third-party plugins
• Codemod framework → Core: uses AST & graph to apply transforms
• Tests & CI → CLI/Core: validate behavior, perform integration scenarios
Architectural patterns and design principles
• Layered architecture: CLI/Agent → Core → Extensions → I/O
• Plugin/extension pattern for languages & external services
• Modular separation of concerns (parsing, analysis, edits, API)
• Incremental computation graph for performance
• Cython extension for critical performance paths
Technologies, frameworks & libraries
• Python 3.12+
• Tree-sitter (parsing)
• rustworkx (graph algorithms)
• Cython (compiled performance modules)
• Click or Typer (CLI – implied)
• Docker & UV (toolchain)
• GitHub Actions (CI/CD)
Final recommendations
• Heavy-weight modules (Cython compiled, rustworkx) to show performance boundaries