CodeTide

CodeTide is a fully local, privacy-preserving tool for parsing and understanding Python codebases using symbolic, structural analysis. No internet, no LLMs, no embeddings - just fast, explainable, and deterministic code intelligence.

✅ Key Features

✅ 100% local & private - all parsing and querying happens on your machine.
📦 Structured parsing of codebases using Tree-sitter.
🧠 Retrieval of relevant code snippets by symbolic ID - not vector similarity.
🧱 Visualize the architecture and hierarchy of your project.
⚡ Fast, cacheable parsing with smart update detection.
🔁 Designed to work alongside tools like Copilot, GPT, and Claude - on your terms.

🔌 VSCode Extension

CodeTide is available as a native Visual Studio Code extension, giving you direct access to structural code understanding inside your editor.

Navigate code intelligently
Retrieve context-aware snippets
Send context directly to LLMs like Copilot or GPT
Works seamlessly with any other extensions

🔗 Install it now: CodeTide on VSCode Marketplace
🔧 Extension source code: CodeTide VSCode Extension on GitHub

🖧 CodeTide as an MCP Server

CodeTide now supports acting as an MCP Server, enabling seamless integration with AI agents and tools. This feature allows agents to dynamically interact with your codebase and retrieve context efficiently.

To enable CodeTide as an MCP server in your environment, add the following entry to your servers configuration file:

{
  "mcpServers": {
    "codetide": {
      "command": "uvx",
      "args": [
        "--from",
        "codetide",
        "codetide-mcp-server"
      ],
      "env": {
        "CODETIDE_WORKSPACE": "./"
      }
    }
  }
}

Why This Helps Agents

Agents working with codebases often need:

Contextual Understanding: Retrieve declarations, imports, and references for any part of the code.
Tool Integration: Use built-in tools to navigate and analyze code.

Available Tools

CodeTide provides the following tools for agents:

getContext: Retrieve code context for identifiers (e.g., functions, classes).
getRepoTree: Explore the repository structure.

Example: Initializing an LLM with CodeTide

Here’s a snippet from agent_tide.py demonstrating how to initialize an LLM with CodeTide as an MCP server:

from aicore.llm import Llm, LlmConfig
from codetide.mcp import codeTideMCPServer
import os

def init_llm() -> Llm:
    llm = Llm.from_config(
        LlmConfig(
            model="deepseek-chat",
            provider="deepseek",
            temperature=0,
            api_key=os.getenv("DEEPSEEK-API-KEY")
        )
    )
    llm.provider.mcp.add_server(name=codeTideMCPServer.name, parameters=codeTideMCPServer)
    return llm

This setup allows the LLM to leverage CodeTide’s tools for codebase interactions.

CodeTide can now be used as an MCP Server! This allows seamless integration with AI tools and workflows. Below are the tools available: The available tools are:

getContext: Retrieve code context for identifiers.
getRepoTree: Generate a visual tree representation of the repository.

⚙️ Installation

📦 From PyPI

pip install codetide --upgrade

🛠️ From Source

git clone https://github.com/BrunoV21/CodeTide.git
cd CodeTide
pip install -e .

🚀 Example: Running CodeTide on Itself

Here's how to parse the CodeTide repository and extract a snippet from the Python parser:

from codetide import CodeTide
from codetide.core.common import writeFile
from dotenv import load_dotenv
import asyncio
import time
import os

async def main():
    st = time.time()
    tide = await CodeTide.from_path(os.getenv("CODETIDE_REPO_PATH"))
    tide.serialize(include_cached_ids=True)
    output = tide.get(["codetide.parsers.python_parser.PythonParser"], degree=1, as_string=True)

    writeFile(output, "./storage/context.txt")
    print(f"took {time.time()-st:.2f}s")

if __name__ == "__main__":
    load_dotenv()
    asyncio.run(main())

This example:

Parses the codebase using Tree-sitter
Serializes the result for fast reuse
Retrieves a specific class with full local context

Here's how to deserialize a CodeTide repository and reuse it:

from codetide import CodeTide
from codetide.core.common import writeFile
from dotenv import load_dotenv
import asyncio
import time
import os

async def main():
    st = time.time()
    tide = CodeTide.deserialize(rootpath=os.getenv("CODETIDE_REPO_PATH"))
    tide.codebase._build_cached_elements()
    await tide.check_for_updates(include_cached_ids=True)
    output = tide.get(["codetide.parsers.python_parser.PythonParser"], degree=2, as_string=True)

    writeFile(output, "./storage/context.txt")
    print(f"took {time.time()-st:.2f}s")

if __name__ == "__main__":
    load_dotenv()
    asyncio.run(main())

This example:

Deserializes the previously serialized CodeTide
Checks for updates to the codebase
Retrieves a specific class with full local context (up to second degree connections)

Here's how to levarage CodeTide's tree view functionalites to get a broad picture of your project:

from codetide import CodeTide
from dotenv import load_dotenv
import time
import os

def main():
    st = time.time()
    tide = CodeTide.deserialize(rootpath=os.getenv("CODETIDE_REPO_PATH"))

    modules_tree_view = tide.codebase.get_tree_view(include_modules=True)
    print(modules_tree_view)
    
    print(f"took {time.time()-st:.2f}s")

if __name__ == "__main__":
    load_dotenv()
    asyncio.run(main())

Output:

├── codetide
│   ├── core
│   │   ├── common.py
│   │   │   ├── CONTEXT_INTRUCTION
│   │   │   ├── TARGET_INSTRUCTION
│   │   │   ├── readFile
│   │   │   ├── wrap_content
│   │   │   ├── wrap_package_dependencies   
│   │   │   └── writeFile
│   │   ├── defaults.py
│   │   │   ├── DEFAULT_BATCH_SIZE
│   │   │   ├── DEFAULT_CACHED_ELEMENTS_FILE
│   │   │   ├── DEFAULT_CACHED_IDS_FILE     
│   │   │   ├── DEFAULT_ENCODING
│   │   │   ├── DEFAULT_MAX_CONCURRENT_TASKS
│   │   │   ├── DEFAULT_SERIALIZATION_PATH
│   │   │   ├── INSTALLATION_DIR
│   │   │   └── LANGUAGE_EXTENSIONS
│   │   ├── html.py
│   │   │   └── render_html_view
│   │   ├── mermaid.py
│   │   │   ├── _render_class_contents
│   │   │   ├── _render_file_contents
│   │   │   ├── _render_mermaid_node
│   │   │   ├── _safe_mermaid_id
│   │   │   ├── save_mermaid_to_html_file
│   │   │   └── to_mermaid_boxy_flowchart
│   │   └── models.py
│   │       ├── BaseCodeElement
│   │       │   ├── file_path
│   │       │   ├── raw
│   │       │   ├── stored_unique_id
│   │       │   ├── apply_second_line_indent_to_first
│   │       │   ├── file_path_without_suffix
│   │       │   ├── unique_id
│   │       │   └── unique_id
│   │       ├── ClassAttribute
│   │       │   ├── class_id
│   │       │   └── visibility
│   │       ├── ClassDefinition
│   │       │   ├── attributes
│   │       │   ├── bases
│   │       │   ├── bases_references
│   │       │   ├── methods
│   │       │   ├── name
│   │       │   ├── add_attribute
│   │       │   ├── add_method
│   │       │   ├── all_methods_ids
│   │       │   └── references
│   │       ├── CodeBase
│   │       │   ├── _cached_elements
│   │       │   ├── root
│   │       │   ├── _build_cached_elements
│   │       │   ├── _build_tree_dict
│   │       │   ├── _list_all_unique_ids_for_property
│   │       │   ├── _render_class_contents
│   │       │   ├── _render_file_contents
│   │       │   ├── _render_tree_node
│   │       │   ├── all_classes
│   │       │   ├── all_functions
│   │       │   ├── all_imports
│   │       │   ├── all_variables
│   │       │   ├── deserialize_cache_elements
│   │       │   ├── get
│   │       │   ├── get_import
│   │       │   ├── get_tree_view
│   │       │   ├── serialize_cache_elements
│   │       │   └── unique_ids
│   │       ├── CodeContextStructure
│   │       │   ├── _cached_elements
│   │       │   ├── _unique_class_elements_ids
│   │       │   ├── class_attributes
│   │       │   ├── class_methods
│   │       │   ├── classes
│   │       │   ├── functions
│   │       │   ├── imports
│   │       │   ├── preloaded
│   │       │   ├── requested_elements
│   │       │   ├── variables
│   │       │   ├── add_class
│   │       │   ├── add_class_attribute
│   │       │   ├── add_class_method
│   │       │   ├── add_function
│   │       │   ├── add_import
│   │       │   ├── add_preloaded
│   │       │   ├── add_variable
│   │       │   ├── as_list_str
│   │       │   └── from_list_of_elements
│   │       ├── CodeFileModel
│   │       │   ├── classes
│   │       │   ├── file_path
│   │       │   ├── functions
│   │       │   ├── imports
│   │       │   ├── raw
│   │       │   ├── variables
│   │       │   ├── _list_all
│   │       │   ├── add_class
│   │       │   ├── add_function
│   │       │   ├── add_import
│   │       │   ├── add_variable
│   │       │   ├── all_classes
│   │       │   ├── all_functions
│   │       │   ├── all_imports
│   │       │   ├── all_variables
│   │       │   ├── get
│   │       │   ├── get_import
│   │       │   └── list_raw_contents
│   │       ├── CodeReference
│   │       │   ├── name
│   │       │   └── unique_id
│   │       ├── FunctionDefinition
│   │       │   ├── decorators
│   │       │   ├── modifiers
│   │       │   ├── name
│   │       │   ├── references
│   │       │   └── signature
│   │       ├── FunctionSignature
│   │       │   ├── parameters
│   │       │   └── return_type
│   │       ├── ImportStatement
│   │       │   ├── alias
│   │       │   ├── definition_id
│   │       │   ├── import_type
│   │       │   ├── name
│   │       │   ├── raw
│   │       │   ├── source
│   │       │   └── as_dependency
│   │       ├── MethodDefinition
│   │       │   └── class_id
│   │       ├── Parameter
│   │       │   ├── default_value
│   │       │   ├── name
│   │       │   ├── type_hint
│   │       │   └── is_optional
│   │       ├── PartialClasses
│   │       │   ├── attributes
│   │       │   ├── class_header
│   │       │   ├── class_id
│   │       │   ├── filepath
│   │       │   ├── methods
│   │       │   └── raw
│   │       └── VariableDeclaration
│   │           ├── modifiers
│   │           ├── name
│   │           ├── raw
│   │           ├── references
│   │           ├── type_hint
│   │           └── value
│   ├── parsers
│   │   ├── base_parser.py
│   │   │   └── BaseParser
│   │   │       ├── extension
│   │   │       ├── import_statement_template
│   │   │       ├── language
│   │   │       ├── parse_file
│   │   │       ├── resolve_inter_files_dependencies
│   │   │       ├── resolve_intra_file_dependencies
│   │   │       └── tree_parser
│   │   ├── generic_parser.py
│   │   │   └── GenericParser
│   │   │       ├── _filepath
│   │   │       ├── extension
│   │   │       ├── import_statement_template
│   │   │       ├── language
│   │   │       ├── parse_code
│   │   │       ├── parse_file
│   │   │       ├── resolve_inter_files_dependencies
│   │   │       ├── resolve_intra_file_dependencies
│   │   │       └── tree_parser
│   │   └── python_parser.py
│   │       └── PythonParser
│   │           ├── _filepath
│   │           ├── _tree_parser
│   │           ├── _default_unique_import_id
│   │           ├── _find_elements_references
│   │           ├── _find_references
│   │           ├── _generate_unique_import_id
│   │           ├── _get_content
│   │           ├── _get_element_count
│   │           ├── _process_aliased_import
│   │           ├── _process_assignment
│   │           ├── _process_block
│   │           ├── _process_class_node
│   │           ├── _process_decorated_definition
│   │           ├── _process_expression_statement
│   │           ├── _process_function_definition
│   │           ├── _process_import_node
│   │           ├── _process_node
│   │           ├── _process_parameters
│   │           ├── _process_type_parameter
│   │           ├── _skip_init_paths
│   │           ├── count_occurences_in_code
│   │           ├── extension
│   │           ├── filepath
│   │           ├── filepath
│   │           ├── import_statement_template
│   │           ├── init_tree_parser
│   │           ├── language
│   │           ├── parse_code
│   │           ├── parse_file
│   │           ├── resolve_inter_files_dependencies
│   │           ├── resolve_intra_file_dependencies
│   │           ├── tree_parser
│   │           └── tree_parser
│   └── autocomplete.py
│       └── AutoComplete
│           ├── __init__
│           ├── get_fuzzy_suggestions
│           └── get_suggestions
├── examples
│   ├── parse_codetide.py
│   │   └── main
│   └── parse_project.py
│       └── main
└── setup.py
    ├── here
    ├── long_description
    ├── requirements
    └── requirements_visualization

🧠 Philosophy

CodeTide is about giving developers structure-aware tools that are fast, predictable, and private. Your code is parsed, navigated, and queried as a symbolic graph - not treated as a black box of tokens. Whether you’re building, refactoring, or feeding context into an LLM - you stay in control.

Like a tide, your codebase evolves - and CodeTide helps you move with it, intelligently.

❌ What CodeTide Does Not Use

To be clear, CodeTide does not rely on:

❌ Large Language Models (LLMs)
❌ Embedding models or token similarity
❌ Vector databases or search indexes
❌ External APIs or cloud services

Instead, it uses:

✅ Tree-sitter for lightweight, fast, and accurate parsing
✅ Deterministic logic and symbolic references to navigate your codebase

🗺️ Roadmap

Here’s what’s next for CodeTide:

🧩 Support more languages already integrated with Tree-sitter
→ TypeScript is the top priority. Now available in Beta

- 🧭 Handle relative imports in Python projects
→ Improve resolution for intra-package navigation.

🤖 Agents Module: AgentTide

CodeTide now includes an agents module, featuring AgentTide—a precision-driven software engineering agent that connects directly to your codebase and executes your requests with full code context.

AgentTide leverages CodeTide’s symbolic code understanding to:

Retrieve and reason about relevant code context for any request
Generate atomic, high-precision patches using strict protocols
Apply changes directly to your codebase, with robust validation

Where to Find It

Source: codetide/agents/tide/agent.py

What It Does

AgentTide acts as an autonomous agent that:

Connects to your codebase using CodeTide’s parsing and context tools
Interacts with users via a conversational interface
Identifies relevant files, classes, and functions for any request
Generates and applies diff-style patches, ensuring code quality and requirements fidelity

Example Usage

To use AgentTide, ensure you have the aicore package installed (pip install codetide[agents]), then instantiate and run the agent:

from codetide import CodeTide
from codetide.agents.tide.agent import AgentTide
from aicore.llm import Llm, LlmConfig
import os, asyncio

async def main():
    tide = await CodeTide.from_path("/path/to/your/repo")
    llm = Llm.from_config(
        LlmConfig(
            model="deepseek-chat",
            provider="deepseek",
            temperature=0,
            api_key=os.getenv("DEEPSEEK-API-KEY")
        )
    )
    agent = AgentTide(llm=llm, tide=tide)
    await agent.run()

if __name__ == "__main__":
    asyncio.run(main())

AgentTide will prompt you for requests, retrieve the relevant code context, and generate precise patches to fulfill your requirements.

Disclaimer: AgentTide is designed for focused, context-aware code editing, not for generating entire applications from vague ideas. While CodeTide as a platform can support larger workflows, the current version of AgentTide is optimized for making precise, well-scoped changes. For best results, provide one clear request at a time. AgentTide does not yet have access to your terminal or the ability to execute commands, but support for test-based validation is planned in future updates.

For more details, see the agents module source code.

📄 License

CodeTide is licensed under the Apache 2.0 License.

🧑‍💻 Contributing

Interested in contributing to CodeTide? We welcome contributions of all kinds - especially new language parsers!

If you'd like to add support for a new language (e.g., Rust, Java, Go), see our CONTRIBUTING.md guide. You'll implement your parser by extending our BaseParser interface and providing robust test coverage. Reference implementations are available for Python and TypeScript in the tests/parsers directory.

Name		Name	Last commit message	Last commit date
Latest commit History 387 Commits
.github		.github
codetide		codetide
docs/assets		docs/assets
examples		examples
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFIEST.in		MANIFIEST.in
README.md		README.md
pyproject.toml		pyproject.toml
requirements-agents.txt		requirements-agents.txt
requirements-visualization.txt		requirements-visualization.txt
requirements.txt		requirements.txt
setup.py		setup.py
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

CodeTide

✅ Key Features

🔌 VSCode Extension

🖧 CodeTide as an MCP Server

Why This Helps Agents

Available Tools

Example: Initializing an LLM with CodeTide

⚙️ Installation

📦 From PyPI

🛠️ From Source

🚀 Example: Running CodeTide on Itself

🧠 Philosophy

❌ What CodeTide Does Not Use

🗺️ Roadmap

🤖 Agents Module: AgentTide

Where to Find It

What It Does

Example Usage

📄 License

🧑‍💻 Contributing

About

Uh oh!

Releases 8

Packages

Uh oh!

Languages

License

BrunoV21/CodeTide

Folders and files

Latest commit

History

Repository files navigation

CodeTide

✅ Key Features

🔌 VSCode Extension

🖧 CodeTide as an MCP Server

Why This Helps Agents

Available Tools

Example: Initializing an LLM with CodeTide

⚙️ Installation

📦 From PyPI

🛠️ From Source

🚀 Example: Running CodeTide on Itself

🧠 Philosophy

❌ What CodeTide Does Not Use

🗺️ Roadmap

🤖 Agents Module: AgentTide

Where to Find It

What It Does

Example Usage

📄 License

🧑‍💻 Contributing

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Languages

Packages