From 9c506d0097db501250c1cf6dab8feab05889bed5 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Fri, 7 Nov 2025 14:23:25 +0100 Subject: [PATCH 01/21] Initial setup for jupyterbook build --- docs/.gitignore | 5 + docs/_config.yml | 185 +++++++ docs/autogen_rst.py | 155 ++++++ docs/create_toc.py | 8 + docs/custom_agent.md | 2 +- pyproject.toml | 14 + uv.lock | 1149 +++++++++++++++++++++++++++++++++++++++++- 7 files changed, 1514 insertions(+), 4 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/_config.yml create mode 100644 docs/autogen_rst.py create mode 100644 docs/create_toc.py diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..37fcf551 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,5 @@ +/_toc.yml +/jupyter_execute +/conf.py +/sensai +/build diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 00000000..98a645c1 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,185 @@ +# Book settings +# Learn more at https://jupyterbook.org/customize/config.html + +####################################################################################### +# A default configuration that will be loaded for all jupyter books +# Users are expected to override these values in their own `_config.yml` file. +# This is also the "master list" of all allowed keys and values. + +####################################################################################### +# Book settings +title : Serena Documentation # The title of the book. Will be placed in the left navbar. +author : Oraios AI & Oraios Software # The author of the book +copyright : "2025 by Serena contributors" # Copyright year to be placed in the footer +logo : ../resources/serena-logo.svg # A path to the book logo +# Patterns to skip when building the book. Can be glob-style (e.g. "*skip.ipynb") +exclude_patterns : ['**.ipynb_checkpoints', '.DS_Store', 'Thumbs.db', '_build', 'jupyter_execute', '.jupyter_cache', '.pytest_cache', 'docs/autogen_rst.py', 'docs/create_toc.py'] +# Auto-exclude files not in the toc +only_build_toc_files : true + +####################################################################################### +# Execution settings +execute: + # NOTE: Notebooks are not executed, because test_notebooks.py executes them and stores them with outputs in the docs/ folder + # NOTE: If changed, repeat below in `nb_execution_mode`. + execute_notebooks : "off" # Whether to execute notebooks at build time. Must be one of ("auto", "force", "cache", "off") + cache : "" # A path to the jupyter cache that will be used to store execution artifacts. Defaults to `_build/.jupyter_cache/` + exclude_patterns : [] # A list of patterns to *skip* in execution (e.g. a notebook that takes a really long time) + timeout : 1000 # The maximum time (in seconds) each notebook cell is allowed to run. + run_in_temp : false # If `True`, then a temporary directory will be created and used as the command working directory (cwd), + # otherwise the notebook's parent directory will be the cwd. + allow_errors : true # If `False`, when a code cell raises an error the execution is stopped, otherwise all cells are always run. + stderr_output : show # One of 'show', 'remove', 'remove-warn', 'warn', 'error', 'severe' + +####################################################################################### +# Parse and render settings +parse: + myst_enable_extensions: # default extensions to enable in the myst parser. See https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html + - amsmath + - colon_fence + # - deflist + - dollarmath + # - html_admonition + # - html_image + - linkify + # - replacements + # - smartquotes + - substitution + - tasklist + myst_url_schemes: [ mailto, http, https ] # URI schemes that will be recognised as external URLs in Markdown links + myst_dmath_double_inline: true # Allow display math ($$) within an inline context + +####################################################################################### +# HTML-specific settings +html: + #favicon : "_static/images/tianshou-favicon.png" # A path to a favicon image + use_edit_page_button : false # Whether to add an "edit this page" button to pages. If `true`, repository information in repository: must be filled in + use_repository_button : false # Whether to add a link to your repository button + use_issues_button : false # Whether to add an "open an issue" button + use_multitoc_numbering : true # Continuous numbering across parts/chapters + use_darkmode_button : false + extra_footer : "" + google_analytics_id : "" # A GA id that can be used to track book views. + home_page_in_navbar : true # Whether to include your home page in the left Navigation Bar + baseurl : "https://tianshou.readthedocs.io/en/master/" + analytics: + + comments: + hypothesis : false + utterances : false + announcement : "" # A banner announcement at the top of the site. + +####################################################################################### +# LaTeX-specific settings +latex: + latex_engine : pdflatex # one of 'pdflatex', 'xelatex' (recommended for unicode), 'luatex', 'platex', 'uplatex' + use_jupyterbook_latex : true # use sphinx-jupyterbook-latex for pdf builds as default + targetname : book.tex +# Add a bibtex file so that we can create citations +#bibtex_bibfiles: +# - refs.bib + +####################################################################################### +# Launch button settings +launch_buttons: + notebook_interface : classic # The interface interactive links will activate ["classic", "jupyterlab"] + binderhub_url : "" # The URL of the BinderHub (e.g., https://mybinder.org) + jupyterhub_url : "" # The URL of the JupyterHub (e.g., https://datahub.berkeley.edu) + thebe : false # Add a thebe button to pages (requires the repository to run on Binder) + colab_url : "https://colab.research.google.com" + +repository: + url : https://github.com/thu-ml/tianshou # The URL to your book's repository + path_to_book : docs # A path to your book's folder, relative to the repository root. + branch : master # Which branch of the repository should be used when creating links + +####################################################################################### +# Advanced and power-user settings +sphinx: + extra_extensions : + - sphinx.ext.autodoc + - sphinx.ext.viewcode + - sphinx_toolbox.more_autodoc.sourcelink + #- sphinxcontrib.spelling + local_extensions : # A list of local extensions to load by sphinx specified by "name: path" items + recursive_update : false # A boolean indicating whether to overwrite the Sphinx config (true) or recursively update (false) + config : # key-value pairs to directly over-ride the Sphinx configuration + autodoc_typehints_format: "short" + autodoc_member_order: "bysource" + autoclass_content: "both" + autodoc_mock_imports: + - numpy + - pandas + - torch + - scipy + - sklearn + - seaborn + - matplotlib + - pytorch_lightning + - torchtext + - tensorboard + - lightgbm + - sklearn + - seaborn + - psutil + - pyyaml + - sqlite3 + - azureml + - mlflow + - MySQLdb + - catboost + - xgboost + - clearml + - azure + - geopandas + - shapely + - networkx + - utm + - sklearn_quantile + autodoc_default_options: + show-inheritance: True + html_js_files: +# We have to list them explicitly because they need to be loaded in a specific order + - js/vega@5.js + - js/vega-lite@5.js + - js/vega-embed@5.js + autodoc_show_sourcelink: True + add_module_names: False + github_username: thu-ml + github_repository: tianshou + nb_execution_mode: "off" + nb_merge_streams: True # This is important for cell outputs to appear as single blocks rather than one block per line + python_use_unqualified_type_names: True + nb_mime_priority_overrides: [ + [ 'html', 'application/vnd.jupyter.widget-view+json', 10 ], + [ 'html', 'application/javascript', 20 ], + [ 'html', 'text/html', 30 ], + [ 'html', 'text/latex', 40 ], + [ 'html', 'image/svg+xml', 50 ], + [ 'html', 'image/png', 60 ], + [ 'html', 'image/jpeg', 70 ], + [ 'html', 'text/markdown', 80 ], + [ 'html', 'text/plain', 90 ], + [ 'spelling', 'application/vnd.jupyter.widget-view+json', 10 ], + [ 'spelling', 'application/javascript', 20 ], + [ 'spelling', 'text/html', 30 ], + [ 'spelling', 'text/latex', 40 ], + [ 'spelling', 'image/svg+xml', 50 ], + [ 'spelling', 'image/png', 60 ], + [ 'spelling', 'image/jpeg', 70 ], + [ 'spelling', 'text/markdown', 80 ], + [ 'spelling', 'text/plain', 90 ], + ] + mathjax_path: https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js + mathjax3_config: + loader: { load: [ '[tex]/configmacros' ] } + tex: + packages: { '[+]': [ 'configmacros' ] } + macros: + vect: ["{\\mathbf{\\boldsymbol{#1}} }", 1] + E: "{\\mathbb{E}}" + P: "{\\mathbb{P}}" + R: "{\\mathbb{R}}" + abs: ["{\\left| #1 \\right|}", 1] + simpl: ["{\\Delta^{#1} }", 1] + amax: "{\\text{argmax}}" diff --git a/docs/autogen_rst.py b/docs/autogen_rst.py new file mode 100644 index 00000000..81aa6870 --- /dev/null +++ b/docs/autogen_rst.py @@ -0,0 +1,155 @@ +import logging +import os +import shutil +from pathlib import Path +from typing import Optional, List + +log = logging.getLogger(os.path.basename(__file__)) + +TOP_LEVEL_PACKAGE = "sensai" +PROJECT_NAME = "sensAI" + +def module_template(module_qualname: str): + module_name = module_qualname.split(".")[-1] + title = module_name.replace("_", r"\_") + return f"""{title} +{"=" * len(title)} + +.. automodule:: {module_qualname} + :members: + :undoc-members: +""" + + +def index_template(package_name: str, doc_references: Optional[List[str]] = None, text_prefix=""): + doc_references = doc_references or "" + if doc_references: + doc_references = "\n" + "\n".join(f"* :doc:`{ref}`" for ref in doc_references) + "\n" + + dirname = package_name.split(".")[-1] + title = dirname.replace("_", r"\_") + if title == TOP_LEVEL_PACKAGE: + title = "API Reference" + return f"{title}\n{'=' * len(title)}" + text_prefix + doc_references + + +def write_to_file(content: str, path: str): + os.makedirs(os.path.dirname(path), exist_ok=True) + with open(path, "w") as f: + f.write(content) + os.chmod(path, 0o666) + + +_SUBTITLE = ( + f"\n Here is the autogenerated documentation of the {PROJECT_NAME} API. \n \n " + "The Table of Contents to the left has the same structure as the " + "repository's package code. The links at each page point to the submodules and subpackages. \n" +) + + +def make_rst(src_root, rst_root, clean=False, overwrite=False, package_prefix=""): + """Creates/updates documentation in form of rst files for modules and packages. + + Does not delete any existing rst files. Thus, rst files for packages or modules that have been removed or renamed + should be deleted by hand. + + This method should be executed from the project's top-level directory + + :param src_root: path to library base directory, typically "src/" + :param rst_root: path to the root directory to which .rst files will be written + :param clean: whether to completely clean the target directory beforehand, removing any existing .rst files + :param overwrite: whether to overwrite existing rst files. This should be used with caution as it will delete + all manual changes to documentation files + :package_prefix: a prefix to prepend to each module (for the case where the src_root is not the base package), + which, if not empty, should end with a "." + :return: + """ + rst_root = os.path.abspath(rst_root) + + if clean and os.path.isdir(rst_root): + shutil.rmtree(rst_root) + + base_package_name = package_prefix + os.path.basename(src_root) + + # TODO: reduce duplication with same logic for subpackages below + files_in_dir = os.listdir(src_root) + module_names = [f[:-3] for f in files_in_dir if f.endswith(".py") and not f.startswith("_")] + subdir_refs = [ + f"{f}/index" + for f in files_in_dir + if os.path.isdir(os.path.join(src_root, f)) + and not f.startswith("_") + and not f.startswith(".") + ] + package_index_rst_path = os.path.join( + rst_root, + "index.rst", + ) + log.info(f"Writing {package_index_rst_path}") + write_to_file( + index_template( + base_package_name, + doc_references=module_names + subdir_refs, + text_prefix=_SUBTITLE, + ), + package_index_rst_path, + ) + + for root, dirnames, filenames in os.walk(src_root): + if os.path.basename(root).startswith("_"): + continue + base_package_relpath = os.path.relpath(root, start=src_root) + base_package_qualname = package_prefix + os.path.relpath( + root, + start=os.path.dirname(src_root), + ).replace(os.path.sep, ".") + + for dirname in dirnames: + if dirname.startswith("_"): + log.debug(f"Skipping {dirname}") + continue + files_in_dir = os.listdir(os.path.join(root, dirname)) + module_names = [ + f[:-3] for f in files_in_dir if f.endswith(".py") and not f.startswith("_") + ] + subdir_refs = [ + f"{f}/index" + for f in files_in_dir + if os.path.isdir(os.path.join(root, dirname, f)) and not f.startswith("_") + ] + package_qualname = f"{base_package_qualname}.{dirname}" + package_index_rst_path = os.path.join( + rst_root, + base_package_relpath, + dirname, + "index.rst", + ) + log.info(f"Writing {package_index_rst_path}") + write_to_file( + index_template(package_qualname, doc_references=module_names + subdir_refs), + package_index_rst_path, + ) + + for filename in filenames: + base_name, ext = os.path.splitext(filename) + if ext == ".py" and not filename.startswith("_"): + module_qualname = f"{base_package_qualname}.{filename[:-3]}" + + module_rst_path = os.path.join(rst_root, base_package_relpath, f"{base_name}.rst") + if os.path.exists(module_rst_path) and not overwrite: + log.debug(f"{module_rst_path} already exists, skipping it") + + log.info(f"Writing module documentation to {module_rst_path}") + write_to_file(module_template(module_qualname), module_rst_path) + + +if __name__ == "__main__": + logging.basicConfig(level=logging.INFO) + docs_root = Path(__file__).parent + enable_module_docs = False + if enable_module_docs: + make_rst( + docs_root / ".." / "src" / "serena", + docs_root / "serena", + clean=True, + ) diff --git a/docs/create_toc.py b/docs/create_toc.py new file mode 100644 index 00000000..3e1779cd --- /dev/null +++ b/docs/create_toc.py @@ -0,0 +1,8 @@ +import os +from pathlib import Path + +# This script provides a platform-independent way of making the jupyter-book call (used in pyproject.toml) +toc_file = Path(__file__).parent / "_toc.yml" +cmd = f"jupyter-book toc from-project docs -e .rst -e .md -e .ipynb >{toc_file}" +print(cmd) +os.system(cmd) diff --git a/docs/custom_agent.md b/docs/custom_agent.md index d1d7afde..add268dd 100644 --- a/docs/custom_agent.md +++ b/docs/custom_agent.md @@ -63,5 +63,5 @@ configuration file (`.yml`). It should be straightforward to incorporate Serena into any agent framework (like [pydantic-ai](https://ai.pydantic.dev/), [langgraph](https://langchain-ai.github.io/langgraph/tutorials/introduction/) or others). Typically, you need only to write an adapter for Serena's tools to the tool representation in the framework of your choice, -as was done by us for Agno with [SerenaAgnoToolkit](/src/serena/agno.py). +as was done by us for Agno with `SerenaAgnoToolkit` (see `/src/serena/agno.py`). diff --git a/pyproject.toml b/pyproject.toml index fa207374..ab885a06 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -65,6 +65,12 @@ dev = [ "types-pyyaml>=6.0.12.20241230", "syrupy>=4.9.1", "types-requests>=2.32.4.20241230", + # docs + "sphinx==5.0.2", + "sphinx_rtd_theme>=0.5.1", + "sphinx-toolbox==3.7.0", + "jupyter-book==0.15.1", + "nbsphinx" ] agno = ["agno>=2.2.1", "sqlalchemy>=2.0.40"] google = ["google-genai>=1.8.0"] @@ -123,6 +129,14 @@ lint = ["_black_check", "_ruff_check"] format = ["_ruff_format", "_black_format"] _mypy = "mypy src/serena" type-check = ["_mypy"] +# docs +_autogen_rst = "python docs/autogen_rst.py" +_sphinx_build = "sphinx-build -b html docs docs/_build -W --keep-going" +_jb_generate_toc = "python docs/create_toc.py" +_jb_generate_config = "jupyter-book config sphinx docs/" +doc-clean = "rm -rf docs/_build docs/03_api" +doc-generate-files = ["_autogen_rst", "_jb_generate_toc", "_jb_generate_config"] +doc-build = ["doc-clean", "doc-generate-files", "_sphinx_build"] [tool.ruff] target-version = "py311" diff --git a/uv.lock b/uv.lock index 831c0de8..741ffb7f 100644 --- a/uv.lock +++ b/uv.lock @@ -2,6 +2,18 @@ version = 1 revision = 2 requires-python = "==3.11.*" +[[package]] +name = "accessible-pygments" +version = "0.0.5" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pygments" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/bc/c1/bbac6a50d02774f91572938964c582fff4270eee73ab822a4aeea4d8b11b/accessible_pygments-0.0.5.tar.gz", hash = "sha256:40918d3e6a2b619ad424cb91e556bd3bd8865443d9f22f1dcdf79e33c8046872", size = 1377899, upload-time = "2024-05-10T11:23:10.216Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/8d/3f/95338030883d8c8b91223b4e21744b04d11b161a3ef117295d8241f50ab4/accessible_pygments-0.0.5-py3-none-any.whl", hash = "sha256:88ae3211e68a1d0b011504b2ffc1691feafce124b845bd072ab6f9f66f34d4b7", size = 1395903, upload-time = "2024-05-10T11:23:08.421Z" }, +] + [[package]] name = "agno" version = "2.2.1" @@ -26,6 +38,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/66/d8/315baab7fc66b3cc89db5e3277729e602a09e7d4ac61b2c3498b193833cf/agno-2.2.1-py3-none-any.whl", hash = "sha256:82311b2afc385810913967109dc5cbb4d3ec1c550aaf22741079fc5e67eb878f", size = 1263574, upload-time = "2025-10-23T20:43:47.355Z" }, ] +[[package]] +name = "alabaster" +version = "0.7.16" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/c9/3e/13dd8e5ed9094e734ac430b5d0eb4f2bb001708a8b7856cbf8e084e001ba/alabaster-0.7.16.tar.gz", hash = "sha256:75a8b99c28a5dad50dd7f8ccdd447a121ddb3892da9e53d1ca5cca3106d58d65", size = 23776, upload-time = "2024-01-10T00:56:10.189Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/32/34/d4e1c02d3bee589efb5dfa17f88ea08bdb3e3eac12bc475462aec52ed223/alabaster-0.7.16-py3-none-any.whl", hash = "sha256:b46733c07dce03ae4e150330b975c75737fa60f0a7c591b6c8bf4928a28e2c92", size = 13511, upload-time = "2024-01-10T00:56:08.388Z" }, +] + [[package]] name = "annotated-types" version = "0.7.0" @@ -67,6 +88,43 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/a1/ee/48ca1a7c89ffec8b6a0c5d02b89c305671d5ffd8d3c94acf8b8c408575bb/anyio-4.9.0-py3-none-any.whl", hash = "sha256:9f76d541cad6e36af7beb62e978876f3b41e3e04f2c1fbf0884604c0a9c4d93c", size = 100916, upload-time = "2025-03-17T00:02:52.713Z" }, ] +[[package]] +name = "apeye" +version = "1.4.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "apeye-core" }, + { name = "domdf-python-tools" }, + { name = "platformdirs" }, + { name = "requests" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/4f/6b/cc65e31843d7bfda8313a9dc0c77a21e8580b782adca53c7cb3e511fe023/apeye-1.4.1.tar.gz", hash = "sha256:14ea542fad689e3bfdbda2189a354a4908e90aee4bf84c15ab75d68453d76a36", size = 99219, upload-time = "2023-08-14T15:32:41.381Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/89/7b/2d63664777b3e831ac1b1d8df5bbf0b7c8bee48e57115896080890527b1b/apeye-1.4.1-py3-none-any.whl", hash = "sha256:44e58a9104ec189bf42e76b3a7fe91e2b2879d96d48e9a77e5e32ff699c9204e", size = 107989, upload-time = "2023-08-14T15:32:40.064Z" }, +] + +[[package]] +name = "apeye-core" +version = "1.1.5" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "domdf-python-tools" }, + { name = "idna" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/e5/4c/4f108cfd06923bd897bf992a6ecb6fb122646ee7af94d7f9a64abd071d4c/apeye_core-1.1.5.tar.gz", hash = "sha256:5de72ed3d00cc9b20fea55e54b7ab8f5ef8500eb33a5368bc162a5585e238a55", size = 96511, upload-time = "2024-01-30T17:45:48.727Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/77/9f/fa9971d2a0c6fef64c87ba362a493a4f230eff4ea8dfb9f4c7cbdf71892e/apeye_core-1.1.5-py3-none-any.whl", hash = "sha256:dc27a93f8c9e246b3b238c5ea51edf6115ab2618ef029b9f2d9a190ec8228fbf", size = 99286, upload-time = "2024-01-30T17:45:46.764Z" }, +] + +[[package]] +name = "appnope" +version = "0.1.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/35/5d/752690df9ef5b76e169e68d6a129fa6d08a7100ca7f754c89495db3c6019/appnope-0.1.4.tar.gz", hash = "sha256:1de3860566df9caf38f01f86f65e0e13e379af54f9e4bee1e66b48f2efffd1ee", size = 4170, upload-time = "2024-02-06T09:43:11.258Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/81/29/5ecc3a15d5a33e31b26c11426c45c501e439cb865d0bff96315d86443b78/appnope-0.1.4-py2.py3-none-any.whl", hash = "sha256:502575ee11cd7a28c0205f379b525beefebab9d161b7c964670864014ed7213c", size = 4321, upload-time = "2024-02-06T09:43:09.663Z" }, +] + [[package]] name = "asttokens" version = "3.0.0" @@ -85,6 +143,40 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/77/06/bb80f5f86020c4551da315d78b3ab75e8228f89f0162f2c3a819e407941a/attrs-25.3.0-py3-none-any.whl", hash = "sha256:427318ce031701fea540783410126f03899a97ffc6f61596ad581ac2e40e3bc3", size = 63815, upload-time = "2025-03-13T11:10:21.14Z" }, ] +[[package]] +name = "autodocsumm" +version = "0.2.14" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/03/96/92afe8a7912b327c01f0a8b6408c9556ee13b1aba5b98d587ac7327ff32d/autodocsumm-0.2.14.tar.gz", hash = "sha256:2839a9d4facc3c4eccd306c08695540911042b46eeafcdc3203e6d0bab40bc77", size = 46357, upload-time = "2024-10-23T18:51:47.369Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/87/bc/3f66af9beb683728e06ca08797e4e9d3e44f432f339718cae3ba856a9cad/autodocsumm-0.2.14-py3-none-any.whl", hash = "sha256:3bad8717fc5190802c60392a7ab04b9f3c97aa9efa8b3780b3d81d615bfe5dc0", size = 14640, upload-time = "2024-10-23T18:51:45.115Z" }, +] + +[[package]] +name = "babel" +version = "2.17.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/7d/6b/d52e42361e1aa00709585ecc30b3f9684b3ab62530771402248b1b1d6240/babel-2.17.0.tar.gz", hash = "sha256:0c54cffb19f690cdcc52a3b50bcbf71e07a808d1c80d549f2459b9d2cf0afb9d", size = 9951852, upload-time = "2025-02-01T15:17:41.026Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b7/b8/3fe70c75fe32afc4bb507f75563d39bc5642255d1d94f1f23604725780bf/babel-2.17.0-py3-none-any.whl", hash = "sha256:4d0b53093fdfb4b21c92b5213dba5a1b23885afa8383709427046b21c366e5f2", size = 10182537, upload-time = "2025-02-01T15:17:37.39Z" }, +] + +[[package]] +name = "beautifulsoup4" +version = "4.14.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "soupsieve" }, + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/77/e9/df2358efd7659577435e2177bfa69cba6c33216681af51a707193dec162a/beautifulsoup4-4.14.2.tar.gz", hash = "sha256:2a98ab9f944a11acee9cc848508ec28d9228abfd522ef0fad6a02a72e0ded69e", size = 625822, upload-time = "2025-09-29T10:05:42.613Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/94/fe/3aed5d0be4d404d12d36ab97e2f1791424d9ca39c2f754a6285d59a3b01d/beautifulsoup4-4.14.2-py3-none-any.whl", hash = "sha256:5ef6fa3a8cbece8488d66985560f97ed091e22bbc4e9c2338508a9d5de6d4515", size = 106392, upload-time = "2025-09-29T10:05:43.771Z" }, +] + [[package]] name = "black" version = "25.1.0" @@ -111,6 +203,23 @@ jupyter = [ { name = "tokenize-rt" }, ] +[[package]] +name = "bleach" +version = "6.3.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "webencodings" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/07/18/3c8523962314be6bf4c8989c79ad9531c825210dd13a8669f6b84336e8bd/bleach-6.3.0.tar.gz", hash = "sha256:6f3b91b1c0a02bb9a78b5a454c92506aa0fdf197e1d5e114d2e00c6f64306d22", size = 203533, upload-time = "2025-10-27T17:57:39.211Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/cd/3a/577b549de0cc09d95f11087ee63c739bba856cd3952697eec4c4bb91350a/bleach-6.3.0-py3-none-any.whl", hash = "sha256:fe10ec77c93ddf3d13a73b035abaac7a9f5e436513864ccdad516693213c65d6", size = 164437, upload-time = "2025-10-27T17:57:37.538Z" }, +] + +[package.optional-dependencies] +css = [ + { name = "tinycss2" }, +] + [[package]] name = "blinker" version = "1.9.0" @@ -120,6 +229,24 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/10/cb/f2ad4230dc2eb1a74edf38f1a38b9b52277f75bef262d8908e60d957e13c/blinker-1.9.0-py3-none-any.whl", hash = "sha256:ba0efaa9080b619ff2f3459d1d500c57bddea4a6b424b60a91141db6fd2f08bc", size = 8458, upload-time = "2024-11-08T17:25:46.184Z" }, ] +[[package]] +name = "cachecontrol" +version = "0.14.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "msgpack" }, + { name = "requests" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/58/3a/0cbeb04ea57d2493f3ec5a069a117ab467f85e4a10017c6d854ddcbff104/cachecontrol-0.14.3.tar.gz", hash = "sha256:73e7efec4b06b20d9267b441c1f733664f989fb8688391b670ca812d70795d11", size = 28985, upload-time = "2025-04-30T16:45:06.135Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/81/4c/800b0607b00b3fd20f1087f80ab53d6b4d005515b0f773e4831e37cfa83f/cachecontrol-0.14.3-py3-none-any.whl", hash = "sha256:b35e44a3113f17d2a31c1e6b27b9de6d4405f84ae51baa8c1d3cc5b633010cae", size = 21802, upload-time = "2025-04-30T16:45:03.863Z" }, +] + +[package.optional-dependencies] +filecache = [ + { name = "filelock" }, +] + [[package]] name = "cachetools" version = "5.5.2" @@ -138,6 +265,30 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/4f/52/34c6cf5bb9285074dc3531c437b3919e825d976fde097a7a73f79e726d03/certifi-2025.7.14-py3-none-any.whl", hash = "sha256:6b31f564a415d79ee77df69d757bb49a5bb53bd9f756cbbe24394ffd6fc1f4b2", size = 162722, upload-time = "2025-07-14T03:29:26.863Z" }, ] +[[package]] +name = "cffi" +version = "2.0.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pycparser", marker = "implementation_name != 'PyPy'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/eb/56/b1ba7935a17738ae8453301356628e8147c79dbb825bcbc73dc7401f9846/cffi-2.0.0.tar.gz", hash = "sha256:44d1b5909021139fe36001ae048dbdde8214afa20200eda0f64c068cac5d5529", size = 523588, upload-time = "2025-09-08T23:24:04.541Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/12/4a/3dfd5f7850cbf0d06dc84ba9aa00db766b52ca38d8b86e3a38314d52498c/cffi-2.0.0-cp311-cp311-macosx_10_13_x86_64.whl", hash = "sha256:b4c854ef3adc177950a8dfc81a86f5115d2abd545751a304c5bcf2c2c7283cfe", size = 184344, upload-time = "2025-09-08T23:22:26.456Z" }, + { url = "https://files.pythonhosted.org/packages/4f/8b/f0e4c441227ba756aafbe78f117485b25bb26b1c059d01f137fa6d14896b/cffi-2.0.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:2de9a304e27f7596cd03d16f1b7c72219bd944e99cc52b84d0145aefb07cbd3c", size = 180560, upload-time = "2025-09-08T23:22:28.197Z" }, + { url = "https://files.pythonhosted.org/packages/b1/b7/1200d354378ef52ec227395d95c2576330fd22a869f7a70e88e1447eb234/cffi-2.0.0-cp311-cp311-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:baf5215e0ab74c16e2dd324e8ec067ef59e41125d3eade2b863d294fd5035c92", size = 209613, upload-time = "2025-09-08T23:22:29.475Z" }, + { url = "https://files.pythonhosted.org/packages/b8/56/6033f5e86e8cc9bb629f0077ba71679508bdf54a9a5e112a3c0b91870332/cffi-2.0.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:730cacb21e1bdff3ce90babf007d0a0917cc3e6492f336c2f0134101e0944f93", size = 216476, upload-time = "2025-09-08T23:22:31.063Z" }, + { url = "https://files.pythonhosted.org/packages/dc/7f/55fecd70f7ece178db2f26128ec41430d8720f2d12ca97bf8f0a628207d5/cffi-2.0.0-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:6824f87845e3396029f3820c206e459ccc91760e8fa24422f8b0c3d1731cbec5", size = 203374, upload-time = "2025-09-08T23:22:32.507Z" }, + { url = "https://files.pythonhosted.org/packages/84/ef/a7b77c8bdc0f77adc3b46888f1ad54be8f3b7821697a7b89126e829e676a/cffi-2.0.0-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:9de40a7b0323d889cf8d23d1ef214f565ab154443c42737dfe52ff82cf857664", size = 202597, upload-time = "2025-09-08T23:22:34.132Z" }, + { url = "https://files.pythonhosted.org/packages/d7/91/500d892b2bf36529a75b77958edfcd5ad8e2ce4064ce2ecfeab2125d72d1/cffi-2.0.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:8941aaadaf67246224cee8c3803777eed332a19d909b47e29c9842ef1e79ac26", size = 215574, upload-time = "2025-09-08T23:22:35.443Z" }, + { url = "https://files.pythonhosted.org/packages/44/64/58f6255b62b101093d5df22dcb752596066c7e89dd725e0afaed242a61be/cffi-2.0.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:a05d0c237b3349096d3981b727493e22147f934b20f6f125a3eba8f994bec4a9", size = 218971, upload-time = "2025-09-08T23:22:36.805Z" }, + { url = "https://files.pythonhosted.org/packages/ab/49/fa72cebe2fd8a55fbe14956f9970fe8eb1ac59e5df042f603ef7c8ba0adc/cffi-2.0.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:94698a9c5f91f9d138526b48fe26a199609544591f859c870d477351dc7b2414", size = 211972, upload-time = "2025-09-08T23:22:38.436Z" }, + { url = "https://files.pythonhosted.org/packages/0b/28/dd0967a76aab36731b6ebfe64dec4e981aff7e0608f60c2d46b46982607d/cffi-2.0.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:5fed36fccc0612a53f1d4d9a816b50a36702c28a2aa880cb8a122b3466638743", size = 217078, upload-time = "2025-09-08T23:22:39.776Z" }, + { url = "https://files.pythonhosted.org/packages/2b/c0/015b25184413d7ab0a410775fdb4a50fca20f5589b5dab1dbbfa3baad8ce/cffi-2.0.0-cp311-cp311-win32.whl", hash = "sha256:c649e3a33450ec82378822b3dad03cc228b8f5963c0c12fc3b1e0ab940f768a5", size = 172076, upload-time = "2025-09-08T23:22:40.95Z" }, + { url = "https://files.pythonhosted.org/packages/ae/8f/dc5531155e7070361eb1b7e4c1a9d896d0cb21c49f807a6c03fd63fc877e/cffi-2.0.0-cp311-cp311-win_amd64.whl", hash = "sha256:66f011380d0e49ed280c789fbd08ff0d40968ee7b665575489afa95c98196ab5", size = 182820, upload-time = "2025-09-08T23:22:42.463Z" }, + { url = "https://files.pythonhosted.org/packages/95/5c/1b493356429f9aecfd56bc171285a4c4ac8697f76e9bbbbb105e537853a1/cffi-2.0.0-cp311-cp311-win_arm64.whl", hash = "sha256:c6638687455baf640e37344fe26d37c404db8b80d037c3d29f58fe8d1c3b194d", size = 177635, upload-time = "2025-09-08T23:22:43.623Z" }, +] + [[package]] name = "charset-normalizer" version = "3.4.2" @@ -181,6 +332,40 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" }, ] +[[package]] +name = "comm" +version = "0.2.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/4c/13/7d740c5849255756bc17888787313b61fd38a0a8304fc4f073dfc46122aa/comm-0.2.3.tar.gz", hash = "sha256:2dc8048c10962d55d7ad693be1e7045d891b7ce8d999c97963a5e3e99c055971", size = 6319, upload-time = "2025-07-25T14:02:04.452Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/60/97/891a0971e1e4a8c5d2b20bbe0e524dc04548d2307fee33cdeba148fd4fc7/comm-0.2.3-py3-none-any.whl", hash = "sha256:c615d91d75f7f04f095b30d1c1711babd43bdc6419c1be9886a85f2f4e489417", size = 7294, upload-time = "2025-07-25T14:02:02.896Z" }, +] + +[[package]] +name = "cssutils" +version = "2.11.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "more-itertools" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/33/9f/329d26121fe165be44b1dfff21aa0dc348f04633931f1d20ed6cf448a236/cssutils-2.11.1.tar.gz", hash = "sha256:0563a76513b6af6eebbe788c3bf3d01c920e46b3f90c8416738c5cfc773ff8e2", size = 711657, upload-time = "2024-06-04T15:51:39.373Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a7/ec/bb273b7208c606890dc36540fe667d06ce840a6f62f9fae7e658fcdc90fb/cssutils-2.11.1-py3-none-any.whl", hash = "sha256:a67bfdfdff4f3867fab43698ec4897c1a828eca5973f4073321b3bccaf1199b1", size = 385747, upload-time = "2024-06-04T15:51:37.499Z" }, +] + +[[package]] +name = "debugpy" +version = "1.8.17" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/15/ad/71e708ff4ca377c4230530d6a7aa7992592648c122a2cd2b321cf8b35a76/debugpy-1.8.17.tar.gz", hash = "sha256:fd723b47a8c08892b1a16b2c6239a8b96637c62a59b94bb5dab4bac592a58a8e", size = 1644129, upload-time = "2025-09-17T16:33:20.633Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d8/53/3af72b5c159278c4a0cf4cffa518675a0e73bdb7d1cac0239b815502d2ce/debugpy-1.8.17-cp311-cp311-macosx_15_0_universal2.whl", hash = "sha256:d3fce3f0e3de262a3b67e69916d001f3e767661c6e1ee42553009d445d1cd840", size = 2207154, upload-time = "2025-09-17T16:33:29.457Z" }, + { url = "https://files.pythonhosted.org/packages/8f/6d/204f407df45600e2245b4a39860ed4ba32552330a0b3f5f160ae4cc30072/debugpy-1.8.17-cp311-cp311-manylinux_2_34_x86_64.whl", hash = "sha256:c6bdf134457ae0cac6fb68205776be635d31174eeac9541e1d0c062165c6461f", size = 3170322, upload-time = "2025-09-17T16:33:30.837Z" }, + { url = "https://files.pythonhosted.org/packages/f2/13/1b8f87d39cf83c6b713de2620c31205299e6065622e7dd37aff4808dd410/debugpy-1.8.17-cp311-cp311-win32.whl", hash = "sha256:e79a195f9e059edfe5d8bf6f3749b2599452d3e9380484cd261f6b7cd2c7c4da", size = 5155078, upload-time = "2025-09-17T16:33:33.331Z" }, + { url = "https://files.pythonhosted.org/packages/c2/c5/c012c60a2922cc91caa9675d0ddfbb14ba59e1e36228355f41cab6483469/debugpy-1.8.17-cp311-cp311-win_amd64.whl", hash = "sha256:b532282ad4eca958b1b2d7dbcb2b7218e02cb934165859b918e3b6ba7772d3f4", size = 5179011, upload-time = "2025-09-17T16:33:35.711Z" }, + { url = "https://files.pythonhosted.org/packages/b0/d0/89247ec250369fc76db477720a26b2fce7ba079ff1380e4ab4529d2fe233/debugpy-1.8.17-py2.py3-none-any.whl", hash = "sha256:60c7dca6571efe660ccb7a9508d73ca14b8796c4ed484c2002abba714226cfef", size = 5283210, upload-time = "2025-09-17T16:34:25.835Z" }, +] + [[package]] name = "decorator" version = "5.2.1" @@ -190,6 +375,28 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/4e/8c/f3147f5c4b73e7550fe5f9352eaa956ae838d5c51eb58e7a25b9f3e2643b/decorator-5.2.1-py3-none-any.whl", hash = "sha256:d316bb415a2d9e2d2b3abcc4084c6502fc09240e292cd76a76afc106a1c8e04a", size = 9190, upload-time = "2025-02-24T04:41:32.565Z" }, ] +[[package]] +name = "defusedxml" +version = "0.7.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/0f/d5/c66da9b79e5bdb124974bfe172b4daf3c984ebd9c2a06e2b8a4dc7331c72/defusedxml-0.7.1.tar.gz", hash = "sha256:1bb3032db185915b62d7c6209c5a8792be6a32ab2fedacc84e01b52c51aa3e69", size = 75520, upload-time = "2021-03-08T10:59:26.269Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/07/6c/aa3f2f849e01cb6a001cd8554a88d4c77c5c1a31c95bdf1cf9301e6d9ef4/defusedxml-0.7.1-py2.py3-none-any.whl", hash = "sha256:a352e7e428770286cc899e2542b6cdaedb2b4953ff269a210103ec58f6198a61", size = 25604, upload-time = "2021-03-08T10:59:24.45Z" }, +] + +[[package]] +name = "dict2css" +version = "0.3.0.post1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "cssutils" }, + { name = "domdf-python-tools" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/24/eb/776eef1f1aa0188c0fc165c3a60b71027539f71f2eedc43ad21b060e9c39/dict2css-0.3.0.post1.tar.gz", hash = "sha256:89c544c21c4ca7472c3fffb9d37d3d926f606329afdb751dc1de67a411b70719", size = 7845, upload-time = "2023-11-22T11:09:20.958Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/fe/47/290daabcf91628f4fc0e17c75a1690b354ba067066cd14407712600e609f/dict2css-0.3.0.post1-py3-none-any.whl", hash = "sha256:f006a6b774c3e31869015122ae82c491fd25e7de4a75607a62aa3e798f837e0d", size = 25647, upload-time = "2023-11-22T11:09:19.221Z" }, +] + [[package]] name = "distro" version = "1.9.0" @@ -208,6 +415,28 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/55/e2/2537ebcff11c1ee1ff17d8d0b6f4db75873e3b0fb32c2d4a2ee31ecb310a/docstring_parser-0.17.0-py3-none-any.whl", hash = "sha256:cf2569abd23dce8099b300f9b4fa8191e9582dda731fd533daf54c4551658708", size = 36896, upload-time = "2025-07-21T07:35:00.684Z" }, ] +[[package]] +name = "docutils" +version = "0.18.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/57/b1/b880503681ea1b64df05106fc7e3c4e3801736cf63deffc6fa7fc5404cf5/docutils-0.18.1.tar.gz", hash = "sha256:679987caf361a7539d76e584cbeddc311e3aee937877c87346f31debc63e9d06", size = 2043249, upload-time = "2021-11-23T17:49:42.043Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/8d/14/69b4bad34e3f250afe29a854da03acb6747711f3df06c359fa053fae4e76/docutils-0.18.1-py2.py3-none-any.whl", hash = "sha256:23010f129180089fbcd3bc08cfefccb3b890b0050e1ca00c867036e9d161b98c", size = 570050, upload-time = "2021-11-23T17:49:38.556Z" }, +] + +[[package]] +name = "domdf-python-tools" +version = "3.10.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "natsort" }, + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/36/8b/ab2d8a292bba8fe3135cacc8bfd3576710a14b8f2d0a8cde19130d5c9d21/domdf_python_tools-3.10.0.tar.gz", hash = "sha256:2ae308d2f4f1e9145f5f4ba57f840fbfd1c2983ee26e4824347789649d3ae298", size = 100458, upload-time = "2025-02-12T17:34:05.747Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/5b/11/208f72084084d3f6a2ed5ebfdfc846692c3f7ad6dce65e400194924f7eed/domdf_python_tools-3.10.0-py3-none-any.whl", hash = "sha256:5e71c1be71bbcc1f881d690c8984b60e64298ec256903b3147f068bc33090c36", size = 126860, upload-time = "2025-02-12T17:34:04.093Z" }, +] + [[package]] name = "dotenv" version = "0.9.9" @@ -237,6 +466,24 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/7b/8f/c4d9bafc34ad7ad5d8dc16dd1347ee0e507a52c3adb6bfa8887e1c6a26ba/executing-2.2.0-py2.py3-none-any.whl", hash = "sha256:11387150cad388d62750327a53d3339fad4888b39a6fe233c3afbb54ecffd3aa", size = 26702, upload-time = "2025-01-22T15:41:25.929Z" }, ] +[[package]] +name = "fastjsonschema" +version = "2.21.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/20/b5/23b216d9d985a956623b6bd12d4086b60f0059b27799f23016af04a74ea1/fastjsonschema-2.21.2.tar.gz", hash = "sha256:b1eb43748041c880796cd077f1a07c3d94e93ae84bba5ed36800a33554ae05de", size = 374130, upload-time = "2025-08-14T18:49:36.666Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/cb/a8/20d0723294217e47de6d9e2e40fd4a9d2f7c4b6ef974babd482a59743694/fastjsonschema-2.21.2-py3-none-any.whl", hash = "sha256:1c797122d0a86c5cace2e54bf4e819c36223b552017172f32c5c024a6b77e463", size = 24024, upload-time = "2025-08-14T18:49:34.776Z" }, +] + +[[package]] +name = "filelock" +version = "3.20.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/58/46/0028a82567109b5ef6e4d2a1f04a583fb513e6cf9527fcdd09afd817deeb/filelock-3.20.0.tar.gz", hash = "sha256:711e943b4ec6be42e1d4e6690b48dc175c822967466bb31c0c293f34334c13f4", size = 18922, upload-time = "2025-10-08T18:03:50.056Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/76/91/7216b27286936c16f5b4d0c530087e4a54eead683e6b0b73dd0c64844af6/filelock-3.20.0-py3-none-any.whl", hash = "sha256:339b4732ffda5cd79b13f4e2711a31b0365ce445d95d243bb996273d072546a2", size = 16054, upload-time = "2025-10-08T18:03:48.35Z" }, +] + [[package]] name = "flask" version = "3.1.1" @@ -350,6 +597,19 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" }, ] +[[package]] +name = "html5lib" +version = "1.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "six" }, + { name = "webencodings" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/ac/b6/b55c3f49042f1df3dcd422b7f224f939892ee94f22abcf503a9b7339eaf2/html5lib-1.1.tar.gz", hash = "sha256:b2e5b40261e20f354d198eae92afc10d750afb487ed5e50f9c4eaf07c184146f", size = 272215, upload-time = "2020-06-22T23:32:38.834Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/6c/dd/a834df6482147d48e225a49515aabc28974ad5a4ca3215c18a882565b028/html5lib-1.1-py2.py3-none-any.whl", hash = "sha256:0d78f8fde1c230e99fe37986a60526d7049ed4bf8a9fadbad5f00e22e58e041d", size = 112173, upload-time = "2020-06-22T23:32:36.781Z" }, +] + [[package]] name = "httpcore" version = "1.0.9" @@ -396,6 +656,27 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/76/c6/c88e154df9c4e1a2a66ccf0005a88dfb2650c1dffb6f5ce603dfbd452ce3/idna-3.10-py3-none-any.whl", hash = "sha256:946d195a0d259cbba61165e88e65941f16e9b36ea6ddb97f00452bae8b1287d3", size = 70442, upload-time = "2024-09-15T18:07:37.964Z" }, ] +[[package]] +name = "imagesize" +version = "1.4.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/a7/84/62473fb57d61e31fef6e36d64a179c8781605429fd927b5dd608c997be31/imagesize-1.4.1.tar.gz", hash = "sha256:69150444affb9cb0d5cc5a92b3676f0b2fb7cd9ae39e947a5e11a36b4497cd4a", size = 1280026, upload-time = "2022-07-01T12:21:05.687Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ff/62/85c4c919272577931d407be5ba5d71c20f0b616d31a0befe0ae45bb79abd/imagesize-1.4.1-py2.py3-none-any.whl", hash = "sha256:0d8d18d08f840c19d0ee7ca1fd82490fdc3729b7ac93f49870406ddde8ef8d8b", size = 8769, upload-time = "2022-07-01T12:21:02.467Z" }, +] + +[[package]] +name = "importlib-metadata" +version = "8.7.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "zipp" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/76/66/650a33bd90f786193e4de4b3ad86ea60b53c89b669a5c7be931fac31cdb0/importlib_metadata-8.7.0.tar.gz", hash = "sha256:d13b81ad223b890aa16c5471f2ac3056cf76c5f10f82d6f9292f0b415f389000", size = 56641, upload-time = "2025-04-27T15:29:01.736Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/20/b0/36bd937216ec521246249be3bf9855081de4c5e06a0c9b4219dbeda50373/importlib_metadata-8.7.0-py3-none-any.whl", hash = "sha256:e5dd1551894c77868a30651cef00984d50e1002d06942a7101d34870c5f02afd", size = 27656, upload-time = "2025-04-27T15:29:00.214Z" }, +] + [[package]] name = "iniconfig" version = "2.1.0" @@ -405,6 +686,30 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/2c/e1/e6716421ea10d38022b952c159d5161ca1193197fb744506875fbb87ea7b/iniconfig-2.1.0-py3-none-any.whl", hash = "sha256:9deba5723312380e77435581c6bf4935c94cbfab9b1ed33ef8d238ea168eb760", size = 6050, upload-time = "2025-03-19T20:10:01.071Z" }, ] +[[package]] +name = "ipykernel" +version = "7.1.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "appnope", marker = "sys_platform == 'darwin'" }, + { name = "comm" }, + { name = "debugpy" }, + { name = "ipython" }, + { name = "jupyter-client" }, + { name = "jupyter-core" }, + { name = "matplotlib-inline" }, + { name = "nest-asyncio" }, + { name = "packaging" }, + { name = "psutil" }, + { name = "pyzmq" }, + { name = "tornado" }, + { name = "traitlets" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/b9/a4/4948be6eb88628505b83a1f2f40d90254cab66abf2043b3c40fa07dfce0f/ipykernel-7.1.0.tar.gz", hash = "sha256:58a3fc88533d5930c3546dc7eac66c6d288acde4f801e2001e65edc5dc9cf0db", size = 174579, upload-time = "2025-10-27T09:46:39.471Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a3/17/20c2552266728ceba271967b87919664ecc0e33efca29c3efc6baf88c5f9/ipykernel-7.1.0-py3-none-any.whl", hash = "sha256:763b5ec6c5b7776f6a8d7ce09b267693b4e5ce75cb50ae696aaefb3c85e1ea4c", size = 117968, upload-time = "2025-10-27T09:46:37.805Z" }, +] + [[package]] name = "ipython" version = "9.4.0" @@ -537,16 +842,123 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/01/0e/b27cdbaccf30b890c40ed1da9fd4a3593a5cf94dae54fb34f8a4b74fcd3f/jsonschema_specifications-2025.4.1-py3-none-any.whl", hash = "sha256:4653bffbd6584f7de83a67e0d620ef16900b390ddc7939d56684d6c81e33f1af", size = 18437, upload-time = "2025-04-23T12:34:05.422Z" }, ] +[[package]] +name = "jupyter-book" +version = "0.15.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "click" }, + { name = "docutils" }, + { name = "jinja2" }, + { name = "jsonschema" }, + { name = "linkify-it-py" }, + { name = "myst-nb" }, + { name = "pyyaml" }, + { name = "sphinx" }, + { name = "sphinx-book-theme" }, + { name = "sphinx-comments" }, + { name = "sphinx-copybutton" }, + { name = "sphinx-design" }, + { name = "sphinx-external-toc" }, + { name = "sphinx-jupyterbook-latex" }, + { name = "sphinx-multitoc-numbering" }, + { name = "sphinx-thebe" }, + { name = "sphinx-togglebutton" }, + { name = "sphinxcontrib-bibtex" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/b3/1a/e38481ea2cd9988234eeee4dd21bec64f235c78004797e48643592018490/jupyter-book-0.15.1.tar.gz", hash = "sha256:8a1634ec16f7eedee0d116f1e5fb7c48203289ad92da42e09519dc71d956c010", size = 63027, upload-time = "2023-03-14T01:32:07.066Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ab/ef/c56470847067fd6d4c059265543188c63b56d01aa2107b18895404f82a9c/jupyter_book-0.15.1-py3-none-any.whl", hash = "sha256:7671264952abd1ca3f5e713b03e138dda710c92a985c49154f398817fe089968", size = 43698, upload-time = "2023-03-14T01:32:05.453Z" }, +] + +[[package]] +name = "jupyter-cache" +version = "0.6.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "attrs" }, + { name = "click" }, + { name = "importlib-metadata" }, + { name = "nbclient" }, + { name = "nbformat" }, + { name = "pyyaml" }, + { name = "sqlalchemy" }, + { name = "tabulate" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/69/64/08dcc1f6fc54a263525edd23b5d2754793470c1c41a8dd82d52406f8d876/jupyter-cache-0.6.1.tar.gz", hash = "sha256:26f83901143edf4af2f3ff5a91e2d2ad298e46e2cee03c8071d37a23a63ccbfc", size = 31953, upload-time = "2023-04-22T15:38:06.006Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/da/8e/918b115bb3b4b821e2d43315e1a08b909219723191623ffbae9072fd226a/jupyter_cache-0.6.1-py3-none-any.whl", hash = "sha256:2fce7d4975805c77f75bdfc1bc2e82bc538b8e5b1af27f2f5e06d55b9f996a82", size = 33886, upload-time = "2023-04-22T15:38:04.33Z" }, +] + +[[package]] +name = "jupyter-client" +version = "8.6.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "jupyter-core" }, + { name = "python-dateutil" }, + { name = "pyzmq" }, + { name = "tornado" }, + { name = "traitlets" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/71/22/bf9f12fdaeae18019a468b68952a60fe6dbab5d67cd2a103cac7659b41ca/jupyter_client-8.6.3.tar.gz", hash = "sha256:35b3a0947c4a6e9d589eb97d7d4cd5e90f910ee73101611f01283732bd6d9419", size = 342019, upload-time = "2024-09-17T10:44:17.613Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/11/85/b0394e0b6fcccd2c1eeefc230978a6f8cb0c5df1e4cd3e7625735a0d7d1e/jupyter_client-8.6.3-py3-none-any.whl", hash = "sha256:e8a19cc986cc45905ac3362915f410f3af85424b4c0905e94fa5f2cb08e8f23f", size = 106105, upload-time = "2024-09-17T10:44:15.218Z" }, +] + +[[package]] +name = "jupyter-core" +version = "5.9.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "platformdirs" }, + { name = "traitlets" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/02/49/9d1284d0dc65e2c757b74c6687b6d319b02f822ad039e5c512df9194d9dd/jupyter_core-5.9.1.tar.gz", hash = "sha256:4d09aaff303b9566c3ce657f580bd089ff5c91f5f89cf7d8846c3cdf465b5508", size = 89814, upload-time = "2025-10-16T19:19:18.444Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e7/e7/80988e32bf6f73919a113473a604f5a8f09094de312b9d52b79c2df7612b/jupyter_core-5.9.1-py3-none-any.whl", hash = "sha256:ebf87fdc6073d142e114c72c9e29a9d7ca03fad818c5d300ce2adc1fb0743407", size = 29032, upload-time = "2025-10-16T19:19:16.783Z" }, +] + +[[package]] +name = "jupyterlab-pygments" +version = "0.3.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/90/51/9187be60d989df97f5f0aba133fa54e7300f17616e065d1ada7d7646b6d6/jupyterlab_pygments-0.3.0.tar.gz", hash = "sha256:721aca4d9029252b11cfa9d185e5b5af4d54772bb8072f9b7036f4170054d35d", size = 512900, upload-time = "2023-11-23T09:26:37.44Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b1/dd/ead9d8ea85bf202d90cc513b533f9c363121c7792674f78e0d8a854b63b4/jupyterlab_pygments-0.3.0-py3-none-any.whl", hash = "sha256:841a89020971da1d8693f1a99997aefc5dc424bb1b251fd6322462a1b8842780", size = 15884, upload-time = "2023-11-23T09:26:34.325Z" }, +] + +[[package]] +name = "latexcodec" +version = "3.0.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/27/dd/4270b2c5e2ee49316c3859e62293bd2ea8e382339d63ab7bbe9f39c0ec3b/latexcodec-3.0.1.tar.gz", hash = "sha256:e78a6911cd72f9dec35031c6ec23584de6842bfbc4610a9678868d14cdfb0357", size = 31222, upload-time = "2025-06-17T18:47:34.051Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b5/40/23569737873cc9637fd488606347e9dd92b9fa37ba4fcda1f98ee5219a97/latexcodec-3.0.1-py3-none-any.whl", hash = "sha256:a9eb8200bff693f0437a69581f7579eb6bca25c4193515c09900ce76451e452e", size = 18532, upload-time = "2025-06-17T18:47:30.726Z" }, +] + +[[package]] +name = "linkify-it-py" +version = "2.0.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "uc-micro-py" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/2a/ae/bb56c6828e4797ba5a4821eec7c43b8bf40f69cda4d4f5f8c8a2810ec96a/linkify-it-py-2.0.3.tar.gz", hash = "sha256:68cda27e162e9215c17d786649d1da0021a451bdc436ef9e0fa0ba5234b9b048", size = 27946, upload-time = "2024-02-04T14:48:04.179Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/04/1e/b832de447dee8b582cac175871d2f6c3d5077cc56d5575cadba1fd1cccfa/linkify_it_py-2.0.3-py3-none-any.whl", hash = "sha256:6bcbc417b0ac14323382aef5c5192c0075bf8a9d6b41820a2b66371eac6b6d79", size = 19820, upload-time = "2024-02-04T14:48:02.496Z" }, +] + [[package]] name = "markdown-it-py" -version = "3.0.0" +version = "2.2.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "mdurl" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/38/71/3b932df36c1a044d397a1f92d1cf91ee0a503d91e470cbd670aa66b07ed0/markdown-it-py-3.0.0.tar.gz", hash = "sha256:e3f60a94fa066dc52ec76661e37c851cb232d92f9886b15cb560aaada2df8feb", size = 74596, upload-time = "2023-06-03T06:41:14.443Z" } +sdist = { url = "https://files.pythonhosted.org/packages/e4/c0/59bd6d0571986f72899288a95d9d6178d0eebd70b6650f1bb3f0da90f8f7/markdown-it-py-2.2.0.tar.gz", hash = "sha256:7c9a5e412688bc771c67432cbfebcdd686c93ce6484913dccf06cb5a0bea35a1", size = 67120, upload-time = "2023-02-22T05:54:30.899Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/42/d7/1ec15b46af6af88f19b8e5ffea08fa375d433c998b8a7639e76935c14f1f/markdown_it_py-3.0.0-py3-none-any.whl", hash = "sha256:355216845c60bd96232cd8d8c40e8f9765cc86f46880e43a8fd22dc1a1a8cab1", size = 87528, upload-time = "2023-06-03T06:41:11.019Z" }, + { url = "https://files.pythonhosted.org/packages/bf/25/2d88e8feee8e055d015343f9b86e370a1ccbec546f2865c98397aaef24af/markdown_it_py-2.2.0-py3-none-any.whl", hash = "sha256:5a35f8d1870171d9acc47b99612dc146129b631baf04970128b568f190d0cc30", size = 84466, upload-time = "2023-02-22T05:54:29.508Z" }, ] [[package]] @@ -601,6 +1013,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/8f/8b/0be74e3308a486f1d127f3f6767de5f9f76454c9b4183210c61cc50999b6/mcp-1.12.3-py3-none-any.whl", hash = "sha256:5483345bf39033b858920a5b6348a303acacf45b23936972160ff152107b850e", size = 158810, upload-time = "2025-07-31T18:36:34.915Z" }, ] +[[package]] +name = "mdit-py-plugins" +version = "0.3.5" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "markdown-it-py" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/49/e7/cc2720da8a32724b36d04c6dba5644154cdf883a1482b3bbb81959a642ed/mdit-py-plugins-0.3.5.tar.gz", hash = "sha256:eee0adc7195e5827e17e02d2a258a2ba159944a0748f59c5099a4a27f78fcf6a", size = 39871, upload-time = "2023-03-02T17:42:50.654Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/fe/4c/a9b222f045f98775034d243198212cbea36d3524c3ee1e8ab8c0346d6953/mdit_py_plugins-0.3.5-py3-none-any.whl", hash = "sha256:ca9a0714ea59a24b2b044a1831f48d817dd0c817e84339f20e7889f392d77c4e", size = 52087, upload-time = "2023-03-02T17:42:48.841Z" }, +] + [[package]] name = "mdurl" version = "0.1.2" @@ -610,6 +1034,41 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" }, ] +[[package]] +name = "mistune" +version = "3.1.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/d7/02/a7fb8b21d4d55ac93cdcde9d3638da5dd0ebdd3a4fed76c7725e10b81cbe/mistune-3.1.4.tar.gz", hash = "sha256:b5a7f801d389f724ec702840c11d8fc48f2b33519102fc7ee739e8177b672164", size = 94588, upload-time = "2025-08-29T07:20:43.594Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/7a/f0/8282d9641415e9e33df173516226b404d367a0fc55e1a60424a152913abc/mistune-3.1.4-py3-none-any.whl", hash = "sha256:93691da911e5d9d2e23bc54472892aff676df27a75274962ff9edc210364266d", size = 53481, upload-time = "2025-08-29T07:20:42.218Z" }, +] + +[[package]] +name = "more-itertools" +version = "10.8.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/ea/5d/38b681d3fce7a266dd9ab73c66959406d565b3e85f21d5e66e1181d93721/more_itertools-10.8.0.tar.gz", hash = "sha256:f638ddf8a1a0d134181275fb5d58b086ead7c6a72429ad725c67503f13ba30bd", size = 137431, upload-time = "2025-09-02T15:23:11.018Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a4/8e/469e5a4a2f5855992e425f3cb33804cc07bf18d48f2db061aec61ce50270/more_itertools-10.8.0-py3-none-any.whl", hash = "sha256:52d4362373dcf7c52546bc4af9a86ee7c4579df9a8dc268be0a2f949d376cc9b", size = 69667, upload-time = "2025-09-02T15:23:09.635Z" }, +] + +[[package]] +name = "msgpack" +version = "1.1.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/4d/f2/bfb55a6236ed8725a96b0aa3acbd0ec17588e6a2c3b62a93eb513ed8783f/msgpack-1.1.2.tar.gz", hash = "sha256:3b60763c1373dd60f398488069bcdc703cd08a711477b5d480eecc9f9626f47e", size = 173581, upload-time = "2025-10-08T09:15:56.596Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/2c/97/560d11202bcd537abca693fd85d81cebe2107ba17301de42b01ac1677b69/msgpack-1.1.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:2e86a607e558d22985d856948c12a3fa7b42efad264dca8a3ebbcfa2735d786c", size = 82271, upload-time = "2025-10-08T09:14:49.967Z" }, + { url = "https://files.pythonhosted.org/packages/83/04/28a41024ccbd67467380b6fb440ae916c1e4f25e2cd4c63abe6835ac566e/msgpack-1.1.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:283ae72fc89da59aa004ba147e8fc2f766647b1251500182fac0350d8af299c0", size = 84914, upload-time = "2025-10-08T09:14:50.958Z" }, + { url = "https://files.pythonhosted.org/packages/71/46/b817349db6886d79e57a966346cf0902a426375aadc1e8e7a86a75e22f19/msgpack-1.1.2-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:61c8aa3bd513d87c72ed0b37b53dd5c5a0f58f2ff9f26e1555d3bd7948fb7296", size = 416962, upload-time = "2025-10-08T09:14:51.997Z" }, + { url = "https://files.pythonhosted.org/packages/da/e0/6cc2e852837cd6086fe7d8406af4294e66827a60a4cf60b86575a4a65ca8/msgpack-1.1.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:454e29e186285d2ebe65be34629fa0e8605202c60fbc7c4c650ccd41870896ef", size = 426183, upload-time = "2025-10-08T09:14:53.477Z" }, + { url = "https://files.pythonhosted.org/packages/25/98/6a19f030b3d2ea906696cedd1eb251708e50a5891d0978b012cb6107234c/msgpack-1.1.2-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:7bc8813f88417599564fafa59fd6f95be417179f76b40325b500b3c98409757c", size = 411454, upload-time = "2025-10-08T09:14:54.648Z" }, + { url = "https://files.pythonhosted.org/packages/b7/cd/9098fcb6adb32187a70b7ecaabf6339da50553351558f37600e53a4a2a23/msgpack-1.1.2-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:bafca952dc13907bdfdedfc6a5f579bf4f292bdd506fadb38389afa3ac5b208e", size = 422341, upload-time = "2025-10-08T09:14:56.328Z" }, + { url = "https://files.pythonhosted.org/packages/e6/ae/270cecbcf36c1dc85ec086b33a51a4d7d08fc4f404bdbc15b582255d05ff/msgpack-1.1.2-cp311-cp311-win32.whl", hash = "sha256:602b6740e95ffc55bfb078172d279de3773d7b7db1f703b2f1323566b878b90e", size = 64747, upload-time = "2025-10-08T09:14:57.882Z" }, + { url = "https://files.pythonhosted.org/packages/2a/79/309d0e637f6f37e83c711f547308b91af02b72d2326ddd860b966080ef29/msgpack-1.1.2-cp311-cp311-win_amd64.whl", hash = "sha256:d198d275222dc54244bf3327eb8cbe00307d220241d9cec4d306d49a44e85f68", size = 71633, upload-time = "2025-10-08T09:14:59.177Z" }, + { url = "https://files.pythonhosted.org/packages/73/4d/7c4e2b3d9b1106cd0aa6cb56cc57c6267f59fa8bfab7d91df5adc802c847/msgpack-1.1.2-cp311-cp311-win_arm64.whl", hash = "sha256:86f8136dfa5c116365a8a651a7d7484b65b13339731dd6faebb9a0242151c406", size = 64755, upload-time = "2025-10-08T09:15:00.48Z" }, +] + [[package]] name = "mypy" version = "1.17.0" @@ -639,6 +1098,135 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/79/7b/2c79738432f5c924bef5071f933bcc9efd0473bac3b4aa584a6f7c1c8df8/mypy_extensions-1.1.0-py3-none-any.whl", hash = "sha256:1be4cccdb0f2482337c4743e60421de3a356cd97508abadd57d47403e94f5505", size = 4963, upload-time = "2025-04-22T14:54:22.983Z" }, ] +[[package]] +name = "myst-nb" +version = "0.17.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "importlib-metadata" }, + { name = "ipykernel" }, + { name = "ipython" }, + { name = "jupyter-cache" }, + { name = "myst-parser" }, + { name = "nbclient" }, + { name = "nbformat" }, + { name = "pyyaml" }, + { name = "sphinx" }, + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/15/e6/6ec454f930f1d542f1c1d9562d939acc41220408ff996b7c5b3b957fba1d/myst-nb-0.17.2.tar.gz", hash = "sha256:0f61386515fab07c73646adca97fff2f69f41e90d313a260217c5bbe419d858b", size = 74184, upload-time = "2023-04-21T12:38:17.712Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/72/84/38b6468146945cf0466a149763d62bd0264cb221eaa74c979498ea215f22/myst_nb-0.17.2-py3-none-any.whl", hash = "sha256:132ca4d0f5c308fdd4b6fdaba077712e28e119ccdafd04d6e41b51aac5483494", size = 78636, upload-time = "2023-04-21T12:38:15.807Z" }, +] + +[[package]] +name = "myst-parser" +version = "0.18.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "docutils" }, + { name = "jinja2" }, + { name = "markdown-it-py" }, + { name = "mdit-py-plugins" }, + { name = "pyyaml" }, + { name = "sphinx" }, + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/68/13/91438d3b835a022fcacd858a7106d4813cfccf98b1fd9a6196cfa2c859df/myst-parser-0.18.1.tar.gz", hash = "sha256:79317f4bb2c13053dd6e64f9da1ba1da6cd9c40c8a430c447a7b146a594c246d", size = 64147, upload-time = "2022-09-27T09:57:45.183Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/72/fd/594c936c65e707deda5670e8fff5ca2c948a12e922813eab5d316694e9ca/myst_parser-0.18.1-py3-none-any.whl", hash = "sha256:61b275b85d9f58aa327f370913ae1bec26ebad372cc99f3ab85c8ec3ee8d9fb8", size = 58157, upload-time = "2022-09-27T09:57:42.689Z" }, +] + +[[package]] +name = "natsort" +version = "8.4.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/e2/a9/a0c57aee75f77794adaf35322f8b6404cbd0f89ad45c87197a937764b7d0/natsort-8.4.0.tar.gz", hash = "sha256:45312c4a0e5507593da193dedd04abb1469253b601ecaf63445ad80f0a1ea581", size = 76575, upload-time = "2023-06-20T04:17:19.925Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ef/82/7a9d0550484a62c6da82858ee9419f3dd1ccc9aa1c26a1e43da3ecd20b0d/natsort-8.4.0-py3-none-any.whl", hash = "sha256:4732914fb471f56b5cce04d7bae6f164a592c7712e1c85f9ef585e197299521c", size = 38268, upload-time = "2023-06-20T04:17:17.522Z" }, +] + +[[package]] +name = "nbclient" +version = "0.7.4" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "jupyter-client" }, + { name = "jupyter-core" }, + { name = "nbformat" }, + { name = "traitlets" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/c8/ee/b9351110fbbc8229863cbc54454f1db91f7836c730018d674a188ede5efd/nbclient-0.7.4.tar.gz", hash = "sha256:d447f0e5a4cfe79d462459aec1b3dc5c2e9152597262be8ee27f7d4c02566a0d", size = 60682, upload-time = "2023-04-25T14:38:02.404Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/f3/97/d35da363d1df4a68f1b3d44335f80235487d7ca77d1f606b0c3523118f34/nbclient-0.7.4-py3-none-any.whl", hash = "sha256:c817c0768c5ff0d60e468e017613e6eae27b6fa31e43f905addd2d24df60c125", size = 73120, upload-time = "2023-04-25T14:38:00.327Z" }, +] + +[[package]] +name = "nbconvert" +version = "7.16.6" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "beautifulsoup4" }, + { name = "bleach", extra = ["css"] }, + { name = "defusedxml" }, + { name = "jinja2" }, + { name = "jupyter-core" }, + { name = "jupyterlab-pygments" }, + { name = "markupsafe" }, + { name = "mistune" }, + { name = "nbclient" }, + { name = "nbformat" }, + { name = "packaging" }, + { name = "pandocfilters" }, + { name = "pygments" }, + { name = "traitlets" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/a3/59/f28e15fc47ffb73af68a8d9b47367a8630d76e97ae85ad18271b9db96fdf/nbconvert-7.16.6.tar.gz", hash = "sha256:576a7e37c6480da7b8465eefa66c17844243816ce1ccc372633c6b71c3c0f582", size = 857715, upload-time = "2025-01-28T09:29:14.724Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/cc/9a/cd673b2f773a12c992f41309ef81b99da1690426bd2f96957a7ade0d3ed7/nbconvert-7.16.6-py3-none-any.whl", hash = "sha256:1375a7b67e0c2883678c48e506dc320febb57685e5ee67faa51b18a90f3a712b", size = 258525, upload-time = "2025-01-28T09:29:12.551Z" }, +] + +[[package]] +name = "nbformat" +version = "5.10.4" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "fastjsonschema" }, + { name = "jsonschema" }, + { name = "jupyter-core" }, + { name = "traitlets" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/6d/fd/91545e604bc3dad7dca9ed03284086039b294c6b3d75c0d2fa45f9e9caf3/nbformat-5.10.4.tar.gz", hash = "sha256:322168b14f937a5d11362988ecac2a4952d3d8e3a2cbeb2319584631226d5b3a", size = 142749, upload-time = "2024-04-04T11:20:37.371Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a9/82/0340caa499416c78e5d8f5f05947ae4bc3cba53c9f038ab6e9ed964e22f1/nbformat-5.10.4-py3-none-any.whl", hash = "sha256:3b48d6c8fbca4b299bf3982ea7db1af21580e4fec269ad087b9e81588891200b", size = 78454, upload-time = "2024-04-04T11:20:34.895Z" }, +] + +[[package]] +name = "nbsphinx" +version = "0.9.7" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "docutils" }, + { name = "jinja2" }, + { name = "nbconvert" }, + { name = "nbformat" }, + { name = "sphinx" }, + { name = "traitlets" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/1e/84/b1856b7651ac34e965aa567a158714c7f3bd42a1b1ce76bf423ffb99872c/nbsphinx-0.9.7.tar.gz", hash = "sha256:abd298a686d55fa894ef697c51d44f24e53aa312dadae38e82920f250a5456fe", size = 180479, upload-time = "2025-03-03T19:46:08.069Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/49/2d/8c8e635bcc6757573d311bb3c5445426382f280da32b8cd6d82d501ef4a4/nbsphinx-0.9.7-py3-none-any.whl", hash = "sha256:7292c3767fea29e405c60743eee5393682a83982ab202ff98f5eb2db02629da8", size = 31660, upload-time = "2025-03-03T19:46:06.581Z" }, +] + +[[package]] +name = "nest-asyncio" +version = "1.6.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/83/f8/51569ac65d696c8ecbee95938f89d4abf00f47d58d48f6fbabfe8f0baefe/nest_asyncio-1.6.0.tar.gz", hash = "sha256:6f172d5449aca15afd6c646851f4e31e02c598d553a667e38cafa997cfec55fe", size = 7418, upload-time = "2024-01-21T14:25:19.227Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a0/c4/c2971a3ba4c6103a3d10c4b0f24f461ddc027f0f09763220cf35ca1401b3/nest_asyncio-1.6.0-py3-none-any.whl", hash = "sha256:87af6efd6b5e897c81050477ef65c62e2b2f35d51703cae01aff2905b1852e1c", size = 5195, upload-time = "2024-01-21T14:25:17.223Z" }, +] + [[package]] name = "nodeenv" version = "1.9.1" @@ -666,6 +1254,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/20/12/38679034af332785aac8774540895e234f4d07f7545804097de4b666afd8/packaging-25.0-py3-none-any.whl", hash = "sha256:29572ef2b1f17581046b3a2227d5c611fb25ec70ca1ba8554b24b0e69331a484", size = 66469, upload-time = "2025-04-19T11:48:57.875Z" }, ] +[[package]] +name = "pandocfilters" +version = "1.5.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/70/6f/3dd4940bbe001c06a65f88e36bad298bc7a0de5036115639926b0c5c0458/pandocfilters-1.5.1.tar.gz", hash = "sha256:002b4a555ee4ebc03f8b66307e287fa492e4a77b4ea14d3f934328297bb4939e", size = 8454, upload-time = "2024-01-18T20:08:13.726Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ef/af/4fbc8cab944db5d21b7e2a5b8e9211a03a79852b1157e2c102fcc61ac440/pandocfilters-1.5.1-py2.py3-none-any.whl", hash = "sha256:93be382804a9cdb0a7267585f157e5d1731bbe5545a85b268d6f5fe6232de2bc", size = 8663, upload-time = "2024-01-18T20:08:11.28Z" }, +] + [[package]] name = "parso" version = "0.8.4" @@ -802,6 +1399,41 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/47/8d/d529b5d697919ba8c11ad626e835d4039be708a35b0d22de83a269a6682c/pyasn1_modules-0.4.2-py3-none-any.whl", hash = "sha256:29253a9207ce32b64c3ac6600edc75368f98473906e8fd1043bd6b5b1de2c14a", size = 181259, upload-time = "2025-03-28T02:41:19.028Z" }, ] +[[package]] +name = "pybtex" +version = "0.25.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "latexcodec" }, + { name = "pyyaml" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/5f/bc/c2be05ca72f8c103670e983df8be26d1e288bc6556f487fa8cccaa27779f/pybtex-0.25.1.tar.gz", hash = "sha256:9eaf90267c7e83e225af89fea65c370afbf65f458220d3946a9e3049e1eca491", size = 406157, upload-time = "2025-06-26T13:27:41.903Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/25/68/ceb5d6679baa326261f5d3e5113d9cfed6efef2810afd9f18bffb8ed312b/pybtex-0.25.1-py2.py3-none-any.whl", hash = "sha256:9053b0d619409a0a83f38abad5d9921de5f7b3ede00742beafcd9f10ad0d8c5c", size = 127437, upload-time = "2025-06-26T13:27:43.585Z" }, +] + +[[package]] +name = "pybtex-docutils" +version = "1.0.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "docutils" }, + { name = "pybtex" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/7e/84/796ea94d26188a853660f81bded39f8de4cfe595130aef0dea1088705a11/pybtex-docutils-1.0.3.tar.gz", hash = "sha256:3a7ebdf92b593e00e8c1c538aa9a20bca5d92d84231124715acc964d51d93c6b", size = 18348, upload-time = "2023-08-22T18:47:54.833Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/11/b1/ce1f4596211efb5410e178a803f08e59b20bedb66837dcf41e21c54f9ec1/pybtex_docutils-1.0.3-py3-none-any.whl", hash = "sha256:8fd290d2ae48e32fcb54d86b0efb8d573198653c7e2447d5bec5847095f430b9", size = 6385, upload-time = "2023-08-22T06:43:20.513Z" }, +] + +[[package]] +name = "pycparser" +version = "2.23" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/fe/cf/d2d3b9f5699fb1e4615c8e32ff220203e43b248e1dfcc6736ad9057731ca/pycparser-2.23.tar.gz", hash = "sha256:78816d4f24add8f10a06d6f05b4d424ad9e96cfebf68a4ddc99c65c0720d00c2", size = 173734, upload-time = "2025-09-09T13:23:47.91Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a0/e3/59cd50310fc9b59512193629e1984c1f95e5c8ae6e5d8c69532ccc65a7fe/pycparser-2.23-py3-none-any.whl", hash = "sha256:e5c6e8d3fbad53479cab09ac03729e0a9faf2bee3db8208a550daf5af81a5934", size = 118140, upload-time = "2025-09-09T13:23:46.651Z" }, +] + [[package]] name = "pydantic" version = "2.11.7" @@ -865,6 +1497,25 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/58/f0/427018098906416f580e3cf1366d3b1abfb408a0652e9f31600c24a1903c/pydantic_settings-2.10.1-py3-none-any.whl", hash = "sha256:a60952460b99cf661dc25c29c0ef171721f98bfcb52ef8d9ea4c943d7c8cc796", size = 45235, upload-time = "2025-06-24T13:26:45.485Z" }, ] +[[package]] +name = "pydata-sphinx-theme" +version = "0.15.4" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "accessible-pygments" }, + { name = "babel" }, + { name = "beautifulsoup4" }, + { name = "docutils" }, + { name = "packaging" }, + { name = "pygments" }, + { name = "sphinx" }, + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/67/ea/3ab478cccacc2e8ef69892c42c44ae547bae089f356c4b47caf61730958d/pydata_sphinx_theme-0.15.4.tar.gz", hash = "sha256:7762ec0ac59df3acecf49fd2f889e1b4565dbce8b88b2e29ee06fdd90645a06d", size = 2400673, upload-time = "2024-06-25T19:28:45.041Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e7/d3/c622950d87a2ffd1654208733b5bd1c5645930014abed8f4c0d74863988b/pydata_sphinx_theme-0.15.4-py3-none-any.whl", hash = "sha256:2136ad0e9500d0949f96167e63f3e298620040aea8f9c74621959eda5d4cf8e6", size = 4640157, upload-time = "2024-06-25T19:28:42.383Z" }, +] + [[package]] name = "pygments" version = "2.19.2" @@ -916,6 +1567,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/ca/31/d4e37e9e550c2b92a9cbc2e4d0b7420a27224968580b5a447f420847c975/pytest_xdist-3.8.0-py3-none-any.whl", hash = "sha256:202ca578cfeb7370784a8c33d6d05bc6e13b4f25b5053c30a152269fd10f0b88", size = 46396, upload-time = "2025-07-01T13:30:56.632Z" }, ] +[[package]] +name = "python-dateutil" +version = "2.9.0.post0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "six" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/66/c0/0c8b6ad9f17a802ee498c46e004a0eb49bc148f2fd230864601a86dcf6db/python-dateutil-2.9.0.post0.tar.gz", hash = "sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3", size = 342432, upload-time = "2024-03-01T18:36:20.211Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" }, +] + [[package]] name = "python-dotenv" version = "1.1.1" @@ -961,6 +1624,42 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/ed/23/8da0bbe2ab9dcdd11f4f4557ccaf95c10b9811b13ecced089d43ce59c3c8/PyYAML-6.0.2-cp311-cp311-win_amd64.whl", hash = "sha256:e10ce637b18caea04431ce14fabcf5c64a1c61ec9c56b071a4b7ca131ca52d44", size = 161980, upload-time = "2024-08-06T20:32:21.273Z" }, ] +[[package]] +name = "pyzmq" +version = "27.1.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "cffi", marker = "implementation_name == 'pypy'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/04/0b/3c9baedbdf613ecaa7aa07027780b8867f57b6293b6ee50de316c9f3222b/pyzmq-27.1.0.tar.gz", hash = "sha256:ac0765e3d44455adb6ddbf4417dcce460fc40a05978c08efdf2948072f6db540", size = 281750, upload-time = "2025-09-08T23:10:18.157Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/06/5d/305323ba86b284e6fcb0d842d6adaa2999035f70f8c38a9b6d21ad28c3d4/pyzmq-27.1.0-cp311-cp311-macosx_10_15_universal2.whl", hash = "sha256:226b091818d461a3bef763805e75685e478ac17e9008f49fce2d3e52b3d58b86", size = 1333328, upload-time = "2025-09-08T23:07:45.946Z" }, + { url = "https://files.pythonhosted.org/packages/bd/a0/fc7e78a23748ad5443ac3275943457e8452da67fda347e05260261108cbc/pyzmq-27.1.0-cp311-cp311-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:0790a0161c281ca9723f804871b4027f2e8b5a528d357c8952d08cd1a9c15581", size = 908803, upload-time = "2025-09-08T23:07:47.551Z" }, + { url = "https://files.pythonhosted.org/packages/7e/22/37d15eb05f3bdfa4abea6f6d96eb3bb58585fbd3e4e0ded4e743bc650c97/pyzmq-27.1.0-cp311-cp311-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c895a6f35476b0c3a54e3eb6ccf41bf3018de937016e6e18748317f25d4e925f", size = 668836, upload-time = "2025-09-08T23:07:49.436Z" }, + { url = "https://files.pythonhosted.org/packages/b1/c4/2a6fe5111a01005fc7af3878259ce17684fabb8852815eda6225620f3c59/pyzmq-27.1.0-cp311-cp311-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5bbf8d3630bf96550b3be8e1fc0fea5cbdc8d5466c1192887bd94869da17a63e", size = 857038, upload-time = "2025-09-08T23:07:51.234Z" }, + { url = "https://files.pythonhosted.org/packages/cb/eb/bfdcb41d0db9cd233d6fb22dc131583774135505ada800ebf14dfb0a7c40/pyzmq-27.1.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:15c8bd0fe0dabf808e2d7a681398c4e5ded70a551ab47482067a572c054c8e2e", size = 1657531, upload-time = "2025-09-08T23:07:52.795Z" }, + { url = "https://files.pythonhosted.org/packages/ab/21/e3180ca269ed4a0de5c34417dfe71a8ae80421198be83ee619a8a485b0c7/pyzmq-27.1.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:bafcb3dd171b4ae9f19ee6380dfc71ce0390fefaf26b504c0e5f628d7c8c54f2", size = 2034786, upload-time = "2025-09-08T23:07:55.047Z" }, + { url = "https://files.pythonhosted.org/packages/3b/b1/5e21d0b517434b7f33588ff76c177c5a167858cc38ef740608898cd329f2/pyzmq-27.1.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:e829529fcaa09937189178115c49c504e69289abd39967cd8a4c215761373394", size = 1894220, upload-time = "2025-09-08T23:07:57.172Z" }, + { url = "https://files.pythonhosted.org/packages/03/f2/44913a6ff6941905efc24a1acf3d3cb6146b636c546c7406c38c49c403d4/pyzmq-27.1.0-cp311-cp311-win32.whl", hash = "sha256:6df079c47d5902af6db298ec92151db82ecb557af663098b92f2508c398bb54f", size = 567155, upload-time = "2025-09-08T23:07:59.05Z" }, + { url = "https://files.pythonhosted.org/packages/23/6d/d8d92a0eb270a925c9b4dd039c0b4dc10abc2fcbc48331788824ef113935/pyzmq-27.1.0-cp311-cp311-win_amd64.whl", hash = "sha256:190cbf120fbc0fc4957b56866830def56628934a9d112aec0e2507aa6a032b97", size = 633428, upload-time = "2025-09-08T23:08:00.663Z" }, + { url = "https://files.pythonhosted.org/packages/ae/14/01afebc96c5abbbd713ecfc7469cfb1bc801c819a74ed5c9fad9a48801cb/pyzmq-27.1.0-cp311-cp311-win_arm64.whl", hash = "sha256:eca6b47df11a132d1745eb3b5b5e557a7dae2c303277aa0e69c6ba91b8736e07", size = 559497, upload-time = "2025-09-08T23:08:02.15Z" }, + { url = "https://files.pythonhosted.org/packages/92/e7/038aab64a946d535901103da16b953c8c9cc9c961dadcbf3609ed6428d23/pyzmq-27.1.0-cp312-abi3-macosx_10_15_universal2.whl", hash = "sha256:452631b640340c928fa343801b0d07eb0c3789a5ffa843f6e1a9cee0ba4eb4fc", size = 1306279, upload-time = "2025-09-08T23:08:03.807Z" }, + { url = "https://files.pythonhosted.org/packages/e8/5e/c3c49fdd0f535ef45eefcc16934648e9e59dace4a37ee88fc53f6cd8e641/pyzmq-27.1.0-cp312-abi3-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:1c179799b118e554b66da67d88ed66cd37a169f1f23b5d9f0a231b4e8d44a113", size = 895645, upload-time = "2025-09-08T23:08:05.301Z" }, + { url = "https://files.pythonhosted.org/packages/f8/e5/b0b2504cb4e903a74dcf1ebae157f9e20ebb6ea76095f6cfffea28c42ecd/pyzmq-27.1.0-cp312-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3837439b7f99e60312f0c926a6ad437b067356dc2bc2ec96eb395fd0fe804233", size = 652574, upload-time = "2025-09-08T23:08:06.828Z" }, + { url = "https://files.pythonhosted.org/packages/f8/9b/c108cdb55560eaf253f0cbdb61b29971e9fb34d9c3499b0e96e4e60ed8a5/pyzmq-27.1.0-cp312-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:43ad9a73e3da1fab5b0e7e13402f0b2fb934ae1c876c51d0afff0e7c052eca31", size = 840995, upload-time = "2025-09-08T23:08:08.396Z" }, + { url = "https://files.pythonhosted.org/packages/c2/bb/b79798ca177b9eb0825b4c9998c6af8cd2a7f15a6a1a4272c1d1a21d382f/pyzmq-27.1.0-cp312-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:0de3028d69d4cdc475bfe47a6128eb38d8bc0e8f4d69646adfbcd840facbac28", size = 1642070, upload-time = "2025-09-08T23:08:09.989Z" }, + { url = "https://files.pythonhosted.org/packages/9c/80/2df2e7977c4ede24c79ae39dcef3899bfc5f34d1ca7a5b24f182c9b7a9ca/pyzmq-27.1.0-cp312-abi3-musllinux_1_2_i686.whl", hash = "sha256:cf44a7763aea9298c0aa7dbf859f87ed7012de8bda0f3977b6fb1d96745df856", size = 2021121, upload-time = "2025-09-08T23:08:11.907Z" }, + { url = "https://files.pythonhosted.org/packages/46/bd/2d45ad24f5f5ae7e8d01525eb76786fa7557136555cac7d929880519e33a/pyzmq-27.1.0-cp312-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:f30f395a9e6fbca195400ce833c731e7b64c3919aa481af4d88c3759e0cb7496", size = 1878550, upload-time = "2025-09-08T23:08:13.513Z" }, + { url = "https://files.pythonhosted.org/packages/e6/2f/104c0a3c778d7c2ab8190e9db4f62f0b6957b53c9d87db77c284b69f33ea/pyzmq-27.1.0-cp312-abi3-win32.whl", hash = "sha256:250e5436a4ba13885494412b3da5d518cd0d3a278a1ae640e113c073a5f88edd", size = 559184, upload-time = "2025-09-08T23:08:15.163Z" }, + { url = "https://files.pythonhosted.org/packages/fc/7f/a21b20d577e4100c6a41795842028235998a643b1ad406a6d4163ea8f53e/pyzmq-27.1.0-cp312-abi3-win_amd64.whl", hash = "sha256:9ce490cf1d2ca2ad84733aa1d69ce6855372cb5ce9223802450c9b2a7cba0ccf", size = 619480, upload-time = "2025-09-08T23:08:17.192Z" }, + { url = "https://files.pythonhosted.org/packages/78/c2/c012beae5f76b72f007a9e91ee9401cb88c51d0f83c6257a03e785c81cc2/pyzmq-27.1.0-cp312-abi3-win_arm64.whl", hash = "sha256:75a2f36223f0d535a0c919e23615fc85a1e23b71f40c7eb43d7b1dedb4d8f15f", size = 552993, upload-time = "2025-09-08T23:08:18.926Z" }, + { url = "https://files.pythonhosted.org/packages/4c/c6/c4dcdecdbaa70969ee1fdced6d7b8f60cfabe64d25361f27ac4665a70620/pyzmq-27.1.0-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:18770c8d3563715387139060d37859c02ce40718d1faf299abddcdcc6a649066", size = 836265, upload-time = "2025-09-08T23:09:49.376Z" }, + { url = "https://files.pythonhosted.org/packages/3e/79/f38c92eeaeb03a2ccc2ba9866f0439593bb08c5e3b714ac1d553e5c96e25/pyzmq-27.1.0-pp311-pypy311_pp73-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:ac25465d42f92e990f8d8b0546b01c391ad431c3bf447683fdc40565941d0604", size = 800208, upload-time = "2025-09-08T23:09:51.073Z" }, + { url = "https://files.pythonhosted.org/packages/49/0e/3f0d0d335c6b3abb9b7b723776d0b21fa7f3a6c819a0db6097059aada160/pyzmq-27.1.0-pp311-pypy311_pp73-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:53b40f8ae006f2734ee7608d59ed661419f087521edbfc2149c3932e9c14808c", size = 567747, upload-time = "2025-09-08T23:09:52.698Z" }, + { url = "https://files.pythonhosted.org/packages/a1/cf/f2b3784d536250ffd4be70e049f3b60981235d70c6e8ce7e3ef21e1adb25/pyzmq-27.1.0-pp311-pypy311_pp73-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f605d884e7c8be8fe1aa94e0a783bf3f591b84c24e4bc4f3e7564c82ac25e271", size = 747371, upload-time = "2025-09-08T23:09:54.563Z" }, + { url = "https://files.pythonhosted.org/packages/01/1b/5dbe84eefc86f48473947e2f41711aded97eecef1231f4558f1f02713c12/pyzmq-27.1.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:c9f7f6e13dff2e44a6afeaf2cf54cee5929ad64afaf4d40b50f93c58fc687355", size = 544862, upload-time = "2025-09-08T23:09:56.509Z" }, +] + [[package]] name = "referencing" version = "0.36.2" @@ -1173,11 +1872,16 @@ agno = [ dev = [ { name = "black", extra = ["jupyter"] }, { name = "jinja2" }, + { name = "jupyter-book" }, { name = "mypy" }, + { name = "nbsphinx" }, { name = "poethepoet" }, { name = "pytest" }, { name = "pytest-xdist" }, { name = "ruff" }, + { name = "sphinx" }, + { name = "sphinx-rtd-theme" }, + { name = "sphinx-toolbox" }, { name = "syrupy" }, { name = "toml-sort" }, { name = "types-pyyaml" }, @@ -1200,8 +1904,10 @@ requires-dist = [ { name = "jinja2", specifier = ">=3.1.6" }, { name = "jinja2", marker = "extra == 'dev'" }, { name = "joblib", specifier = ">=1.5.1" }, + { name = "jupyter-book", marker = "extra == 'dev'", specifier = "==0.15.1" }, { name = "mcp", specifier = "==1.12.3" }, { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.16.1" }, + { name = "nbsphinx", marker = "extra == 'dev'" }, { name = "overrides", specifier = ">=7.7.0,<8" }, { name = "pathspec", specifier = ">=0.12.1" }, { name = "poethepoet", marker = "extra == 'dev'", specifier = ">=0.20.0" }, @@ -1216,6 +1922,9 @@ requires-dist = [ { name = "ruamel-yaml", specifier = ">=0.18.0" }, { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.0.285" }, { name = "sensai-utils", specifier = ">=1.5.0" }, + { name = "sphinx", marker = "extra == 'dev'", specifier = "==5.0.2" }, + { name = "sphinx-rtd-theme", marker = "extra == 'dev'", specifier = ">=0.5.1" }, + { name = "sphinx-toolbox", marker = "extra == 'dev'", specifier = "==3.7.0" }, { name = "sqlalchemy", marker = "extra == 'agno'", specifier = ">=2.0.40" }, { name = "syrupy", marker = "extra == 'dev'", specifier = ">=4.9.1" }, { name = "tiktoken", specifier = ">=0.9.0" }, @@ -1227,6 +1936,15 @@ requires-dist = [ ] provides-extras = ["dev", "agno", "google"] +[[package]] +name = "setuptools" +version = "80.9.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/18/5d/3bf57dcd21979b887f014ea83c24ae194cfcd12b9e0fda66b957c69d1fca/setuptools-80.9.0.tar.gz", hash = "sha256:f36b47402ecde768dbfafc46e8e4207b4360c654f1f3bb84475f0a28628fb19c", size = 1319958, upload-time = "2025-05-27T00:56:51.443Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a3/dc/17031897dae0efacfea57dfd3a82fdd2a2aeb58e0ff71b77b87e44edc772/setuptools-80.9.0-py3-none-any.whl", hash = "sha256:062d34222ad13e0cc312a4c02d73f059e86a4acbfbdea8f8f76b28c99f306922", size = 1201486, upload-time = "2025-05-27T00:56:49.664Z" }, +] + [[package]] name = "shellingham" version = "1.5.4" @@ -1236,6 +1954,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" }, ] +[[package]] +name = "six" +version = "1.17.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/94/e7/b2c673351809dca68a0e064b6af791aa332cf192da575fd474ed7d6f16a2/six-1.17.0.tar.gz", hash = "sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81", size = 34031, upload-time = "2024-12-04T17:35:28.174Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" }, +] + [[package]] name = "smmap" version = "5.0.2" @@ -1254,6 +1981,346 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/e9/44/75a9c9421471a6c4805dbf2356f7c181a29c1879239abab1ea2cc8f38b40/sniffio-1.3.1-py3-none-any.whl", hash = "sha256:2f6da418d1f1e0fddd844478f41680e794e6051915791a034ff65e5f100525a2", size = 10235, upload-time = "2024-02-25T23:20:01.196Z" }, ] +[[package]] +name = "snowballstemmer" +version = "3.0.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/75/a7/9810d872919697c9d01295633f5d574fb416d47e535f258272ca1f01f447/snowballstemmer-3.0.1.tar.gz", hash = "sha256:6d5eeeec8e9f84d4d56b847692bacf79bc2c8e90c7f80ca4444ff8b6f2e52895", size = 105575, upload-time = "2025-05-09T16:34:51.843Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c8/78/3565d011c61f5a43488987ee32b6f3f656e7f107ac2782dd57bdd7d91d9a/snowballstemmer-3.0.1-py3-none-any.whl", hash = "sha256:6cd7b3897da8d6c9ffb968a6781fa6532dce9c3618a4b127d920dab764a19064", size = 103274, upload-time = "2025-05-09T16:34:50.371Z" }, +] + +[[package]] +name = "soupsieve" +version = "2.8" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/6d/e6/21ccce3262dd4889aa3332e5a119a3491a95e8f60939870a3a035aabac0d/soupsieve-2.8.tar.gz", hash = "sha256:e2dd4a40a628cb5f28f6d4b0db8800b8f581b65bb380b97de22ba5ca8d72572f", size = 103472, upload-time = "2025-08-27T15:39:51.78Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/14/a0/bb38d3b76b8cae341dad93a2dd83ab7462e6dbcdd84d43f54ee60a8dc167/soupsieve-2.8-py3-none-any.whl", hash = "sha256:0cc76456a30e20f5d7f2e14a98a4ae2ee4e5abdc7c5ea0aafe795f344bc7984c", size = 36679, upload-time = "2025-08-27T15:39:50.179Z" }, +] + +[[package]] +name = "sphinx" +version = "5.0.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "alabaster" }, + { name = "babel" }, + { name = "colorama", marker = "sys_platform == 'win32'" }, + { name = "docutils" }, + { name = "imagesize" }, + { name = "jinja2" }, + { name = "packaging" }, + { name = "pygments" }, + { name = "requests" }, + { name = "snowballstemmer" }, + { name = "sphinxcontrib-applehelp" }, + { name = "sphinxcontrib-devhelp" }, + { name = "sphinxcontrib-htmlhelp" }, + { name = "sphinxcontrib-jsmath" }, + { name = "sphinxcontrib-qthelp" }, + { name = "sphinxcontrib-serializinghtml" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/83/5f/0ebf0c94dffd7a848ebfeafc0d3147a784afffb44e2c6fcaeab7eadd67ad/Sphinx-5.0.2.tar.gz", hash = "sha256:b18e978ea7565720f26019c702cd85c84376e948370f1cd43d60265010e1c7b0", size = 6729086, upload-time = "2022-06-16T17:17:44.446Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/fd/a2/3139e82a7caa2fb6954d0e63db206cc60e0ad6c67ae61ef9cf87dc70ade1/Sphinx-5.0.2-py3-none-any.whl", hash = "sha256:d3e57663eed1d7c5c50895d191fdeda0b54ded6f44d5621b50709466c338d1e8", size = 3125975, upload-time = "2022-06-16T17:17:39.291Z" }, +] + +[[package]] +name = "sphinx-autodoc-typehints" +version = "1.19.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/2c/04/53d13c123a2d2ac6c5fd073a0d0a258323815650de147062a514f382f0ac/sphinx_autodoc_typehints-1.19.1.tar.gz", hash = "sha256:6c841db55e0e9be0483ff3962a2152b60e79306f4288d8c4e7e86ac84486a5ea", size = 31708, upload-time = "2022-07-31T19:26:12.126Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/57/fc/bfadc16f4046de2f0069217d7202942bf47fe004853cb59fbd3138367a60/sphinx_autodoc_typehints-1.19.1-py3-none-any.whl", hash = "sha256:9be46aeeb1b315eb5df1f3a7cb262149895d16c7d7dcd77b92513c3c3a1e85e6", size = 12493, upload-time = "2022-07-31T19:26:10.622Z" }, +] + +[[package]] +name = "sphinx-book-theme" +version = "1.0.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pydata-sphinx-theme" }, + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/be/3d/81b2d643d456e3d1bf9069836af7cc32c71e7efaa14faa5858100c9241d7/sphinx_book_theme-1.0.1.tar.gz", hash = "sha256:927b399a6906be067e49c11ef1a87472f1b1964075c9eea30fb82c64b20aedee", size = 290063, upload-time = "2023-03-31T07:13:37.536Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/8e/45/3abe359075154f4d6a8626f4b591a28cc703d7c169cef1f7b87cab1a62f7/sphinx_book_theme-1.0.1-py3-none-any.whl", hash = "sha256:d15f8248b3718a9a6be0ba617a32d1591f9fa39c614469bface777ba06a73b75", size = 396932, upload-time = "2023-03-31T07:13:35.359Z" }, +] + +[[package]] +name = "sphinx-comments" +version = "0.0.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/c0/75/5bbf29e83eaf79843180cf424d0d550bda14a1792ca51dcf79daa065ba93/sphinx-comments-0.0.3.tar.gz", hash = "sha256:00170afff27019fad08e421da1ae49c681831fb2759786f07c826e89ac94cf21", size = 7960, upload-time = "2020-08-12T00:07:31.183Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/26/97/a5c39f619375d4f81d5422377fb027075898efa6b6202c1ccf1e5bb38a32/sphinx_comments-0.0.3-py3-none-any.whl", hash = "sha256:1e879b4e9bfa641467f83e3441ac4629225fc57c29995177d043252530c21d00", size = 4591, upload-time = "2020-08-12T00:07:30.297Z" }, +] + +[[package]] +name = "sphinx-copybutton" +version = "0.5.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/fc/2b/a964715e7f5295f77509e59309959f4125122d648f86b4fe7d70ca1d882c/sphinx-copybutton-0.5.2.tar.gz", hash = "sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd", size = 23039, upload-time = "2023-04-14T08:10:22.998Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9e/48/1ea60e74949eecb12cdd6ac43987f9fd331156388dcc2319b45e2ebb81bf/sphinx_copybutton-0.5.2-py3-none-any.whl", hash = "sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e", size = 13343, upload-time = "2023-04-14T08:10:20.844Z" }, +] + +[[package]] +name = "sphinx-design" +version = "0.3.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/7b/28/0eb39f87239acf377db5f08cf2f2b27d43c3371624a4cca128dfe952aa10/sphinx_design-0.3.0.tar.gz", hash = "sha256:7183fa1fae55b37ef01bda5125a21ee841f5bbcbf59a35382be598180c4cefba", size = 2151040, upload-time = "2022-08-22T22:14:51.473Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/89/aa/9872f086a8f483f86f174d3eb03c6954b01e851e151c4ddbd5bf758a9402/sphinx_design-0.3.0-py3-none-any.whl", hash = "sha256:823c1dd74f31efb3285ec2f1254caefed29d762a40cd676f58413a1e4ed5cc96", size = 2173640, upload-time = "2022-08-22T22:14:49.5Z" }, +] + +[[package]] +name = "sphinx-external-toc" +version = "0.3.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "click" }, + { name = "pyyaml" }, + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/a9/55/84109f851bffeb93ecaa18c9d525168224038c5db633224b0e088b841c13/sphinx_external_toc-0.3.1.tar.gz", hash = "sha256:9c8ea9980ea0e57bf3ce98f6a400f9b69eb1df808f7dd796c9c8cc1873d8b355", size = 31574, upload-time = "2022-11-24T23:59:37.51Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/6a/2e/ba8e08ac97618e3f207e19297840937d4c39d77cea1aca2b8ea0a18f0bd8/sphinx_external_toc-0.3.1-py3-none-any.whl", hash = "sha256:cd93c1e7599327b2a728db12d9819068ce719c4b037ffc62e47f20ffb6310fb3", size = 26710, upload-time = "2022-11-24T23:59:34.73Z" }, +] + +[[package]] +name = "sphinx-jinja2-compat" +version = "0.4.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "jinja2" }, + { name = "markupsafe" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/43/98/43313781f29e8c6c46fec907430310172d6f207e95e4fbea9289990fbbfe/sphinx_jinja2_compat-0.4.1.tar.gz", hash = "sha256:0188f0802d42c3da72997533b55a00815659a78d3f81d4b4747b1fb15a5728e6", size = 5222, upload-time = "2025-08-06T20:06:25.824Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ce/c8/4fd58c1000d7f8f5572c507f4550d2e2d9741e500c68eb2e3da17cbe5a85/sphinx_jinja2_compat-0.4.1-py3-none-any.whl", hash = "sha256:64ca0d46f0d8029fbe69ea612793a55e6ef0113e1bba4a85d402158c09f17a14", size = 8123, upload-time = "2025-08-06T20:06:24.947Z" }, +] + +[[package]] +name = "sphinx-jupyterbook-latex" +version = "0.5.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/20/a5/7dbb8a2f4238d0c5dbed4b1fec6fcc1979571257b99620a21368674a45ef/sphinx_jupyterbook_latex-0.5.2.tar.gz", hash = "sha256:da1d3ad028f55ddbf10b9130bb9f24fc60cafb671cbd39dfd95537aafc90972e", size = 15731, upload-time = "2022-11-16T04:07:33.781Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/18/9e/23dfce036d9cd50d71fcc7da70b99b7a6ea92bd55eb4a2fc2ac8a9501dbf/sphinx_jupyterbook_latex-0.5.2-py3-none-any.whl", hash = "sha256:24de689689ddc27c736b15b91c6b9afdcdc31570938572693bb05bfff8f50758", size = 14027, upload-time = "2022-11-16T04:07:32.049Z" }, +] + +[[package]] +name = "sphinx-multitoc-numbering" +version = "0.1.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/37/1e/577bae038372885ebc34bd8c0f290295785a0250cac6528eb6d50e4b92d5/sphinx-multitoc-numbering-0.1.3.tar.gz", hash = "sha256:c9607671ac511236fa5d61a7491c1031e700e8d498c9d2418e6c61d1251209ae", size = 4542, upload-time = "2021-03-15T12:01:43.758Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ec/9f/902f2030674cd9473fdbe5a2c2dec2618c27ec853484c35f82cf8df40ece/sphinx_multitoc_numbering-0.1.3-py3-none-any.whl", hash = "sha256:33d2e707a9b2b8ad636b3d4302e658a008025106fe0474046c651144c26d8514", size = 4616, upload-time = "2021-03-15T12:01:42.419Z" }, +] + +[[package]] +name = "sphinx-prompt" +version = "1.10.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "certifi" }, + { name = "docutils" }, + { name = "idna" }, + { name = "jinja2" }, + { name = "pygments" }, + { name = "requests" }, + { name = "sphinx" }, + { name = "urllib3" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/6c/1b/ceb8d295275982121eefc8a4f0b71edf7f26c16f5bc53f4204527f173783/sphinx_prompt-1.10.1.tar.gz", hash = "sha256:2b8a18433ee3d9f2a7c4e51a768fb14c5177cce4bf0e2298ecc068a0ca9918bf", size = 5242, upload-time = "2025-08-13T09:21:35.971Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/33/23/dca289e67226222ce988f7a4a31cae0c0f4752338ead0c1e509203658080/sphinx_prompt-1.10.1-py3-none-any.whl", hash = "sha256:6cd34abbeedc14446bba76036b1821da142052f7043c5a8a3d6b84565ee54900", size = 7428, upload-time = "2025-08-13T09:21:35.192Z" }, +] + +[[package]] +name = "sphinx-rtd-theme" +version = "2.0.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "docutils" }, + { name = "sphinx" }, + { name = "sphinxcontrib-jquery" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/fe/33/2a35a9cdbfda9086bda11457bcc872173ab3565b16b6d7f6b3efaa6dc3d6/sphinx_rtd_theme-2.0.0.tar.gz", hash = "sha256:bd5d7b80622406762073a04ef8fadc5f9151261563d47027de09910ce03afe6b", size = 2785005, upload-time = "2023-11-28T04:14:03.104Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ea/46/00fda84467815c29951a9c91e3ae7503c409ddad04373e7cfc78daad4300/sphinx_rtd_theme-2.0.0-py2.py3-none-any.whl", hash = "sha256:ec93d0856dc280cf3aee9a4c9807c60e027c7f7b461b77aeffed682e68f0e586", size = 2824721, upload-time = "2023-11-28T04:13:59.589Z" }, +] + +[[package]] +name = "sphinx-tabs" +version = "3.4.7" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "docutils" }, + { name = "pygments" }, + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/6a/53/a9a91995cb365e589f413b77fc75f1c0e9b4ac61bfa8da52a779ad855cc0/sphinx-tabs-3.4.7.tar.gz", hash = "sha256:991ad4a424ff54119799ba1491701aa8130dd43509474aef45a81c42d889784d", size = 15891, upload-time = "2024-10-08T13:37:27.887Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/6b/c6/f47505b564b918a3ba60c1e99232d4942c4a7e44ecaae603e829e3d05dae/sphinx_tabs-3.4.7-py3-none-any.whl", hash = "sha256:c12d7a36fd413b369e9e9967a0a4015781b71a9c393575419834f19204bd1915", size = 9727, upload-time = "2024-10-08T13:37:26.192Z" }, +] + +[[package]] +name = "sphinx-thebe" +version = "0.2.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/19/f6/fb50e5cb37447e30caa25b1cda2734cb2a1737c2f16bb36e4c463dee583c/sphinx-thebe-0.2.1.tar.gz", hash = "sha256:f4c8c1542054f991b73fcb28c4cf21697e42aba2f83f22348c1c851b82766583", size = 8284, upload-time = "2023-01-27T09:50:26.797Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/58/1c/f4a84761862a783273bb11e4e8f36976f19d18a0ead4543663b02140a9cd/sphinx_thebe-0.2.1-py3-none-any.whl", hash = "sha256:e8af555c90acba3541fa7108ea5981ae9c4bd406b54d9a242ab054d326ab7441", size = 8287, upload-time = "2023-01-27T09:50:25.333Z" }, +] + +[[package]] +name = "sphinx-togglebutton" +version = "0.3.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "docutils" }, + { name = "setuptools" }, + { name = "sphinx" }, + { name = "wheel" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/f0/df/d151dfbbe588116e450ca7e898750cb218dca6b2e557ced8de6f9bd7242b/sphinx-togglebutton-0.3.2.tar.gz", hash = "sha256:ab0c8b366427b01e4c89802d5d078472c427fa6e9d12d521c34fa0442559dc7a", size = 8324, upload-time = "2022-07-15T12:08:50.286Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e9/18/267ce39f29d26cdc7177231428ba823fe5ca94db8c56d1bed69033b364c8/sphinx_togglebutton-0.3.2-py3-none-any.whl", hash = "sha256:9647ba7874b7d1e2d43413d8497153a85edc6ac95a3fea9a75ef9c1e08aaae2b", size = 8249, upload-time = "2022-07-15T12:08:48.8Z" }, +] + +[[package]] +name = "sphinx-toolbox" +version = "3.7.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "apeye" }, + { name = "autodocsumm" }, + { name = "beautifulsoup4" }, + { name = "cachecontrol", extra = ["filecache"] }, + { name = "dict2css" }, + { name = "docutils" }, + { name = "domdf-python-tools" }, + { name = "filelock" }, + { name = "html5lib" }, + { name = "ruamel-yaml" }, + { name = "sphinx" }, + { name = "sphinx-autodoc-typehints" }, + { name = "sphinx-jinja2-compat" }, + { name = "sphinx-prompt" }, + { name = "sphinx-tabs" }, + { name = "tabulate" }, + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/e0/12/eaad3e01a1cc46fdd0b8c7c7b8a66b35967b1a8026a0e09922bf5f060d55/sphinx_toolbox-3.7.0.tar.gz", hash = "sha256:045db70e6d73241ff0b922f2e76597e2cc4904dbabef9fc6f3a46718b0e48d51", size = 111205, upload-time = "2024-07-04T13:37:52.2Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ba/34/04a727ad0335fd5670854926a1cad2dda2957f4261b755bdcaf2e6a4473e/sphinx_toolbox-3.7.0-py3-none-any.whl", hash = "sha256:9ea800fb6b2ecc5f382ab3547b415029fe9603b0b7eeb4c15c5da77c1eb5f21a", size = 193952, upload-time = "2024-07-04T13:37:49.371Z" }, +] + +[[package]] +name = "sphinxcontrib-applehelp" +version = "2.0.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/ba/6e/b837e84a1a704953c62ef8776d45c3e8d759876b4a84fe14eba2859106fe/sphinxcontrib_applehelp-2.0.0.tar.gz", hash = "sha256:2f29ef331735ce958efa4734873f084941970894c6090408b079c61b2e1c06d1", size = 20053, upload-time = "2024-07-29T01:09:00.465Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/5d/85/9ebeae2f76e9e77b952f4b274c27238156eae7979c5421fba91a28f4970d/sphinxcontrib_applehelp-2.0.0-py3-none-any.whl", hash = "sha256:4cd3f0ec4ac5dd9c17ec65e9ab272c9b867ea77425228e68ecf08d6b28ddbdb5", size = 119300, upload-time = "2024-07-29T01:08:58.99Z" }, +] + +[[package]] +name = "sphinxcontrib-bibtex" +version = "2.5.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "docutils" }, + { name = "pybtex" }, + { name = "pybtex-docutils" }, + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/eb/54/94fbcd5eb0532eaa91580d09795c4b6c562b72d5638c2ed5b5cc31d2b1f8/sphinxcontrib-bibtex-2.5.0.tar.gz", hash = "sha256:71b42e5db0e2e284f243875326bf9936aa9a763282277d75048826fef5b00eaa", size = 113310, upload-time = "2022-08-22T13:16:46.025Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b2/17/3be04de2ed752996654895558db01a30d64759b2c7120e7692402b8d4e19/sphinxcontrib_bibtex-2.5.0-py3-none-any.whl", hash = "sha256:748f726eaca6efff7731012103417ef130ecdcc09501b4d0c54283bf5f059f76", size = 39752, upload-time = "2022-08-22T13:16:43.376Z" }, +] + +[[package]] +name = "sphinxcontrib-devhelp" +version = "2.0.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/f6/d2/5beee64d3e4e747f316bae86b55943f51e82bb86ecd325883ef65741e7da/sphinxcontrib_devhelp-2.0.0.tar.gz", hash = "sha256:411f5d96d445d1d73bb5d52133377b4248ec79db5c793ce7dbe59e074b4dd1ad", size = 12967, upload-time = "2024-07-29T01:09:23.417Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/35/7a/987e583882f985fe4d7323774889ec58049171828b58c2217e7f79cdf44e/sphinxcontrib_devhelp-2.0.0-py3-none-any.whl", hash = "sha256:aefb8b83854e4b0998877524d1029fd3e6879210422ee3780459e28a1f03a8a2", size = 82530, upload-time = "2024-07-29T01:09:21.945Z" }, +] + +[[package]] +name = "sphinxcontrib-htmlhelp" +version = "2.1.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/43/93/983afd9aa001e5201eab16b5a444ed5b9b0a7a010541e0ddfbbfd0b2470c/sphinxcontrib_htmlhelp-2.1.0.tar.gz", hash = "sha256:c9e2916ace8aad64cc13a0d233ee22317f2b9025b9cf3295249fa985cc7082e9", size = 22617, upload-time = "2024-07-29T01:09:37.889Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/0a/7b/18a8c0bcec9182c05a0b3ec2a776bba4ead82750a55ff798e8d406dae604/sphinxcontrib_htmlhelp-2.1.0-py3-none-any.whl", hash = "sha256:166759820b47002d22914d64a075ce08f4c46818e17cfc9470a9786b759b19f8", size = 98705, upload-time = "2024-07-29T01:09:36.407Z" }, +] + +[[package]] +name = "sphinxcontrib-jquery" +version = "4.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/de/f3/aa67467e051df70a6330fe7770894b3e4f09436dea6881ae0b4f3d87cad8/sphinxcontrib-jquery-4.1.tar.gz", hash = "sha256:1620739f04e36a2c779f1a131a2dfd49b2fd07351bf1968ced074365933abc7a", size = 122331, upload-time = "2023-03-14T15:01:01.944Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/76/85/749bd22d1a68db7291c89e2ebca53f4306c3f205853cf31e9de279034c3c/sphinxcontrib_jquery-4.1-py2.py3-none-any.whl", hash = "sha256:f936030d7d0147dd026a4f2b5a57343d233f1fc7b363f68b3d4f1cb0993878ae", size = 121104, upload-time = "2023-03-14T15:01:00.356Z" }, +] + +[[package]] +name = "sphinxcontrib-jsmath" +version = "1.0.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/b2/e8/9ed3830aeed71f17c026a07a5097edcf44b692850ef215b161b8ad875729/sphinxcontrib-jsmath-1.0.1.tar.gz", hash = "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8", size = 5787, upload-time = "2019-01-21T16:10:16.347Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c2/42/4c8646762ee83602e3fb3fbe774c2fac12f317deb0b5dbeeedd2d3ba4b77/sphinxcontrib_jsmath-1.0.1-py2.py3-none-any.whl", hash = "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178", size = 5071, upload-time = "2019-01-21T16:10:14.333Z" }, +] + +[[package]] +name = "sphinxcontrib-qthelp" +version = "2.0.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/68/bc/9104308fc285eb3e0b31b67688235db556cd5b0ef31d96f30e45f2e51cae/sphinxcontrib_qthelp-2.0.0.tar.gz", hash = "sha256:4fe7d0ac8fc171045be623aba3e2a8f613f8682731f9153bb2e40ece16b9bbab", size = 17165, upload-time = "2024-07-29T01:09:56.435Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/27/83/859ecdd180cacc13b1f7e857abf8582a64552ea7a061057a6c716e790fce/sphinxcontrib_qthelp-2.0.0-py3-none-any.whl", hash = "sha256:b18a828cdba941ccd6ee8445dbe72ffa3ef8cbe7505d8cd1fa0d42d3f2d5f3eb", size = 88743, upload-time = "2024-07-29T01:09:54.885Z" }, +] + +[[package]] +name = "sphinxcontrib-serializinghtml" +version = "2.0.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/3b/44/6716b257b0aa6bfd51a1b31665d1c205fb12cb5ad56de752dfa15657de2f/sphinxcontrib_serializinghtml-2.0.0.tar.gz", hash = "sha256:e9d912827f872c029017a53f0ef2180b327c3f7fd23c87229f7a8e8b70031d4d", size = 16080, upload-time = "2024-07-29T01:10:09.332Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/52/a7/d2782e4e3f77c8450f727ba74a8f12756d5ba823d81b941f1b04da9d033a/sphinxcontrib_serializinghtml-2.0.0-py3-none-any.whl", hash = "sha256:6e2cb0eef194e10c27ec0023bfeb25badbbb5868244cf5bc5bdc04e4464bf331", size = 92072, upload-time = "2024-07-29T01:10:08.203Z" }, +] + [[package]] name = "sqlalchemy" version = "2.0.41" @@ -1326,6 +2393,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/ec/9d/aef9ec5fd5a4ee2f6a96032c4eda5888c5c7cec65cef6b28c4fc37671d88/syrupy-4.9.1-py3-none-any.whl", hash = "sha256:b94cc12ed0e5e75b448255430af642516842a2374a46936dd2650cfb6dd20eda", size = 52214, upload-time = "2025-03-24T01:36:35.278Z" }, ] +[[package]] +name = "tabulate" +version = "0.9.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/ec/fe/802052aecb21e3797b8f7902564ab6ea0d60ff8ca23952079064155d1ae1/tabulate-0.9.0.tar.gz", hash = "sha256:0095b12bf5966de529c0feb1fa08671671b3368eec77d7ef7ab114be2c068b3c", size = 81090, upload-time = "2022-10-06T17:21:48.54Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/40/44/4a5f08c96eb108af5cb50b41f76142f0afa346dfa99d5296fe7202a11854/tabulate-0.9.0-py3-none-any.whl", hash = "sha256:024ca478df22e9340661486f85298cff5f6dcdba14f3813e8830015b9ed1948f", size = 35252, upload-time = "2022-10-06T17:21:44.262Z" }, +] + [[package]] name = "tenacity" version = "8.5.0" @@ -1353,6 +2429,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/6f/07/c67ad1724b8e14e2b4c8cca04b15da158733ac60136879131db05dda7c30/tiktoken-0.9.0-cp311-cp311-win_amd64.whl", hash = "sha256:11a20e67fdf58b0e2dea7b8654a288e481bb4fc0289d3ad21291f8d0849915fb", size = 893895, upload-time = "2025-02-14T06:02:22.67Z" }, ] +[[package]] +name = "tinycss2" +version = "1.4.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "webencodings" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/7a/fd/7a5ee21fd08ff70d3d33a5781c255cbe779659bd03278feb98b19ee550f4/tinycss2-1.4.0.tar.gz", hash = "sha256:10c0972f6fc0fbee87c3edb76549357415e94548c1ae10ebccdea16fb404a9b7", size = 87085, upload-time = "2024-10-24T14:58:29.895Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e6/34/ebdc18bae6aa14fbee1a08b63c015c72b64868ff7dae68808ab500c492e2/tinycss2-1.4.0-py3-none-any.whl", hash = "sha256:3a49cf47b7675da0b15d0c6e1df8df4ebd96e9394bb905a5775adb0d884c5289", size = 26610, upload-time = "2024-10-24T14:58:28.029Z" }, +] + [[package]] name = "tokenize-rt" version = "6.2.0" @@ -1383,6 +2471,25 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/bd/75/8539d011f6be8e29f339c42e633aae3cb73bffa95dd0f9adec09b9c58e85/tomlkit-0.13.3-py3-none-any.whl", hash = "sha256:c89c649d79ee40629a9fda55f8ace8c6a1b42deb912b2a8fd8d942ddadb606b0", size = 38901, upload-time = "2025-06-05T07:13:43.546Z" }, ] +[[package]] +name = "tornado" +version = "6.5.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/09/ce/1eb500eae19f4648281bb2186927bb062d2438c2e5093d1360391afd2f90/tornado-6.5.2.tar.gz", hash = "sha256:ab53c8f9a0fa351e2c0741284e06c7a45da86afb544133201c5cc8578eb076a0", size = 510821, upload-time = "2025-08-08T18:27:00.78Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/f6/48/6a7529df2c9cc12efd2e8f5dd219516184d703b34c06786809670df5b3bd/tornado-6.5.2-cp39-abi3-macosx_10_9_universal2.whl", hash = "sha256:2436822940d37cde62771cff8774f4f00b3c8024fe482e16ca8387b8a2724db6", size = 442563, upload-time = "2025-08-08T18:26:42.945Z" }, + { url = "https://files.pythonhosted.org/packages/f2/b5/9b575a0ed3e50b00c40b08cbce82eb618229091d09f6d14bce80fc01cb0b/tornado-6.5.2-cp39-abi3-macosx_10_9_x86_64.whl", hash = "sha256:583a52c7aa94ee046854ba81d9ebb6c81ec0fd30386d96f7640c96dad45a03ef", size = 440729, upload-time = "2025-08-08T18:26:44.473Z" }, + { url = "https://files.pythonhosted.org/packages/1b/4e/619174f52b120efcf23633c817fd3fed867c30bff785e2cd5a53a70e483c/tornado-6.5.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b0fe179f28d597deab2842b86ed4060deec7388f1fd9c1b4a41adf8af058907e", size = 444295, upload-time = "2025-08-08T18:26:46.021Z" }, + { url = "https://files.pythonhosted.org/packages/95/fa/87b41709552bbd393c85dd18e4e3499dcd8983f66e7972926db8d96aa065/tornado-6.5.2-cp39-abi3-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:b186e85d1e3536d69583d2298423744740986018e393d0321df7340e71898882", size = 443644, upload-time = "2025-08-08T18:26:47.625Z" }, + { url = "https://files.pythonhosted.org/packages/f9/41/fb15f06e33d7430ca89420283a8762a4e6b8025b800ea51796ab5e6d9559/tornado-6.5.2-cp39-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e792706668c87709709c18b353da1f7662317b563ff69f00bab83595940c7108", size = 443878, upload-time = "2025-08-08T18:26:50.599Z" }, + { url = "https://files.pythonhosted.org/packages/11/92/fe6d57da897776ad2e01e279170ea8ae726755b045fe5ac73b75357a5a3f/tornado-6.5.2-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:06ceb1300fd70cb20e43b1ad8aaee0266e69e7ced38fa910ad2e03285009ce7c", size = 444549, upload-time = "2025-08-08T18:26:51.864Z" }, + { url = "https://files.pythonhosted.org/packages/9b/02/c8f4f6c9204526daf3d760f4aa555a7a33ad0e60843eac025ccfd6ff4a93/tornado-6.5.2-cp39-abi3-musllinux_1_2_i686.whl", hash = "sha256:74db443e0f5251be86cbf37929f84d8c20c27a355dd452a5cfa2aada0d001ec4", size = 443973, upload-time = "2025-08-08T18:26:53.625Z" }, + { url = "https://files.pythonhosted.org/packages/ae/2d/f5f5707b655ce2317190183868cd0f6822a1121b4baeae509ceb9590d0bd/tornado-6.5.2-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:b5e735ab2889d7ed33b32a459cac490eda71a1ba6857b0118de476ab6c366c04", size = 443954, upload-time = "2025-08-08T18:26:55.072Z" }, + { url = "https://files.pythonhosted.org/packages/e8/59/593bd0f40f7355806bf6573b47b8c22f8e1374c9b6fd03114bd6b7a3dcfd/tornado-6.5.2-cp39-abi3-win32.whl", hash = "sha256:c6f29e94d9b37a95013bb669616352ddb82e3bfe8326fccee50583caebc8a5f0", size = 445023, upload-time = "2025-08-08T18:26:56.677Z" }, + { url = "https://files.pythonhosted.org/packages/c7/2a/f609b420c2f564a748a2d80ebfb2ee02a73ca80223af712fca591386cafb/tornado-6.5.2-cp39-abi3-win_amd64.whl", hash = "sha256:e56a5af51cc30dd2cae649429af65ca2f6571da29504a07995175df14c18f35f", size = 445427, upload-time = "2025-08-08T18:26:57.91Z" }, + { url = "https://files.pythonhosted.org/packages/5e/4f/e1f65e8f8c76d73658b33d33b81eed4322fb5085350e4328d5c956f0c8f9/tornado-6.5.2-cp39-abi3-win_arm64.whl", hash = "sha256:d6c33dc3672e3a1f3618eb63b7ef4683a7688e7b9e6e8f0d9aa5726360a004af", size = 444456, upload-time = "2025-08-08T18:26:59.207Z" }, +] + [[package]] name = "tqdm" version = "4.67.1" @@ -1461,6 +2568,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/17/69/cd203477f944c353c31bade965f880aa1061fd6bf05ded0726ca845b6ff7/typing_inspection-0.4.1-py3-none-any.whl", hash = "sha256:389055682238f53b04f7badcb49b989835495a96700ced5dab2d8feae4b26f51", size = 14552, upload-time = "2025-05-21T18:55:22.152Z" }, ] +[[package]] +name = "uc-micro-py" +version = "1.0.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/91/7a/146a99696aee0609e3712f2b44c6274566bc368dfe8375191278045186b8/uc-micro-py-1.0.3.tar.gz", hash = "sha256:d321b92cff673ec58027c04015fcaa8bb1e005478643ff4a500882eaab88c48a", size = 6043, upload-time = "2024-02-09T16:52:01.654Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/37/87/1f677586e8ac487e29672e4b17455758fce261de06a0d086167bb760361a/uc_micro_py-1.0.3-py3-none-any.whl", hash = "sha256:db1dffff340817673d7b466ec86114a9dc0e9d4d9b5ba229d9d60e5c12600cd5", size = 6229, upload-time = "2024-02-09T16:52:00.371Z" }, +] + [[package]] name = "urllib3" version = "2.5.0" @@ -1492,6 +2608,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/fd/84/fd2ba7aafacbad3c4201d395674fc6348826569da3c0937e75505ead3528/wcwidth-0.2.13-py2.py3-none-any.whl", hash = "sha256:3da69048e4540d84af32131829ff948f1e022c1c6bdb8d6102117aac784f6859", size = 34166, upload-time = "2024-01-06T02:10:55.763Z" }, ] +[[package]] +name = "webencodings" +version = "0.5.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/0b/02/ae6ceac1baeda530866a85075641cec12989bd8d31af6d5ab4a3e8c92f47/webencodings-0.5.1.tar.gz", hash = "sha256:b36a1c245f2d304965eb4e0a82848379241dc04b865afcc4aab16748587e1923", size = 9721, upload-time = "2017-04-05T20:21:34.189Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/f4/24/2a3e3df732393fed8b3ebf2ec078f05546de641fe1b667ee316ec1dcf3b7/webencodings-0.5.1-py2.py3-none-any.whl", hash = "sha256:a0af1213f3c2226497a97e2b3aa01a7e4bee4f403f95be16fc9acd2947514a78", size = 11774, upload-time = "2017-04-05T20:21:32.581Z" }, +] + [[package]] name = "websockets" version = "15.0.1" @@ -1523,3 +2648,21 @@ sdist = { url = "https://files.pythonhosted.org/packages/9f/69/83029f1f6300c5fb2 wheels = [ { url = "https://files.pythonhosted.org/packages/52/24/ab44c871b0f07f491e5d2ad12c9bd7358e527510618cb1b803a88e986db1/werkzeug-3.1.3-py3-none-any.whl", hash = "sha256:54b78bf3716d19a65be4fceccc0d1d7b89e608834989dfae50ea87564639213e", size = 224498, upload-time = "2024-11-08T15:52:16.132Z" }, ] + +[[package]] +name = "wheel" +version = "0.45.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/8a/98/2d9906746cdc6a6ef809ae6338005b3f21bb568bea3165cfc6a243fdc25c/wheel-0.45.1.tar.gz", hash = "sha256:661e1abd9198507b1409a20c02106d9670b2576e916d58f520316666abca6729", size = 107545, upload-time = "2024-11-23T00:18:23.513Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/0b/2c/87f3254fd8ffd29e4c02732eee68a83a1d3c346ae39bc6822dcbcb697f2b/wheel-0.45.1-py3-none-any.whl", hash = "sha256:708e7481cc80179af0e556bbf0cc00b8444c7321e2700b8d8580231d13017248", size = 72494, upload-time = "2024-11-23T00:18:21.207Z" }, +] + +[[package]] +name = "zipp" +version = "3.23.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/e3/02/0f2892c661036d50ede074e376733dca2ae7c6eb617489437771209d4180/zipp-3.23.0.tar.gz", hash = "sha256:a07157588a12518c9d4034df3fbbee09c814741a33ff63c05fa29d26a2404166", size = 25547, upload-time = "2025-06-08T17:06:39.4Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/2e/54/647ade08bf0db230bfea292f893923872fd20be6ac6f53b2b936ba839d75/zipp-3.23.0-py3-none-any.whl", hash = "sha256:071652d6115ed432f5ce1d34c336c0adfd6a884660d1e9712a256d3d3bd4b14e", size = 10276, upload-time = "2025-06-08T17:06:38.034Z" }, +] From faf3441ab267d6cf7dc9215a3594647f06f5dad5 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Fri, 7 Nov 2025 18:00:00 +0100 Subject: [PATCH 02/21] Add content from README in docs structure --- .gitignore | 3 + CHANGELOG.md | 2 +- README.md | 6 +- docs/01-about/000_intro.md | 2 + docs/01-about/010_llm-integration.md | 19 + docs/01-about/020_programming-languages.md | 45 +++ docs/01-about/030_serena-in-action.md | 14 + .../040_comparison-to-other-agents.md | 61 ++++ docs/01-about/050_acknowledgements.md | 54 +++ docs/02-usage/000_intro.md | 3 + docs/02-usage/010_quick-start.md | 345 ++++++++++++++++++ docs/02-usage/020_detailed-usage.md | 206 +++++++++++ docs/03-special-guides/000_intro.md | 3 + docs/{ => 03-special-guides}/custom_agent.md | 0 .../scala_setup_guide_for_serena.md | 0 .../serena_on_chatgpt.md | 0 docs/_config.yml | 1 + docs/create_toc.py | 5 +- docs/index.md | 14 + 19 files changed, 777 insertions(+), 6 deletions(-) create mode 100644 docs/01-about/000_intro.md create mode 100644 docs/01-about/010_llm-integration.md create mode 100644 docs/01-about/020_programming-languages.md create mode 100644 docs/01-about/030_serena-in-action.md create mode 100644 docs/01-about/040_comparison-to-other-agents.md create mode 100644 docs/01-about/050_acknowledgements.md create mode 100644 docs/02-usage/000_intro.md create mode 100644 docs/02-usage/010_quick-start.md create mode 100644 docs/02-usage/020_detailed-usage.md create mode 100644 docs/03-special-guides/000_intro.md rename docs/{ => 03-special-guides}/custom_agent.md (100%) rename docs/{ => 03-special-guides}/scala_setup_guide_for_serena.md (100%) rename docs/{ => 03-special-guides}/serena_on_chatgpt.md (100%) create mode 100644 docs/index.md diff --git a/.gitignore b/.gitignore index f71c7714..27086cc8 100644 --- a/.gitignore +++ b/.gitignore @@ -215,6 +215,9 @@ pylint.html # Cache is in .multilspy **/.multilspy/** +# temporary and backup files +*.bak +*.tmp tmp/ .serena/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 544fa9d6..ba9a8211 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,7 +23,7 @@ Status of the `main` branch. Changes prior to the next official version change w * **Add support for Fortran** via fortls language server (requires `pip install fortls`) * **Add support for Julia** via LanguageServer.jl * **Add support for Haskell** via Haskell Language Server (HLS) with automatic discovery via ghcup, stack, or system PATH; supports both Stack and Cabal projects - * **Add support for Scala** via Metals language server (requires some [manual setup](docs/scala_setup_guide_for_serena.md)) + * **Add support for Scala** via Metals language server (requires some [manual setup](docs/03-special-guides/scala_setup_guide_for_serena.md)) * **Add support for Elm** via @elm-tooling/elm-language-server (automatically downloads if not installed; requires Elm compiler) * **Add support for Perl** via Perl::LanguageServer with LSP integration for .pl, .pm, and .t files * **Add support for AL (Application Language)** for Microsoft Dynamics 365 Business Central development. Requires VS Code AL extension (ms-dynamics-smb.al). diff --git a/README.md b/README.md index 444ea91b..4c220ba8 100644 --- a/README.md +++ b/README.md @@ -43,8 +43,8 @@ In general, Serena can be integrated with an LLM in several ways: * IDEs like VSCode, Cursor or IntelliJ, * Extensions like Cline or Roo Code * Local clients like [OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp), [Jan](https://jan.ai/docs/mcp-examples/browser/browserbase#enable-mcp), [Agno](https://docs.agno.com/introduction/playground) and others -* by using [mcpo to connect it to ChatGPT](docs/serena_on_chatgpt.md) or other clients that don't support MCP but do support tool calling via OpenAPI. -* by incorporating Serena's tools into an agent framework of your choice, as illustrated [here](docs/custom_agent.md). +* by using [mcpo to connect it to ChatGPT](docs/03-special-guides/serena_on_chatgpt.md) or other clients that don't support MCP but do support tool calling via OpenAPI. +* by incorporating Serena's tools into an agent framework of your choice, as illustrated [here](docs/03-special-guides/custom_agent.md). Serena's tool implementation is decoupled from the framework-specific code and can thus easily be adapted to any agent framework. ### Serena in Action @@ -188,7 +188,7 @@ Serena can be used in various ways, below you will find instructions for selecte * For coding with Claude, we recommend using Serena through [Claude Code](#claude-code) or [Claude Desktop](#claude-desktop). You can also use Serena in most other [terminal-based clients](#other-terminal-based-clients). * If you want a GUI experience outside an IDE, you can use one of the many [local GUIs](#local-guis-and-frameworks) that support MCP servers. - You can also connect Serena to many web clients (including ChatGPT) using [mcpo](docs/serena_on_chatgpt.md). + You can also connect Serena to many web clients (including ChatGPT) using [mcpo](docs/03-special-guides/serena_on_chatgpt.md). * If you want to use Serena integrated in your IDE, see the section on [other MCP clients](#other-mcp-clients---cline-roo-code-cursor-windsurf-etc). * You can use Serena as a library for building your own applications. We try to keep the public API stable, but you should still expect breaking changes and pin Serena to a fixed version if you use it as a dependency. diff --git a/docs/01-about/000_intro.md b/docs/01-about/000_intro.md new file mode 100644 index 00000000..388ef411 --- /dev/null +++ b/docs/01-about/000_intro.md @@ -0,0 +1,2 @@ +# About Serena + diff --git a/docs/01-about/010_llm-integration.md b/docs/01-about/010_llm-integration.md new file mode 100644 index 00000000..2b2ac314 --- /dev/null +++ b/docs/01-about/010_llm-integration.md @@ -0,0 +1,19 @@ +## LLM Integration + +Serena provides the necessary [tools](#list-of-tools) for coding workflows, but an LLM is required to do the actual work, +orchestrating tool use. + +For example, **supercharge the performance of Claude Code** with a [one-line shell command](#claude-code). + +In general, Serena can be integrated with an LLM in several ways: + +* by using the **model context protocol (MCP)**. + Serena provides an MCP server which integrates with + * Claude Code and Claude Desktop, + * Terminal-based clients like Codex, Gemini-CLI, Qwen3-Coder, rovodev, OpenHands CLI and others, + * IDEs like VSCode, Cursor or IntelliJ, + * Extensions like Cline or Roo Code + * Local clients like [OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp), [Jan](https://jan.ai/docs/mcp-examples/browser/browserbase#enable-mcp), [Agno](https://docs.agno.com/introduction/playground) and others +* by using [mcpo to connect it to ChatGPT](docs/serena_on_chatgpt.md) or other clients that don't support MCP but do support tool calling via OpenAPI. +* by incorporating Serena's tools into an agent framework of your choice, as illustrated [here](docs/custom_agent.md). + Serena's tool implementation is decoupled from the framework-specific code and can thus easily be adapted to any agent framework. diff --git a/docs/01-about/020_programming-languages.md b/docs/01-about/020_programming-languages.md new file mode 100644 index 00000000..3212dba7 --- /dev/null +++ b/docs/01-about/020_programming-languages.md @@ -0,0 +1,45 @@ +## Programming Language Support & Semantic Analysis Capabilities + +Serena's semantic code analysis capabilities build on **language servers** using the widely implemented +language server protocol (LSP). The LSP provides a set of versatile code querying +and editing functionalities based on symbolic understanding of the code. +Equipped with these capabilities, Serena discovers and edits code just like a seasoned developer +making use of an IDE's capabilities would. +Serena can efficiently find the right context and do the right thing even in very large and +complex projects! So not only is it free and open-source, it frequently achieves better results +than existing solutions that charge a premium. + +Language servers provide support for a wide range of programming languages. +With Serena, we provide direct, out-of-the-box support for: + +* Python +* TypeScript/Javascript +* PHP (uses Intelephense LSP; set `INTELEPHENSE_LICENSE_KEY` environment variable for premium features) +* Go (requires installation of gopls) +* R (requires installation of the `languageserver` R package) +* Rust (requires [rustup](https://rustup.rs/) - uses rust-analyzer from your toolchain) +* C/C++ (you may experience issues with finding references, we are working on it) +* Zig (requires installation of ZLS - Zig Language Server) +* C# +* Ruby (by default, uses [ruby-lsp](https://github.com/Shopify/ruby-lsp), specify ruby_solargraph as your language to use the previous solargraph based implementation) +* Swift +* Kotlin (uses the pre-alpha [official kotlin LS](https://github.com/Kotlin/kotlin-lsp), some issues may appear) +* Java (_Note_: startup is slow, initial startup especially so. There may be issues with java on macos and linux, we are working on it.) +* Clojure +* Dart +* Bash +* Lua (automatically downloads lua-language-server if not installed) +* Nix (requires nixd installation) +* Elixir (requires installation of NextLS and Elixir; **Windows not supported**) +* Elm (automatically downloads elm-language-server if not installed; requires Elm compiler) +* Scala (requires some [manual setup](docs/scala_setup_guide_for_serena.md); uses Metals LSP) +* Erlang (requires installation of beam and [erlang_ls](https://github.com/erlang-ls/erlang_ls), experimental, might be slow or hang) +* Perl (requires installation of Perl::LanguageServer) +* Fortran (requires installation of fortls: `pip install fortls`) +* Haskell (automatically locates HLS via ghcup, stack, or system PATH; supports Stack and Cabal projects) +* Julia +* AL +* Markdown (must be explicitly specified via `--language markdown` when generating project config, primarily useful for documentation-heavy projects) + +Support for further languages can easily be added by providing a shallow adapter for a new language server implementation, +see Serena's [memory on that](.serena/memories/adding_new_language_support_guide.md). diff --git a/docs/01-about/030_serena-in-action.md b/docs/01-about/030_serena-in-action.md new file mode 100644 index 00000000..31b26fba --- /dev/null +++ b/docs/01-about/030_serena-in-action.md @@ -0,0 +1,14 @@ +## Serena in Action + +### Demonstration 1: Efficient Operation in Claude Code + +A demonstration of Serena efficiently retrieving and editing code within Claude Code, thereby saving tokens and time. Efficient operations are not only useful for saving costs, but also for generally improving the generated code's quality. This effect may be less pronounced in very small projects, but often becomes of crucial importance in larger ones. + +https://github.com/user-attachments/assets/ab78ebe0-f77d-43cc-879a-cc399efefd87 + +### Demonstration 2: Serena in Claude Desktop + +A demonstration of Serena implementing a small feature for itself (a better log GUI) with Claude Desktop. +Note how Serena's tools enable Claude to find and edit the right symbols. + +https://github.com/user-attachments/assets/6eaa9aa1-610d-4723-a2d6-bf1e487ba753 diff --git a/docs/01-about/040_comparison-to-other-agents.md b/docs/01-about/040_comparison-to-other-agents.md new file mode 100644 index 00000000..b65085a0 --- /dev/null +++ b/docs/01-about/040_comparison-to-other-agents.md @@ -0,0 +1,61 @@ +## Comparison with Other Coding Agents + +To our knowledge, Serena is the first fully-featured coding agent where the +entire functionality +is available through an MCP server, thus not requiring API keys or +subscriptions. + +### Subscription-Based Coding Agents + +Many prominent subscription-based coding agents are parts of IDEs like +Windsurf, Cursor and VSCode. +Serena's functionality is similar to Cursor's Agent, Windsurf's Cascade or +VSCode's agent mode. + +Serena has the advantage of not requiring a subscription. +A potential disadvantage is that it +is not directly integrated into an IDE, so the inspection of newly written code +is not as seamless. + +More technical differences are: + +* Serena is not bound to a specific IDE or CLI. + Serena's MCP server can be used with any MCP client (including some IDEs), + and the Agno-based agent provides additional ways of applying its functionality. +* Serena is not bound to a specific large language model or API. +* Serena navigates and edits code using a language server, so it has a symbolic + understanding of the code. + IDE-based tools often use a RAG-based or purely text-based approach, which is often + less powerful, especially for large codebases. +* Serena is open-source and has a small codebase, so it can be easily extended + and modified. + +### API-Based Coding Agents + +An alternative to subscription-based agents are API-based agents like Claude +Code, Cline, Aider, Roo Code and others, where the usage costs map directly +to the API costs of the underlying LLM. +Some of them (like Cline) can even be included in IDEs as an extension. +They are often very powerful and their main downside are the (potentially very +high) API costs. + +Serena itself can be used as an API-based agent (see the section on Agno above). +We have not yet written a CLI tool or a +dedicated IDE extension for Serena (and there is probably no need for the latter, as +Serena can already be used with any IDE that supports MCP servers). +If there is demand for a Serena as a CLI tool like Claude Code, we will +consider writing one. + +The main difference between Serena and other API-based agents is that Serena can +also be used as an MCP server, thus not requiring +an API key and bypassing the API costs. This is a unique feature of Serena. + +### Other MCP-Based Coding Agents + +There are other MCP servers designed for coding, like [DesktopCommander](https://github.com/wonderwhy-er/DesktopCommanderMCP) and +[codemcp](https://github.com/ezyang/codemcp). +However, to the best of our knowledge, none of them provide semantic code +retrieval and editing tools; they rely purely on text-based analysis. +It is the integration of language servers and the MCP that makes Serena unique +and so powerful for challenging coding tasks, especially in the context of +larger codebases. \ No newline at end of file diff --git a/docs/01-about/050_acknowledgements.md b/docs/01-about/050_acknowledgements.md new file mode 100644 index 00000000..e2e024da --- /dev/null +++ b/docs/01-about/050_acknowledgements.md @@ -0,0 +1,54 @@ +## Acknowledgements + +### Sponsors + +We are very grateful to our [sponsors](https://github.com/sponsors/oraios) who help us drive Serena's development. The core team +(the founders of [Oraios AI](https://oraios-ai.de/)) put in a lot of work in order to turn Serena into a useful open source project. +So far, there is no business model behind this project, and sponsors are our only source of income from it. + +Sponsors help us dedicating more time to the project, managing contributions, and working on larger features (like better tooling based on more advanced +LSP features, VSCode integration, debugging via the DAP, and several others). +If you find this project useful to your work, or would like to accelerate the development of Serena, consider becoming a sponsor. + +We are proud to announce that the Visual Studio Code team, together with Microsoft’s Open Source Programs Office and GitHub Open Source +have decided to sponsor Serena with a one-time contribution! + +

+ Visual Studio Code sponsor logo +

+ +### Community Contributions + +A significant part of Serena, especially support for various languages, was contributed by the open source community. +We are very grateful for the many contributors who made this possible and who played an important role in making Serena +what it is today. + +### Technologies +We built Serena on top of multiple existing open-source technologies, the most important ones being: + +1. [multilspy](https://github.com/microsoft/multilspy). + A library which wraps language server implementations and adapts them for interaction via Python + and which provided the basis for our library Solid-LSP (src/solidlsp). + Solid-LSP provides pure synchronous LSP calls and extends the original library with the symbolic logic + that Serena required. +2. [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk) +3. [Agno](https://github.com/agno-agi/agno) and + the associated [agent-ui](https://github.com/agno-agi/agent-ui), + which we use to allow Serena to work with any model, beyond the ones + supporting the MCP. +4. All the language servers that we use through Solid-LSP. + +Without these projects, Serena would not have been possible (or would have been significantly more difficult to build). + +## Customizing and Extending Serena + +It is straightforward to extend Serena's AI functionality with your own ideas. +Simply implement a new tool by subclassing +`serena.agent.Tool` and implement the `apply` method with a signature +that matches the tool's requirements. +Once implemented, `SerenaAgent` will automatically have access to the new tool. + +It is also relatively straightforward to add [support for a new programming language](/.serena/memories/adding_new_language_support_guide.md). + +We look forward to seeing what the community will come up with! +For details on contributing, see [contributing guidelines](/CONTRIBUTING.md). \ No newline at end of file diff --git a/docs/02-usage/000_intro.md b/docs/02-usage/000_intro.md new file mode 100644 index 00000000..067ae050 --- /dev/null +++ b/docs/02-usage/000_intro.md @@ -0,0 +1,3 @@ +# Usage + +This section provides usage instructions. diff --git a/docs/02-usage/010_quick-start.md b/docs/02-usage/010_quick-start.md new file mode 100644 index 00000000..5a7c31b0 --- /dev/null +++ b/docs/02-usage/010_quick-start.md @@ -0,0 +1,345 @@ +## Quick Start + +Serena can be used in various ways, below you will find instructions for selected integrations. + +* For coding with Claude, we recommend using Serena through [Claude Code](#claude-code) or [Claude Desktop](#claude-desktop). You can also use Serena in most other [terminal-based clients](#other-terminal-based-clients). +* If you want a GUI experience outside an IDE, you can use one of the many [local GUIs](#local-guis-and-frameworks) that support MCP servers. + You can also connect Serena to many web clients (including ChatGPT) using [mcpo](docs/serena_on_chatgpt.md). +* If you want to use Serena integrated in your IDE, see the section on [other MCP clients](#other-mcp-clients---cline-roo-code-cursor-windsurf-etc). +* You can use Serena as a library for building your own applications. We try to keep the public API stable, but you should still + expect breaking changes and pin Serena to a fixed version if you use it as a dependency. + +Serena is managed by `uv`, so you will need to [install it](https://docs.astral.sh/uv/getting-started/installation/). + +### Running the Serena MCP Server + +You have several options for running the MCP server, which are explained in the subsections below. + +#### Usage + +The typical usage involves the client (Claude Code, Claude Desktop, etc.) running +the MCP server as a subprocess (using stdio communication), +so the client needs to be provided with the command to run the MCP server. +(Alternatively, you can run the MCP server in Streamable HTTP or SSE mode and tell your client +how to connect to it.) + +Note that no matter how you run the MCP server, Serena will, by default, start a small web-based dashboard on localhost that will display logs and allow shutting down the +MCP server (since many clients fail to clean up processes correctly). +This and other settings can be adjusted in the [configuration](#configuration) and/or by providing [command-line arguments](#command-line-arguments). + +#### Using uvx + +`uvx` can be used to run the latest version of Serena directly from the repository, without an explicit local installation. + +```shell +uvx --from git+https://github.com/oraios/serena serena start-mcp-server +``` + +Explore the CLI to see some of the customization options that serena provides (more info on them below). + +#### Local Installation + +1. Clone the repository and change into it. + + ```shell + git clone https://github.com/oraios/serena + cd serena + ``` + +2. Optionally edit the configuration file in your home directory with + + ```shell + uv run serena config edit + ``` + + If you just want the default config, you can skip this part, and a config file will be created when you first run Serena. +3. Run the server with `uv`: + + ```shell + uv run serena start-mcp-server + ``` + + When running from outside the serena installation directory, be sure to pass it, i.e., use + + ```shell + uv run --directory /abs/path/to/serena serena start-mcp-server + ``` + +#### Using Docker (Experimental) + +⚠️ Docker support is currently experimental with several limitations. Please read the [Docker documentation](DOCKER.md) for important caveats before using it. + +You can run the Serena MCP server directly via docker as follows, +assuming that the projects you want to work on are all located in `/path/to/your/projects`: + +```shell +docker run --rm -i --network host -v /path/to/your/projects:/workspaces/projects ghcr.io/oraios/serena:latest serena start-mcp-server --transport stdio +``` + +Replace `/path/to/your/projects` with the absolute path to your projects directory. The Docker approach provides: + +* Better security isolation for shell command execution +* No need to install language servers and dependencies locally +* Consistent environment across different systems + +Alternatively, use docker compose with the `compose.yml` file provided in the repository. + +See the [Docker documentation](DOCKER.md) for detailed setup instructions, configuration options, and known limitations. + +#### Using Nix + +If you are using Nix and [have enabled the `nix-command` and `flakes` features](https://nixos.wiki/wiki/flakes), you can run Serena using the following command: + +```bash +nix run github:oraios/serena -- start-mcp-server --transport stdio +``` + +You can also install Serena by referencing this repo (`github:oraios/serena`) and using it in your Nix flake. The package is exported as `serena`. + +#### Streamable HTTP Mode + +ℹ️ Note that MCP servers which use stdio as a protocol are somewhat unusual as far as client/server architectures go, as the server +necessarily has to be started by the client in order for communication to take place via the server's standard input/output stream. +In other words, you do not need to start the server yourself. The client application (e.g. Claude Desktop) takes care of this and +therefore needs to be configured with a launch command. + +When using instead the *Streamable HTTP* mode, you control the server lifecycle yourself, +i.e. you start the server and provide the client with the URL to connect to it. + +Simply provide `start-mcp-server` with the `--transport streamable-http` option and optionally provide the port. +For example, to run the Serena MCP server in Streamable HTTP mode on port 9121 using a local installation, +you would run this command from the Serena directory, + +```shell +uv run serena start-mcp-server --transport streamable-http --port 9121 +``` + +and then configure your client to connect to `http://localhost:9121/mcp`. + +ℹ️ Note that SSE transport is supported as well, but its use is discouraged. +Use Streamable HTTP instead. + +#### Command-Line Arguments + +The Serena MCP server supports a wide range of additional command-line options, including the option to run in Streamable HTTP or SSE mode +and to adapt Serena to various [contexts and modes of operation](#modes-and-contexts). + +Run with parameter `--help` to get a list of available options. + +### Configuration + +Serena is very flexible in terms of configuration. While for most users, the default configurations will work, +you can fully adjust it to your needs by editing a few yaml files. You can disable tools, change Serena's instructions +(what we denote as the `system_prompt`), adjust the output of tools that just provide a prompt, and even adjust tool descriptions. + +Serena is configured in four places: + +1. The `serena_config.yml` for general settings that apply to all clients and projects. + It is located in your user directory under `.serena/serena_config.yml`. + If you do not explicitly create the file, it will be auto-generated when you first run Serena. + You can edit it directly or use + + ```shell + uvx --from git+https://github.com/oraios/serena serena config edit + ``` + + (or use the `--directory` command version). +2. In the arguments passed to the `start-mcp-server` in your client's config (see below), + which will apply to all sessions started by the respective client. In particular, the [context](#contexts) parameter + should be set appropriately for Serena to be best adjusted to existing tools and capabilities of your client. + See for a detailed explanation. You can override all entries from the `serena_config.yml` through command line arguments. +3. In the `.serena/project.yml` file within your project. This will hold project-level configuration that is used whenever + that project is activated. This file will be autogenerated when you first use Serena on that project, but you can also + generate it explicitly with + + ```shell + uvx --from git+https://github.com/oraios/serena serena project generate-yml + ``` + + (or use the `--directory` command version). +4. Through the context and modes. Explore the [modes and contexts](#modes-and-contexts) section for more details. + +After the initial setup, continue with one of the sections below, depending on how you +want to use Serena. + +### Project Activation & Indexing + +If you are mostly working with the same project, you can configure to always activate it at startup +by passing `--project ` to the `start-mcp-server` command in your client's MCP config. +This is especially useful for clients which configure MCP servers on a per-project basis, like Claude Code. + +Otherwise, the recommended way is to just ask the LLM to activate a project by providing it an absolute path to, or, +in case the project was activated in the past, by its name. The default project name is the directory name. + +* "Activate the project /path/to/my_project" +* "Activate the project my_project" + +All projects that have been activated will be automatically added to your `serena_config.yml`, and for each +project, the file `.serena/project.yml` will be generated. You can adjust the latter, e.g., by changing the name +(which you refer to during the activation) or other options. Make sure to not have two different projects with the +same name. + +ℹ️ For larger projects, we recommend that you index your project to accelerate Serena's tools; otherwise the first +tool application may be very slow. +To do so, run this from the project directory (or pass the path to the project as an argument): + +```shell +uvx --from git+https://github.com/oraios/serena serena project index +``` + +(or use the `--directory` command version). + +### Configuring Popular Clients + +#### Claude Code + +Serena is a great way to make Claude Code both cheaper and more powerful! + +From your project directory, add serena with a command like this, + +```shell +claude mcp add serena -- --context ide-assistant --project "$(pwd)" +``` + +where `` is your way of [running the Serena MCP server](#running-the-serena-mcp-server). +For example, when using `uvx`, you would run + +```shell +claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project "$(pwd)" +``` + +ℹ️ Serena comes with an instruction text, and Claude needs to read it to properly use Serena's tools. +As of version `v1.0.52`, claude code reads the instructions of the MCP server, so this **is handled automatically**. +If you are using an older version, or if Claude fails to read the instructions, you can ask it explicitly +to "read Serena's initial instructions" or run `/mcp__serena__initial_instructions` to load the instruction text. +If you want to make use of that, you will have to enable the corresponding tool explicitly by adding `initial_instructions` to the `included_optional_tools` +in your config. +Note that you may have to make Claude read the instructions when you start a new conversation and after any compacting operation to ensure Claude remains properly configured to use Serena's tools. + +#### Codex + +Serena works with OpenAI's Codex CLI out of the box, but you have to use the `codex` context for it to work properly. (The technical reason is that Codex doesn't fully support the MCP specifications, so some massaging of tools is required.). + +Unlike Claude Code, in Codex you add an MCP server globally and not per project. Add the following to +`~/.codex/config.toml` (create the file if it does not exist): + +```toml +[mcp_servers.serena] +command = "uvx" +args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"] +``` + +After codex has started, you need to activate the project, which you can do by saying: + +"Activate the current dir as project using serena" + +> If you don't activate the project, you will not be able to use Serena's tools! + +That's it! Have a look at `~/.codex/log/codex-tui.log` to see if any errors occurred. + +The Serena dashboard will run if you have not disabled it in the configuration, but due to Codex's sandboxing the webbrowser +may not open automatically. You can open it manually by going to `http://localhost:24282/dashboard/index.html` (or a higher port, if +that was already taken). + +> Codex will often show the tools as `failed` even though they are successfully executed. This is not a problem, seems to be a bug in Codex. Despite the error message, everything works as expected. + +#### Other Terminal-Based Clients + +There are many terminal-based coding assistants that support MCP servers, such as [Codex](https://github.com/openai/codex?tab=readme-ov-file#model-context-protocol-mcp), +[Gemini-CLI](https://github.com/google-gemini/gemini-cli), [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder), +[rovodev](https://community.atlassian.com/forums/Rovo-for-Software-Teams-Beta/Introducing-Rovo-Dev-CLI-AI-Powered-Development-in-your-terminal/ba-p/3043623), +the [OpenHands CLI](https://docs.all-hands.dev/usage/how-to/cli-mode) and [opencode](https://github.com/sst/opencode). + +They generally benefit from the symbolic tools provided by Serena. You might want to customize some aspects of Serena +by writing your own context, modes or prompts to adjust it to your workflow, to other MCP servers you are using, and to +the client's internal capabilities. + +#### Claude Desktop + +For [Claude Desktop](https://claude.ai/download) (available for Windows and macOS), go to File / Settings / Developer / MCP Servers / Edit Config, +which will let you open the JSON file `claude_desktop_config.json`. +Add the `serena` MCP server configuration, using a [run command](#running-the-serena-mcp-server) depending on your setup. + +* local installation: + + ```json + { + "mcpServers": { + "serena": { + "command": "/abs/path/to/uv", + "args": ["run", "--directory", "/abs/path/to/serena", "serena", "start-mcp-server"] + } + } + } + ``` + +* uvx: + + ```json + { + "mcpServers": { + "serena": { + "command": "/abs/path/to/uvx", + "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"] + } + } + } + ``` + +* docker: + + ```json + { + "mcpServers": { + "serena": { + "command": "docker", + "args": ["run", "--rm", "-i", "--network", "host", "-v", "/path/to/your/projects:/workspaces/projects", "ghcr.io/oraios/serena:latest", "serena", "start-mcp-server", "--transport", "stdio"] + } + } + } + ``` + +If you are using paths containing backslashes for paths on Windows +(note that you can also just use forward slashes), be sure to escape them correctly (`\\`). + +That's it! Save the config and then restart Claude Desktop. You are ready for activating your first project. + +ℹ️ You can further customize the run command using additional arguments (see [above](#command-line-arguments)). + +Note: on Windows and macOS there are official Claude Desktop applications by Anthropic, for Linux there is an [open-source +community version](https://github.com/aaddrick/claude-desktop-debian). + +⚠️ Be sure to fully quit the Claude Desktop application, as closing Claude will just minimize it to the system tray – at least on Windows. + +⚠️ Some clients may leave behind zombie processes. You will have to find and terminate them manually then. +With Serena, you can activate the [dashboard](#serenas-logs-the-dashboard-and-gui-tool) to prevent unnoted processes and also use the dashboard +for shutting down Serena. + +After restarting, you should see Serena's tools in your chat interface (notice the small hammer icon). + +For more information on MCP servers with Claude Desktop, see [the official quick start guide](https://modelcontextprotocol.io/quickstart/user). + +#### MCP Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) + +Being an MCP Server, Serena can be included in any MCP Client. The same configuration as above, +perhaps with small client-specific modifications, should work. Most of the popular +existing coding assistants (IDE extensions or VSCode-like IDEs) support connections +to MCP Servers. It is **recommended to use the `ide-assistant` context** for these integrations by adding `"--context", "ide-assistant"` to the `args` in your MCP client's configuration. Including Serena generally boosts their performance +by providing them tools for symbolic operations. + +In this case, the billing for the usage continues to be controlled by the client of your choice +(unlike with the Claude Desktop client). But you may still want to use Serena through such an approach, +e.g., for one of the following reasons: + +1. You are already using a coding assistant (say Cline or Cursor) and just want to make it more powerful. +2. You are on Linux and don't want to use the [community-created Claude Desktop](https://github.com/aaddrick/claude-desktop-debian). +3. You want tighter integration of Serena into your IDE and don't mind paying for that. + +#### Local GUIs and Frameworks + +Over the last months, several technologies have emerged that allow you to run a powerful local GUI +and connect it to an MCP server. They will work with Serena out of the box. +Some of the leading open source GUI technologies offering this are +[Jan](https://jan.ai/docs/mcp), [OpenHands](https://github.com/All-Hands-AI/OpenHands/), +[OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp) and [Agno](https://docs.agno.com/introduction/playground). +They allow combining Serena with almost any LLM (including locally running ones) and offer various other integrations. diff --git a/docs/02-usage/020_detailed-usage.md b/docs/02-usage/020_detailed-usage.md new file mode 100644 index 00000000..2fe63e08 --- /dev/null +++ b/docs/02-usage/020_detailed-usage.md @@ -0,0 +1,206 @@ +## Detailed Usage and Recommendations + +### Tool Execution + +Serena combines tools for semantic code retrieval with editing capabilities and shell execution. +Serena's behavior can be further customized through [Modes and Contexts](#modes-and-contexts). +Find the complete list of tools [below](#full-list-of-tools). + +The use of all tools is generally recommended, as this allows Serena to provide the most value: +Only by executing shell commands (in particular, tests) can Serena identify and correct mistakes +autonomously. + +#### Shell Execution and Editing Tools + +Many clients have their own shell execution tool, and by default Serena's shell tool will be disabled in them +(e.g., when using the `ide-assistant` or `codex` context). However, when using Serena through something like +Claude Desktop or ChatGPT, it is recommended to enable Serena's `execute_shell_command` tool to allow +agentic behavior. + +It should be noted that the `execute_shell_command` tool allows for arbitrary code execution. +When using Serena as an MCP Server, clients will typically ask the user for permission +before executing a tool, so as long as the user inspects execution parameters beforehand, +this should not be a problem. +However, if you have concerns, you can choose to disable certain commands in your project's configuration file. +If you only want to use Serena purely for analyzing code and suggesting implementations +without modifying the codebase, you can enable read-only mode by setting `read_only: true` in your project configuration file. +This will automatically disable all editing tools and prevent any modifications to your codebase while still +allowing all analysis and exploration capabilities. + +In general, be sure to back up your work and use a version control system in order to avoid +losing any work. + +### Modes and Contexts + +Serena's behavior and toolset can be adjusted using contexts and modes. +These allow for a high degree of customization to best suit your workflow and the environment Serena is operating in. + +#### Contexts + +A context defines the general environment in which Serena is operating. +It influences the initial system prompt and the set of available tools. +A context is set at startup when launching Serena (e.g., via CLI options for an MCP server or in the agent script) and cannot be changed during an active session. + +Serena comes with pre-defined contexts: + +* `desktop-app`: Tailored for use with desktop applications like Claude Desktop. This is the default. +* `agent`: Designed for scenarios where Serena acts as a more autonomous agent, for example, when used with Agno. +* `ide-assistant`: Optimized for integration into IDEs like VSCode, Cursor, or Cline, focusing on in-editor coding assistance. + Choose the context that best matches the type of integration you are using. + +When launching Serena, specify the context using `--context `. +Note that for cases where parameter lists are specified (e.g. Claude Desktop), you must add two parameters to the list. + +If you are using a local server (such as Llama.cpp) which requires you to use OpenAI-compatible tool descriptions, use context `oaicompat-agent` instead of `agent`. + +#### Modes + +Modes further refine Serena's behavior for specific types of tasks or interaction styles. Multiple modes can be active simultaneously, allowing you to combine their effects. Modes influence the system prompt and can also alter the set of available tools by excluding certain ones. + +Examples of built-in modes include: + +* `planning`: Focuses Serena on planning and analysis tasks. +* `editing`: Optimizes Serena for direct code modification tasks. +* `interactive`: Suitable for a conversational, back-and-forth interaction style. +* `one-shot`: Configures Serena for tasks that should be completed in a single response, often used with `planning` for generating reports or initial plans. +* `no-onboarding`: Skips the initial onboarding process if it's not needed for a particular session. +* `onboarding`: (Usually triggered automatically) Focuses on the project onboarding process. + +Modes can be set at startup (similar to contexts) but can also be _switched dynamically_ during a session. You can instruct the LLM to use the `switch_modes` tool to activate a different set of modes (e.g., "switch to planning and one-shot modes"). + +When launching Serena, specify modes using `--mode `; multiple modes can be specified, e.g. `--mode planning --mode no-onboarding`. + +:warning: **Mode Compatibility**: While you can combine modes, some may be semantically incompatible (e.g., `interactive` and `one-shot`). Serena currently does not prevent incompatible combinations; it is up to the user to choose sensible mode configurations. + +#### Customization + +You can create your own contexts and modes to precisely tailor Serena to your needs in two ways: + +* You can use Serena's CLI to manage modes and contexts. Check out + + ```shell + uvx --from git+https://github.com/oraios/serena serena mode --help + ``` + + and + + ```shell + uvx --from git+https://github.com/oraios/serena serena context --help + ``` + + _NOTE_: Custom contexts/modes are simply YAML files in `/.serena`, they are automatically registered and available for use by their name (filename without the `.yml` extension). If you don't want to use Serena's CLI, you can create and manage them in any way you see fit. +* **Using external YAML files**: When starting Serena, you can also provide an absolute path to a custom `.yml` file for a context or mode. + +This customization allows for deep integration and adaptation of Serena to specific project requirements or personal preferences. + +### Onboarding and Memories + +By default, Serena will perform an **onboarding process** when +it is started for the first time for a project. +The goal of the onboarding is for Serena to get familiar with the project +and to store memories, which it can then draw upon in future interactions. +If an LLM should fail to complete the onboarding and does not actually write the +respective memories to disk, you may need to ask it to do so explicitly. + +The onboarding will usually read a lot of content from the project, thus filling +up the context. It can therefore be advisable to switch to another conversation +once the onboarding is complete. +After the onboarding, we recommend that you have a quick look at the memories and, +if necessary, edit them or add additional ones. + +**Memories** are files stored in `.serena/memories/` in the project directory, +which the agent can choose to read in subsequent interactions. +Feel free to read and adjust them as needed; you can also add new ones manually. +Every file in the `.serena/memories/` directory is a memory file. +Whenever Serena starts working on a project, the list of memories is +provided, and the agent can decide to read them. +We found that memories can significantly improve the user experience with Serena. + +### Prepare Your Project + +#### Structure Your Codebase + +Serena uses the code structure for finding, reading and editing code. This means that it will +work well with well-structured code but may perform poorly on fully unstructured one (like a "God class" +with enormous, non-modular functions). +Furthermore, for languages that are not statically typed, type annotations are highly beneficial. + +#### Start from a Clean State + +It is best to start a code generation task from a clean git state. Not only will +this make it easier for you to inspect the changes, but also the model itself will +have a chance of seeing what it has changed by calling `git diff` and thereby +correct itself or continue working in a followup conversation if needed. + +:warning: **Important**: since Serena will write to files using the system-native line endings +and it might want to look at the git diff, it is important to +set `git config core.autocrlf` to `true` on Windows. +With `git config core.autocrlf` set to `false` on Windows, you may end up with huge diffs +only due to line endings. It is generally a good idea to globally enable this git setting on Windows: + +```shell +git config --global core.autocrlf true +``` + +#### Logging, Linting, and Automated Tests + +Serena can successfully complete tasks in an _agent loop_, where it iteratively +acquires information, performs actions, and reflects on the results. +However, Serena cannot use a debugger; it must rely on the results of program executions, +linting results, and test results to assess the correctness of its actions. +Therefore, software that is designed to meaningful interpretable outputs (e.g. log messages) +and that has a good test coverage is much easier to work with for Serena. + +We generally recommend to start an editing task from a state where all linting checks and tests pass. + +### Prompting Strategies + +We found that it is often a good idea to spend some time conceptualizing and planning a task +before actually implementing it, especially for non-trivial task. This helps both in achieving +better results and in increasing the feeling of control and staying in the loop. You can +make a detailed plan in one session, where Serena may read a lot of your code to build up the context, +and then continue with the implementation in another (potentially after creating suitable memories). + +### Running Out of Context + +For long and complicated tasks, or tasks where Serena has read a lot of content, you +may come close to the limits of context tokens. In that case, it is often a good idea to continue +in a new conversation. Serena has a dedicated tool to create a summary of the current state +of the progress and all relevant info for continuing it. You can request to create this summary and +write it to a memory. Then, in a new conversation, you can just ask Serena to read the memory and +continue with the task. In our experience, this worked really well. On the up-side, since in a +single session there is no summarization involved, Serena does not usually get lost (unlike some +other agents that summarize under the hood), and it is also instructed to occasionally check whether +it's on the right track. + +Moreover, Serena is instructed to be frugal with context +(e.g., to not read bodies of code symbols unnecessarily), +but we found that Claude is not always very good in being frugal (Gemini seemed better at it). +You can explicitly instruct it to not read the bodies if you know that it's not needed. + +### Serena's Logs: The Dashboard and GUI Tool + +Serena provides two convenient ways of accessing the logs of the current session: + +* via the **web-based dashboard** (enabled by default) + + This is supported on all platforms. + By default, it will be accessible at `http://localhost:24282/dashboard/index.html`, + but a higher port may be used if the default port is unavailable/multiple instances are running. + +* via the **GUI tool** (disabled by default) + + This is mainly supported on Windows, but it may also work on Linux; macOS is unsupported. + +Both can be enabled, configured or disabled in Serena's configuration file (`serena_config.yml`, see above). +If enabled, they will automatically be opened as soon as the Serena agent/MCP server is started. +The web dashboard will display usage statistics of Serena's tools if you set `record_tool_usage_stats: True` in your config. + +In addition to viewing logs, both tools allow to shut down the Serena agent. +This function is provided, because clients like Claude Desktop may fail to terminate the MCP server subprocess +when they themselves are closed. + +### Serena and GIT worktrees +[git-worktree](https://git-scm.com/docs/git-worktree) can be an excellent way to parallelize your work. More on this in [Anthropic: Run parallel Claude Code sessions with Git worktrees](https://docs.claude.com/en/docs/claude-code/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees). + +When it comes to serena AND git-worktree AND larger projects (that take longer to index), the recommended way is to COPY your `$ORIG_PROJECT/.serena/cache` to `$GIT_WORKTREE/.serena/cache`. After you have performed pre-indexing of your project described in [Project Activation & Indexing](#project-activation--indexing) section. To avoid having to re-index per each git work tree that you create. diff --git a/docs/03-special-guides/000_intro.md b/docs/03-special-guides/000_intro.md new file mode 100644 index 00000000..d2d34716 --- /dev/null +++ b/docs/03-special-guides/000_intro.md @@ -0,0 +1,3 @@ +# Special Guides + +This section contains special guides for certain topics that require more in-depth explanations. \ No newline at end of file diff --git a/docs/custom_agent.md b/docs/03-special-guides/custom_agent.md similarity index 100% rename from docs/custom_agent.md rename to docs/03-special-guides/custom_agent.md diff --git a/docs/scala_setup_guide_for_serena.md b/docs/03-special-guides/scala_setup_guide_for_serena.md similarity index 100% rename from docs/scala_setup_guide_for_serena.md rename to docs/03-special-guides/scala_setup_guide_for_serena.md diff --git a/docs/serena_on_chatgpt.md b/docs/03-special-guides/serena_on_chatgpt.md similarity index 100% rename from docs/serena_on_chatgpt.md rename to docs/03-special-guides/serena_on_chatgpt.md diff --git a/docs/_config.yml b/docs/_config.yml index 98a645c1..b12f6610 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -104,6 +104,7 @@ sphinx: local_extensions : # A list of local extensions to load by sphinx specified by "name: path" items recursive_update : false # A boolean indicating whether to overwrite the Sphinx config (true) or recursively update (false) config : # key-value pairs to directly over-ride the Sphinx configuration + master_doc: "01-about/000_intro.md" autodoc_typehints_format: "short" autodoc_member_order: "bysource" autoclass_content: "both" diff --git a/docs/create_toc.py b/docs/create_toc.py index 3e1779cd..39490e88 100644 --- a/docs/create_toc.py +++ b/docs/create_toc.py @@ -2,7 +2,8 @@ import os from pathlib import Path # This script provides a platform-independent way of making the jupyter-book call (used in pyproject.toml) -toc_file = Path(__file__).parent / "_toc.yml" -cmd = f"jupyter-book toc from-project docs -e .rst -e .md -e .ipynb >{toc_file}" +folder = Path(__file__).parent +toc_file = folder / "_toc.yml" +cmd = f"jupyter-book toc from-project docs -e .rst -e .md -e .ipynb >{toc_file}" print(cmd) os.system(cmd) diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..a0c18522 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,14 @@ +# Welcome to Serena! + +* Serena is a powerful **coding agent toolkit** capable of turning an LLM into a fully-featured agent that works + **directly on your codebase**. + Unlike most other tools, it is not tied to an LLM, framework or an interface, making it easy to use it in a variety of ways. +* Serena provides essential **semantic code retrieval and editing tools** that are akin to an IDE's capabilities, + extracting code entities at the symbol level and exploiting relational structure. + When combined with an existing coding agent, these tools greatly enhance (token) efficiency. +* Serena is **free & open-source**, enhancing the capabilities of LLMs you already have access to free of charge. + +Therefore, you can think of Serena as providing IDE-like tools to your LLM/coding agent. +With it, the agent no longer needs to read entire files, perform grep-like searches or string replacements to find and +edit the right code. +Instead, it can use code-centred tools like `find_symbol`, `find_referencing_symbols` and `insert_after_symbol`. From c2b456a862b6260975135ba0f0b9ffc6ac7bf570 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Fri, 7 Nov 2025 20:10:34 +0100 Subject: [PATCH 03/21] Restructure docs, improve texts (particular for Running Serena) --- docs/02-usage/000_intro.md | 10 +- docs/02-usage/010_prerequisites.md | 4 + docs/02-usage/010_quick-start.md | 345 ------------------ docs/02-usage/020_running.md | 156 ++++++++ docs/02-usage/030_clients.md | 154 ++++++++ docs/02-usage/040_workflow.md | 51 +++ docs/02-usage/050_configuration.md | 77 ++++ ...etailed-usage.md => 999_detailed-usage.md} | 65 ---- 8 files changed, 451 insertions(+), 411 deletions(-) create mode 100644 docs/02-usage/010_prerequisites.md delete mode 100644 docs/02-usage/010_quick-start.md create mode 100644 docs/02-usage/020_running.md create mode 100644 docs/02-usage/030_clients.md create mode 100644 docs/02-usage/040_workflow.md create mode 100644 docs/02-usage/050_configuration.md rename docs/02-usage/{020_detailed-usage.md => 999_detailed-usage.md} (65%) diff --git a/docs/02-usage/000_intro.md b/docs/02-usage/000_intro.md index 067ae050..110763f1 100644 --- a/docs/02-usage/000_intro.md +++ b/docs/02-usage/000_intro.md @@ -1,3 +1,11 @@ # Usage -This section provides usage instructions. +Serena can be used in various ways. +In this section, you will find general usage instructions as well as concrete instructions for selected integrations. + +* For coding with Claude, we recommend using Serena through [Claude Code](#claude-code) or [Claude Desktop](#claude-desktop). You can also use Serena in most other [terminal-based clients](#other-terminal-based-clients). +* If you want a GUI experience outside an IDE, you can use one of the many [local GUIs](#local-guis-and-frameworks) that support MCP servers. + You can also connect Serena to many web clients (including ChatGPT) using [mcpo](docs/serena_on_chatgpt.md). +* If you want to use Serena integrated in your IDE, see the section on [other MCP clients](#other-mcp-clients---cline-roo-code-cursor-windsurf-etc). +* You can use Serena as a library for building your own applications. We try to keep the public API stable, but you should still + expect breaking changes and pin Serena to a fixed version if you use it as a dependency. diff --git a/docs/02-usage/010_prerequisites.md b/docs/02-usage/010_prerequisites.md new file mode 100644 index 00000000..e6265e67 --- /dev/null +++ b/docs/02-usage/010_prerequisites.md @@ -0,0 +1,4 @@ +## Install uv + +Serena is managed by `uv`, and the only prerequesite for using Serena is to have `uv` installed. +To install it, follow the instructions [here](https://docs.astral.sh/uv/getting-started/installation/). \ No newline at end of file diff --git a/docs/02-usage/010_quick-start.md b/docs/02-usage/010_quick-start.md deleted file mode 100644 index 5a7c31b0..00000000 --- a/docs/02-usage/010_quick-start.md +++ /dev/null @@ -1,345 +0,0 @@ -## Quick Start - -Serena can be used in various ways, below you will find instructions for selected integrations. - -* For coding with Claude, we recommend using Serena through [Claude Code](#claude-code) or [Claude Desktop](#claude-desktop). You can also use Serena in most other [terminal-based clients](#other-terminal-based-clients). -* If you want a GUI experience outside an IDE, you can use one of the many [local GUIs](#local-guis-and-frameworks) that support MCP servers. - You can also connect Serena to many web clients (including ChatGPT) using [mcpo](docs/serena_on_chatgpt.md). -* If you want to use Serena integrated in your IDE, see the section on [other MCP clients](#other-mcp-clients---cline-roo-code-cursor-windsurf-etc). -* You can use Serena as a library for building your own applications. We try to keep the public API stable, but you should still - expect breaking changes and pin Serena to a fixed version if you use it as a dependency. - -Serena is managed by `uv`, so you will need to [install it](https://docs.astral.sh/uv/getting-started/installation/). - -### Running the Serena MCP Server - -You have several options for running the MCP server, which are explained in the subsections below. - -#### Usage - -The typical usage involves the client (Claude Code, Claude Desktop, etc.) running -the MCP server as a subprocess (using stdio communication), -so the client needs to be provided with the command to run the MCP server. -(Alternatively, you can run the MCP server in Streamable HTTP or SSE mode and tell your client -how to connect to it.) - -Note that no matter how you run the MCP server, Serena will, by default, start a small web-based dashboard on localhost that will display logs and allow shutting down the -MCP server (since many clients fail to clean up processes correctly). -This and other settings can be adjusted in the [configuration](#configuration) and/or by providing [command-line arguments](#command-line-arguments). - -#### Using uvx - -`uvx` can be used to run the latest version of Serena directly from the repository, without an explicit local installation. - -```shell -uvx --from git+https://github.com/oraios/serena serena start-mcp-server -``` - -Explore the CLI to see some of the customization options that serena provides (more info on them below). - -#### Local Installation - -1. Clone the repository and change into it. - - ```shell - git clone https://github.com/oraios/serena - cd serena - ``` - -2. Optionally edit the configuration file in your home directory with - - ```shell - uv run serena config edit - ``` - - If you just want the default config, you can skip this part, and a config file will be created when you first run Serena. -3. Run the server with `uv`: - - ```shell - uv run serena start-mcp-server - ``` - - When running from outside the serena installation directory, be sure to pass it, i.e., use - - ```shell - uv run --directory /abs/path/to/serena serena start-mcp-server - ``` - -#### Using Docker (Experimental) - -⚠️ Docker support is currently experimental with several limitations. Please read the [Docker documentation](DOCKER.md) for important caveats before using it. - -You can run the Serena MCP server directly via docker as follows, -assuming that the projects you want to work on are all located in `/path/to/your/projects`: - -```shell -docker run --rm -i --network host -v /path/to/your/projects:/workspaces/projects ghcr.io/oraios/serena:latest serena start-mcp-server --transport stdio -``` - -Replace `/path/to/your/projects` with the absolute path to your projects directory. The Docker approach provides: - -* Better security isolation for shell command execution -* No need to install language servers and dependencies locally -* Consistent environment across different systems - -Alternatively, use docker compose with the `compose.yml` file provided in the repository. - -See the [Docker documentation](DOCKER.md) for detailed setup instructions, configuration options, and known limitations. - -#### Using Nix - -If you are using Nix and [have enabled the `nix-command` and `flakes` features](https://nixos.wiki/wiki/flakes), you can run Serena using the following command: - -```bash -nix run github:oraios/serena -- start-mcp-server --transport stdio -``` - -You can also install Serena by referencing this repo (`github:oraios/serena`) and using it in your Nix flake. The package is exported as `serena`. - -#### Streamable HTTP Mode - -ℹ️ Note that MCP servers which use stdio as a protocol are somewhat unusual as far as client/server architectures go, as the server -necessarily has to be started by the client in order for communication to take place via the server's standard input/output stream. -In other words, you do not need to start the server yourself. The client application (e.g. Claude Desktop) takes care of this and -therefore needs to be configured with a launch command. - -When using instead the *Streamable HTTP* mode, you control the server lifecycle yourself, -i.e. you start the server and provide the client with the URL to connect to it. - -Simply provide `start-mcp-server` with the `--transport streamable-http` option and optionally provide the port. -For example, to run the Serena MCP server in Streamable HTTP mode on port 9121 using a local installation, -you would run this command from the Serena directory, - -```shell -uv run serena start-mcp-server --transport streamable-http --port 9121 -``` - -and then configure your client to connect to `http://localhost:9121/mcp`. - -ℹ️ Note that SSE transport is supported as well, but its use is discouraged. -Use Streamable HTTP instead. - -#### Command-Line Arguments - -The Serena MCP server supports a wide range of additional command-line options, including the option to run in Streamable HTTP or SSE mode -and to adapt Serena to various [contexts and modes of operation](#modes-and-contexts). - -Run with parameter `--help` to get a list of available options. - -### Configuration - -Serena is very flexible in terms of configuration. While for most users, the default configurations will work, -you can fully adjust it to your needs by editing a few yaml files. You can disable tools, change Serena's instructions -(what we denote as the `system_prompt`), adjust the output of tools that just provide a prompt, and even adjust tool descriptions. - -Serena is configured in four places: - -1. The `serena_config.yml` for general settings that apply to all clients and projects. - It is located in your user directory under `.serena/serena_config.yml`. - If you do not explicitly create the file, it will be auto-generated when you first run Serena. - You can edit it directly or use - - ```shell - uvx --from git+https://github.com/oraios/serena serena config edit - ``` - - (or use the `--directory` command version). -2. In the arguments passed to the `start-mcp-server` in your client's config (see below), - which will apply to all sessions started by the respective client. In particular, the [context](#contexts) parameter - should be set appropriately for Serena to be best adjusted to existing tools and capabilities of your client. - See for a detailed explanation. You can override all entries from the `serena_config.yml` through command line arguments. -3. In the `.serena/project.yml` file within your project. This will hold project-level configuration that is used whenever - that project is activated. This file will be autogenerated when you first use Serena on that project, but you can also - generate it explicitly with - - ```shell - uvx --from git+https://github.com/oraios/serena serena project generate-yml - ``` - - (or use the `--directory` command version). -4. Through the context and modes. Explore the [modes and contexts](#modes-and-contexts) section for more details. - -After the initial setup, continue with one of the sections below, depending on how you -want to use Serena. - -### Project Activation & Indexing - -If you are mostly working with the same project, you can configure to always activate it at startup -by passing `--project ` to the `start-mcp-server` command in your client's MCP config. -This is especially useful for clients which configure MCP servers on a per-project basis, like Claude Code. - -Otherwise, the recommended way is to just ask the LLM to activate a project by providing it an absolute path to, or, -in case the project was activated in the past, by its name. The default project name is the directory name. - -* "Activate the project /path/to/my_project" -* "Activate the project my_project" - -All projects that have been activated will be automatically added to your `serena_config.yml`, and for each -project, the file `.serena/project.yml` will be generated. You can adjust the latter, e.g., by changing the name -(which you refer to during the activation) or other options. Make sure to not have two different projects with the -same name. - -ℹ️ For larger projects, we recommend that you index your project to accelerate Serena's tools; otherwise the first -tool application may be very slow. -To do so, run this from the project directory (or pass the path to the project as an argument): - -```shell -uvx --from git+https://github.com/oraios/serena serena project index -``` - -(or use the `--directory` command version). - -### Configuring Popular Clients - -#### Claude Code - -Serena is a great way to make Claude Code both cheaper and more powerful! - -From your project directory, add serena with a command like this, - -```shell -claude mcp add serena -- --context ide-assistant --project "$(pwd)" -``` - -where `` is your way of [running the Serena MCP server](#running-the-serena-mcp-server). -For example, when using `uvx`, you would run - -```shell -claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project "$(pwd)" -``` - -ℹ️ Serena comes with an instruction text, and Claude needs to read it to properly use Serena's tools. -As of version `v1.0.52`, claude code reads the instructions of the MCP server, so this **is handled automatically**. -If you are using an older version, or if Claude fails to read the instructions, you can ask it explicitly -to "read Serena's initial instructions" or run `/mcp__serena__initial_instructions` to load the instruction text. -If you want to make use of that, you will have to enable the corresponding tool explicitly by adding `initial_instructions` to the `included_optional_tools` -in your config. -Note that you may have to make Claude read the instructions when you start a new conversation and after any compacting operation to ensure Claude remains properly configured to use Serena's tools. - -#### Codex - -Serena works with OpenAI's Codex CLI out of the box, but you have to use the `codex` context for it to work properly. (The technical reason is that Codex doesn't fully support the MCP specifications, so some massaging of tools is required.). - -Unlike Claude Code, in Codex you add an MCP server globally and not per project. Add the following to -`~/.codex/config.toml` (create the file if it does not exist): - -```toml -[mcp_servers.serena] -command = "uvx" -args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"] -``` - -After codex has started, you need to activate the project, which you can do by saying: - -"Activate the current dir as project using serena" - -> If you don't activate the project, you will not be able to use Serena's tools! - -That's it! Have a look at `~/.codex/log/codex-tui.log` to see if any errors occurred. - -The Serena dashboard will run if you have not disabled it in the configuration, but due to Codex's sandboxing the webbrowser -may not open automatically. You can open it manually by going to `http://localhost:24282/dashboard/index.html` (or a higher port, if -that was already taken). - -> Codex will often show the tools as `failed` even though they are successfully executed. This is not a problem, seems to be a bug in Codex. Despite the error message, everything works as expected. - -#### Other Terminal-Based Clients - -There are many terminal-based coding assistants that support MCP servers, such as [Codex](https://github.com/openai/codex?tab=readme-ov-file#model-context-protocol-mcp), -[Gemini-CLI](https://github.com/google-gemini/gemini-cli), [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder), -[rovodev](https://community.atlassian.com/forums/Rovo-for-Software-Teams-Beta/Introducing-Rovo-Dev-CLI-AI-Powered-Development-in-your-terminal/ba-p/3043623), -the [OpenHands CLI](https://docs.all-hands.dev/usage/how-to/cli-mode) and [opencode](https://github.com/sst/opencode). - -They generally benefit from the symbolic tools provided by Serena. You might want to customize some aspects of Serena -by writing your own context, modes or prompts to adjust it to your workflow, to other MCP servers you are using, and to -the client's internal capabilities. - -#### Claude Desktop - -For [Claude Desktop](https://claude.ai/download) (available for Windows and macOS), go to File / Settings / Developer / MCP Servers / Edit Config, -which will let you open the JSON file `claude_desktop_config.json`. -Add the `serena` MCP server configuration, using a [run command](#running-the-serena-mcp-server) depending on your setup. - -* local installation: - - ```json - { - "mcpServers": { - "serena": { - "command": "/abs/path/to/uv", - "args": ["run", "--directory", "/abs/path/to/serena", "serena", "start-mcp-server"] - } - } - } - ``` - -* uvx: - - ```json - { - "mcpServers": { - "serena": { - "command": "/abs/path/to/uvx", - "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"] - } - } - } - ``` - -* docker: - - ```json - { - "mcpServers": { - "serena": { - "command": "docker", - "args": ["run", "--rm", "-i", "--network", "host", "-v", "/path/to/your/projects:/workspaces/projects", "ghcr.io/oraios/serena:latest", "serena", "start-mcp-server", "--transport", "stdio"] - } - } - } - ``` - -If you are using paths containing backslashes for paths on Windows -(note that you can also just use forward slashes), be sure to escape them correctly (`\\`). - -That's it! Save the config and then restart Claude Desktop. You are ready for activating your first project. - -ℹ️ You can further customize the run command using additional arguments (see [above](#command-line-arguments)). - -Note: on Windows and macOS there are official Claude Desktop applications by Anthropic, for Linux there is an [open-source -community version](https://github.com/aaddrick/claude-desktop-debian). - -⚠️ Be sure to fully quit the Claude Desktop application, as closing Claude will just minimize it to the system tray – at least on Windows. - -⚠️ Some clients may leave behind zombie processes. You will have to find and terminate them manually then. -With Serena, you can activate the [dashboard](#serenas-logs-the-dashboard-and-gui-tool) to prevent unnoted processes and also use the dashboard -for shutting down Serena. - -After restarting, you should see Serena's tools in your chat interface (notice the small hammer icon). - -For more information on MCP servers with Claude Desktop, see [the official quick start guide](https://modelcontextprotocol.io/quickstart/user). - -#### MCP Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) - -Being an MCP Server, Serena can be included in any MCP Client. The same configuration as above, -perhaps with small client-specific modifications, should work. Most of the popular -existing coding assistants (IDE extensions or VSCode-like IDEs) support connections -to MCP Servers. It is **recommended to use the `ide-assistant` context** for these integrations by adding `"--context", "ide-assistant"` to the `args` in your MCP client's configuration. Including Serena generally boosts their performance -by providing them tools for symbolic operations. - -In this case, the billing for the usage continues to be controlled by the client of your choice -(unlike with the Claude Desktop client). But you may still want to use Serena through such an approach, -e.g., for one of the following reasons: - -1. You are already using a coding assistant (say Cline or Cursor) and just want to make it more powerful. -2. You are on Linux and don't want to use the [community-created Claude Desktop](https://github.com/aaddrick/claude-desktop-debian). -3. You want tighter integration of Serena into your IDE and don't mind paying for that. - -#### Local GUIs and Frameworks - -Over the last months, several technologies have emerged that allow you to run a powerful local GUI -and connect it to an MCP server. They will work with Serena out of the box. -Some of the leading open source GUI technologies offering this are -[Jan](https://jan.ai/docs/mcp), [OpenHands](https://github.com/All-Hands-AI/OpenHands/), -[OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp) and [Agno](https://docs.agno.com/introduction/playground). -They allow combining Serena with almost any LLM (including locally running ones) and offer various other integrations. diff --git a/docs/02-usage/020_running.md b/docs/02-usage/020_running.md new file mode 100644 index 00000000..8233027c --- /dev/null +++ b/docs/02-usage/020_running.md @@ -0,0 +1,156 @@ +## Running Serena + +Serena is a command-line tool with a variety of sub-commands. +The main command is `start-mcp-server`, which starts the MCP server that +provides Serena's functionality to LLM clients via the Model Context Protocol (MCP). + +### Ways of Running Serena + +There are several ways to run Serena, depending on your preferences and setup. +In the following, we will refer to the command used to run Serena as ``, +which you should replace with the appropriate command based on your chosen method. + +#### Using uvx + +`uvx` is part of `uv`. It can be used to run the latest version of Serena directly from the repository, without an explicit local installation. + + uvx --from git+https://github.com/oraios/serena serena + +Explore the CLI to see some of the customization options that serena provides (more info on them below). + +#### Local Installation + +1. Clone the repository and change into it. + + ```shell + git clone https://github.com/oraios/serena + cd serena + ``` + +2. Run Serena via + + ```shell + uv run serena + ``` + + when within the serena installation directory. + From other directories, run it with the `--directory` option, i.e. + + ```shell + uv run --directory /abs/path/to/serena serena + ``` + +#### Using Docker (Experimental) + +⚠️ Docker support is currently experimental with several limitations. Please read the [Docker documentation](DOCKER.md) for important caveats before using it. + +You can run the Serena MCP server directly via docker as follows, +assuming that the projects you want to work on are all located in `/path/to/your/projects`: + +```shell +docker run --rm -i --network host -v /path/to/your/projects:/workspaces/projects ghcr.io/oraios/serena:latest serena +``` + +Replace `/path/to/your/projects` with the absolute path to your projects directory. The Docker approach provides: + +* Better security isolation for shell command execution +* No need to install language servers and dependencies locally +* Consistent environment across different systems + +Alternatively, use docker compose with the `compose.yml` file provided in the repository. + +See the [Docker documentation](DOCKER.md) for detailed setup instructions, configuration options, and known limitations. + +#### Using Nix + +If you are using Nix and [have enabled the `nix-command` and `flakes` features](https://nixos.wiki/wiki/flakes), you can run Serena using the following command: + +```bash +nix run github:oraios/serena -- [options] +``` + +You can also install Serena by referencing this repo (`github:oraios/serena`) and using it in your Nix flake. The package is exported as `serena`. + +### Running the MCP Server + +Given your preferred method of running Serena, you can start the MCP server using the `start-mcp-server` command: + + start-mcp-server [options] + +Note that no matter how you run the MCP server, Serena will, by default, start a web-based dashboard on localhost that will allow you to inspect +the server's operations, logs, and configuration. + +#### Standard I/O Mode + +The typical usage involves the client (e.g. Claude Code, Codex or Cursor) running +the MCP server as a subprocess and using the process' stdin/stdout streams to communicate with it. +In order to launch the server, the client thus needs to be provided with the command to run the MCP server. + +Communication over stdio is the default for the Serena MCP server, so in the simplest +case, you can simply run the `start-mcp-server` command without any additional options. + + start-mcp-server + +For example, to run the server in stdio mode via `uvx`, you would run: + + uvx --from git+https://github.com/oraios/serena serena start-mcp-server + +ℹ️ See the section ["Configuring Your MCP Client"](030_clients) for information on how to configure your MCP client (e.g. Claude Code, Codex, Cursor, etc.) +to connect to the Serena MCP server. + +ℹ️ Note that MCP servers which use stdio as a protocol are somewhat unusual as far as client/server architectures go, as the server +necessarily has to be started by the client in order for communication to take place via the server's standard input/output stream. +In other words, you do not need to start the server yourself. The client application (e.g. Claude Desktop) takes care of this and +therefore needs to be configured with a launch command. + +#### Streamable HTTP Mode + +When using instead the *Streamable HTTP* mode, you control the server lifecycle yourself, +i.e. you start the server and provide the client with the URL to connect to it. + +Simply provide `start-mcp-server` with the `--transport streamable-http` option and optionally provide the desired port +via the `--port` option. + + start-mcp-server --transport streamable-http --port + +For example, to run the Serena MCP server in streamable HTTP mode on port 9121 using uvx, +you would run + + uvx --from git+https://github.com/oraios/serena serena start-mcp-server --transport streamable-http --port 9121 + +and then configure your client to connect to `http://localhost:9121/mcp`. + +ℹ️ Note that while SSE transport is also supported, its use is discouraged. + +#### MCP Server Command-Line Arguments + +The Serena MCP server supports a wide range of additional command-line options. +Use the command + + start-mcp-server --help + +to get a list of all available options. + +Some useful options include: + + * `--project `: specify the project to work on by name or path. + * `--context `: specify the operation [context]() in which Serena shall operate + * `--mode `: specify one or more [modes]() to enable (can be passed several times) + * `--enable-web-dashboard `: enable or disable the web dashboard (enabled by default) + +### Other Commands + +Serena provides several other commands in addition to `start-mcp-server`, +most of which are related to project setup and configuration. + +To get a list of available commands, run: + + --help + +To get help on a specific command, run: + + --help + +Here are some examples of commands you might find useful: + + # TODO diff --git a/docs/02-usage/030_clients.md b/docs/02-usage/030_clients.md new file mode 100644 index 00000000..3d4ab85f --- /dev/null +++ b/docs/02-usage/030_clients.md @@ -0,0 +1,154 @@ +## Configuring Your MCP Client + +### Claude Code + +Serena is a great way to make Claude Code both cheaper and more powerful! + +From your project directory, add serena with a command like this, + +```shell +claude mcp add serena -- --context ide-assistant --project "$(pwd)" +``` + +where `` is your way of [running the Serena MCP server](#running-the-serena-mcp-server). +For example, when using `uvx`, you would run + +```shell +claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project "$(pwd)" +``` + +ℹ️ Serena comes with an instruction text, and Claude needs to read it to properly use Serena's tools. +As of version `v1.0.52`, claude code reads the instructions of the MCP server, so this **is handled automatically**. +If you are using an older version, or if Claude fails to read the instructions, you can ask it explicitly +to "read Serena's initial instructions" or run `/mcp__serena__initial_instructions` to load the instruction text. +If you want to make use of that, you will have to enable the corresponding tool explicitly by adding `initial_instructions` to the `included_optional_tools` +in your config. +Note that you may have to make Claude read the instructions when you start a new conversation and after any compacting operation to ensure Claude remains properly configured to use Serena's tools. + +### Codex + +Serena works with OpenAI's Codex CLI out of the box, but you have to use the `codex` context for it to work properly. (The technical reason is that Codex doesn't fully support the MCP specifications, so some massaging of tools is required.). + +Unlike Claude Code, in Codex you add an MCP server globally and not per project. Add the following to +`~/.codex/config.toml` (create the file if it does not exist): + +```toml +[mcp_servers.serena] +command = "uvx" +args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"] +``` + +After codex has started, you need to activate the project, which you can do by saying: + +"Activate the current dir as project using serena" + +> If you don't activate the project, you will not be able to use Serena's tools! + +That's it! Have a look at `~/.codex/log/codex-tui.log` to see if any errors occurred. + +The Serena dashboard will run if you have not disabled it in the configuration, but due to Codex's sandboxing the webbrowser +may not open automatically. You can open it manually by going to `http://localhost:24282/dashboard/index.html` (or a higher port, if +that was already taken). + +> Codex will often show the tools as `failed` even though they are successfully executed. This is not a problem, seems to be a bug in Codex. Despite the error message, everything works as expected. + +### Other Terminal-Based Clients + +There are many terminal-based coding assistants that support MCP servers, such as [Codex](https://github.com/openai/codex?tab=readme-ov-file#model-context-protocol-mcp), +[Gemini-CLI](https://github.com/google-gemini/gemini-cli), [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder), +[rovodev](https://community.atlassian.com/forums/Rovo-for-Software-Teams-Beta/Introducing-Rovo-Dev-CLI-AI-Powered-Development-in-your-terminal/ba-p/3043623), +the [OpenHands CLI](https://docs.all-hands.dev/usage/how-to/cli-mode) and [opencode](https://github.com/sst/opencode). + +They generally benefit from the symbolic tools provided by Serena. You might want to customize some aspects of Serena +by writing your own context, modes or prompts to adjust it to your workflow, to other MCP servers you are using, and to +the client's internal capabilities. + +### Claude Desktop + +For [Claude Desktop](https://claude.ai/download) (available for Windows and macOS), go to File / Settings / Developer / MCP Servers / Edit Config, +which will let you open the JSON file `claude_desktop_config.json`. +Add the `serena` MCP server configuration, using a [run command](#running-the-serena-mcp-server) depending on your setup. + +* local installation: + + ```json + { + "mcpServers": { + "serena": { + "command": "/abs/path/to/uv", + "args": ["run", "--directory", "/abs/path/to/serena", "serena", "start-mcp-server"] + } + } + } + ``` + +* uvx: + + ```json + { + "mcpServers": { + "serena": { + "command": "/abs/path/to/uvx", + "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"] + } + } + } + ``` + +* docker: + + ```json + { + "mcpServers": { + "serena": { + "command": "docker", + "args": ["run", "--rm", "-i", "--network", "host", "-v", "/path/to/your/projects:/workspaces/projects", "ghcr.io/oraios/serena:latest", "serena", "start-mcp-server", "--transport", "stdio"] + } + } + } + ``` + +If you are using paths containing backslashes for paths on Windows +(note that you can also just use forward slashes), be sure to escape them correctly (`\\`). + +That's it! Save the config and then restart Claude Desktop. You are ready for activating your first project. + +ℹ️ You can further customize the run command using additional arguments (see [above](#command-line-arguments)). + +Note: on Windows and macOS there are official Claude Desktop applications by Anthropic, for Linux there is an [open-source +community version](https://github.com/aaddrick/claude-desktop-debian). + +⚠️ Be sure to fully quit the Claude Desktop application, as closing Claude will just minimize it to the system tray – at least on Windows. + +⚠️ Some clients may leave behind zombie processes. You will have to find and terminate them manually then. +With Serena, you can activate the [dashboard](#serenas-logs-the-dashboard-and-gui-tool) to prevent unnoted processes and also use the dashboard +for shutting down Serena. + +After restarting, you should see Serena's tools in your chat interface (notice the small hammer icon). + +For more information on MCP servers with Claude Desktop, see [the official quick start guide](https://modelcontextprotocol.io/quickstart/user). + +### MCP Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) + +Being an MCP Server, Serena can be included in any MCP Client. The same configuration as above, +perhaps with small client-specific modifications, should work. Most of the popular +existing coding assistants (IDE extensions or VSCode-like IDEs) support connections +to MCP Servers. It is **recommended to use the `ide-assistant` context** for these integrations by adding `"--context", "ide-assistant"` to the `args` in your MCP client's configuration. Including Serena generally boosts their performance +by providing them tools for symbolic operations. + +In this case, the billing for the usage continues to be controlled by the client of your choice +(unlike with the Claude Desktop client). But you may still want to use Serena through such an approach, +e.g., for one of the following reasons: + +1. You are already using a coding assistant (say Cline or Cursor) and just want to make it more powerful. +2. You are on Linux and don't want to use the [community-created Claude Desktop](https://github.com/aaddrick/claude-desktop-debian). +3. You want tighter integration of Serena into your IDE and don't mind paying for that. + +### Local GUIs and Frameworks + +Over the last months, several technologies have emerged that allow you to run a powerful local GUI +and connect it to an MCP server. They will work with Serena out of the box. +Some of the leading open source GUI technologies offering this are +[Jan](https://jan.ai/docs/mcp), [OpenHands](https://github.com/All-Hands-AI/OpenHands/), +[OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp) and [Agno](https://docs.agno.com/introduction/playground). +They allow combining Serena with almost any LLM (including locally running ones) and offer various other integrations. diff --git a/docs/02-usage/040_workflow.md b/docs/02-usage/040_workflow.md new file mode 100644 index 00000000..7c949870 --- /dev/null +++ b/docs/02-usage/040_workflow.md @@ -0,0 +1,51 @@ +## The Project Workflow + +### Project Activation & Indexing + +If you are mostly working with the same project, you can configure to always activate it at startup +by passing `--project ` to the `start-mcp-server` command in your client's MCP config. +This is especially useful for clients which configure MCP servers on a per-project basis, like Claude Code. + +Otherwise, the recommended way is to just ask the LLM to activate a project by providing it an absolute path to, or, +in case the project was activated in the past, by its name. The default project name is the directory name. + +* "Activate the project /path/to/my_project" +* "Activate the project my_project" + +All projects that have been activated will be automatically added to your `serena_config.yml`, and for each +project, the file `.serena/project.yml` will be generated. You can adjust the latter, e.g., by changing the name +(which you refer to during the activation) or other options. Make sure to not have two different projects with the +same name. + +ℹ️ For larger projects, we recommend that you index your project to accelerate Serena's tools; otherwise the first +tool application may be very slow. +To do so, run this from the project directory (or pass the path to the project as an argument): + +```shell +uvx --from git+https://github.com/oraios/serena serena project index +``` + +(or use the `--directory` command version). + +### Onboarding and Memories + +By default, Serena will perform an **onboarding process** when +it is started for the first time for a project. +The goal of the onboarding is for Serena to get familiar with the project +and to store memories, which it can then draw upon in future interactions. +If an LLM should fail to complete the onboarding and does not actually write the +respective memories to disk, you may need to ask it to do so explicitly. + +The onboarding will usually read a lot of content from the project, thus filling +up the context. It can therefore be advisable to switch to another conversation +once the onboarding is complete. +After the onboarding, we recommend that you have a quick look at the memories and, +if necessary, edit them or add additional ones. + +**Memories** are files stored in `.serena/memories/` in the project directory, +which the agent can choose to read in subsequent interactions. +Feel free to read and adjust them as needed; you can also add new ones manually. +Every file in the `.serena/memories/` directory is a memory file. +Whenever Serena starts working on a project, the list of memories is +provided, and the agent can decide to read them. +We found that memories can significantly improve the user experience with Serena. \ No newline at end of file diff --git a/docs/02-usage/050_configuration.md b/docs/02-usage/050_configuration.md new file mode 100644 index 00000000..ee9a2120 --- /dev/null +++ b/docs/02-usage/050_configuration.md @@ -0,0 +1,77 @@ +## Configuration + +Serena is very flexible in terms of configuration. While for most users, the default configurations will work, +you can fully adjust it to your needs by editing a few yaml files. You can disable tools, change Serena's instructions +(what we denote as the `system_prompt`), adjust the output of tools that just provide a prompt, and even adjust tool descriptions. + +Serena is configured in four places: + +1. The `serena_config.yml` for general settings that apply to all clients and projects. + It is located in your user directory under `.serena/serena_config.yml`. + If you do not explicitly create the file, it will be auto-generated when you first run Serena. + You can edit it directly or use + + ```shell + uvx --from git+https://github.com/oraios/serena serena config edit + ``` + + (or use the `--directory` command version). +2. In the arguments passed to the `start-mcp-server` in your client's config (see below), + which will apply to all sessions started by the respective client. In particular, the [context](#contexts) parameter + should be set appropriately for Serena to be best adjusted to existing tools and capabilities of your client. + See for a detailed explanation. You can override all entries from the `serena_config.yml` through command line arguments. +3. In the `.serena/project.yml` file within your project. This will hold project-level configuration that is used whenever + that project is activated. This file will be autogenerated when you first use Serena on that project, but you can also + generate it explicitly with + + ```shell + uvx --from git+https://github.com/oraios/serena serena project generate-yml + ``` + + (or use the `--directory` command version). +4. Through the context and modes (see below). + +After the initial setup, continue with one of the sections below, depending on how you +want to use Serena. + +### Modes and Contexts + +Serena's behavior and toolset can be adjusted using contexts and modes. +These allow for a high degree of customization to best suit your workflow and the environment Serena is operating in. + +#### Contexts + +A context defines the general environment in which Serena is operating. +It influences the initial system prompt and the set of available tools. +A context is set at startup when launching Serena (e.g., via CLI options for an MCP server or in the agent script) and cannot be changed during an active session. + +Serena comes with pre-defined contexts: + +* `desktop-app`: Tailored for use with desktop applications like Claude Desktop. This is the default. +* `agent`: Designed for scenarios where Serena acts as a more autonomous agent, for example, when used with Agno. +* `ide-assistant`: Optimized for integration into IDEs like VSCode, Cursor, or Cline, focusing on in-editor coding assistance. + Choose the context that best matches the type of integration you are using. + +When launching Serena, specify the context using `--context `. +Note that for cases where parameter lists are specified (e.g. Claude Desktop), you must add two parameters to the list. + +If you are using a local server (such as Llama.cpp) which requires you to use OpenAI-compatible tool descriptions, use context `oaicompat-agent` instead of `agent`. + +#### Modes + +Modes further refine Serena's behavior for specific types of tasks or interaction styles. Multiple modes can be active simultaneously, allowing you to combine their effects. Modes influence the system prompt and can also alter the set of available tools by excluding certain ones. + +Examples of built-in modes include: + +* `planning`: Focuses Serena on planning and analysis tasks. +* `editing`: Optimizes Serena for direct code modification tasks. +* `interactive`: Suitable for a conversational, back-and-forth interaction style. +* `one-shot`: Configures Serena for tasks that should be completed in a single response, often used with `planning` for generating reports or initial plans. +* `no-onboarding`: Skips the initial onboarding process if it's not needed for a particular session. +* `onboarding`: (Usually triggered automatically) Focuses on the project onboarding process. + +Modes can be set at startup (similar to contexts) but can also be _switched dynamically_ during a session. You can instruct the LLM to use the `switch_modes` tool to activate a different set of modes (e.g., "switch to planning and one-shot modes"). + +When launching Serena, specify modes using `--mode `; multiple modes can be specified, e.g. `--mode planning --mode no-onboarding`. + +:warning: **Mode Compatibility**: While you can combine modes, some may be semantically incompatible (e.g., `interactive` and `one-shot`). Serena currently does not prevent incompatible combinations; it is up to the user to choose sensible mode configurations. diff --git a/docs/02-usage/020_detailed-usage.md b/docs/02-usage/999_detailed-usage.md similarity index 65% rename from docs/02-usage/020_detailed-usage.md rename to docs/02-usage/999_detailed-usage.md index 2fe63e08..53dc4b27 100644 --- a/docs/02-usage/020_detailed-usage.md +++ b/docs/02-usage/999_detailed-usage.md @@ -30,48 +30,6 @@ allowing all analysis and exploration capabilities. In general, be sure to back up your work and use a version control system in order to avoid losing any work. -### Modes and Contexts - -Serena's behavior and toolset can be adjusted using contexts and modes. -These allow for a high degree of customization to best suit your workflow and the environment Serena is operating in. - -#### Contexts - -A context defines the general environment in which Serena is operating. -It influences the initial system prompt and the set of available tools. -A context is set at startup when launching Serena (e.g., via CLI options for an MCP server or in the agent script) and cannot be changed during an active session. - -Serena comes with pre-defined contexts: - -* `desktop-app`: Tailored for use with desktop applications like Claude Desktop. This is the default. -* `agent`: Designed for scenarios where Serena acts as a more autonomous agent, for example, when used with Agno. -* `ide-assistant`: Optimized for integration into IDEs like VSCode, Cursor, or Cline, focusing on in-editor coding assistance. - Choose the context that best matches the type of integration you are using. - -When launching Serena, specify the context using `--context `. -Note that for cases where parameter lists are specified (e.g. Claude Desktop), you must add two parameters to the list. - -If you are using a local server (such as Llama.cpp) which requires you to use OpenAI-compatible tool descriptions, use context `oaicompat-agent` instead of `agent`. - -#### Modes - -Modes further refine Serena's behavior for specific types of tasks or interaction styles. Multiple modes can be active simultaneously, allowing you to combine their effects. Modes influence the system prompt and can also alter the set of available tools by excluding certain ones. - -Examples of built-in modes include: - -* `planning`: Focuses Serena on planning and analysis tasks. -* `editing`: Optimizes Serena for direct code modification tasks. -* `interactive`: Suitable for a conversational, back-and-forth interaction style. -* `one-shot`: Configures Serena for tasks that should be completed in a single response, often used with `planning` for generating reports or initial plans. -* `no-onboarding`: Skips the initial onboarding process if it's not needed for a particular session. -* `onboarding`: (Usually triggered automatically) Focuses on the project onboarding process. - -Modes can be set at startup (similar to contexts) but can also be _switched dynamically_ during a session. You can instruct the LLM to use the `switch_modes` tool to activate a different set of modes (e.g., "switch to planning and one-shot modes"). - -When launching Serena, specify modes using `--mode `; multiple modes can be specified, e.g. `--mode planning --mode no-onboarding`. - -:warning: **Mode Compatibility**: While you can combine modes, some may be semantically incompatible (e.g., `interactive` and `one-shot`). Serena currently does not prevent incompatible combinations; it is up to the user to choose sensible mode configurations. - #### Customization You can create your own contexts and modes to precisely tailor Serena to your needs in two ways: @@ -93,29 +51,6 @@ You can create your own contexts and modes to precisely tailor Serena to your ne This customization allows for deep integration and adaptation of Serena to specific project requirements or personal preferences. -### Onboarding and Memories - -By default, Serena will perform an **onboarding process** when -it is started for the first time for a project. -The goal of the onboarding is for Serena to get familiar with the project -and to store memories, which it can then draw upon in future interactions. -If an LLM should fail to complete the onboarding and does not actually write the -respective memories to disk, you may need to ask it to do so explicitly. - -The onboarding will usually read a lot of content from the project, thus filling -up the context. It can therefore be advisable to switch to another conversation -once the onboarding is complete. -After the onboarding, we recommend that you have a quick look at the memories and, -if necessary, edit them or add additional ones. - -**Memories** are files stored in `.serena/memories/` in the project directory, -which the agent can choose to read in subsequent interactions. -Feel free to read and adjust them as needed; you can also add new ones manually. -Every file in the `.serena/memories/` directory is a memory file. -Whenever Serena starts working on a project, the list of memories is -provided, and the agent can decide to read them. -We found that memories can significantly improve the user experience with Serena. - ### Prepare Your Project #### Structure Your Codebase From 774333befc7e5ab57fd0077efef5a4a0a9eeda39 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Fri, 7 Nov 2025 20:30:17 +0100 Subject: [PATCH 04/21] Improve docs on contexts and modes --- docs/02-usage/050_configuration.md | 28 +++++++++++++++++++++++++--- docs/02-usage/999_detailed-usage.md | 21 --------------------- 2 files changed, 25 insertions(+), 24 deletions(-) diff --git a/docs/02-usage/050_configuration.md b/docs/02-usage/050_configuration.md index ee9a2120..31de3420 100644 --- a/docs/02-usage/050_configuration.md +++ b/docs/02-usage/050_configuration.md @@ -41,7 +41,7 @@ These allow for a high degree of customization to best suit your workflow and th #### Contexts -A context defines the general environment in which Serena is operating. +A **context** defines the general environment in which Serena is operating. It influences the initial system prompt and the set of available tools. A context is set at startup when launching Serena (e.g., via CLI options for an MCP server or in the agent script) and cannot be changed during an active session. @@ -57,6 +57,16 @@ Note that for cases where parameter lists are specified (e.g. Claude Desktop), y If you are using a local server (such as Llama.cpp) which requires you to use OpenAI-compatible tool descriptions, use context `oaicompat-agent` instead of `agent`. +You can manage contexts using the `context` command, + + context --help + context list + context create + context edit + context delete + +where `` is [your way of running Serena](020_running). + #### Modes Modes further refine Serena's behavior for specific types of tasks or interaction styles. Multiple modes can be active simultaneously, allowing you to combine their effects. Modes influence the system prompt and can also alter the set of available tools by excluding certain ones. @@ -70,8 +80,20 @@ Examples of built-in modes include: * `no-onboarding`: Skips the initial onboarding process if it's not needed for a particular session. * `onboarding`: (Usually triggered automatically) Focuses on the project onboarding process. -Modes can be set at startup (similar to contexts) but can also be _switched dynamically_ during a session. You can instruct the LLM to use the `switch_modes` tool to activate a different set of modes (e.g., "switch to planning and one-shot modes"). +Modes can be set at startup (similar to contexts) but can also be _switched dynamically_ during a session. +You can instruct the LLM to use the `switch_modes` tool to activate a different set of modes (e.g., "Switch to planning and one-shot modes"). When launching Serena, specify modes using `--mode `; multiple modes can be specified, e.g. `--mode planning --mode no-onboarding`. -:warning: **Mode Compatibility**: While you can combine modes, some may be semantically incompatible (e.g., `interactive` and `one-shot`). Serena currently does not prevent incompatible combinations; it is up to the user to choose sensible mode configurations. +:warning: **Mode Compatibility**: While you can combine modes, some may be semantically incompatible (e.g., `interactive` and `one-shot`). +Serena currently does not prevent incompatible combinations; it is up to the user to choose sensible mode configurations. + +You can manage contexts using the `mode` command, + + mode --help + mode list + mode create + mode edit + mode delete + +where `` is [your way of running Serena](020_running). \ No newline at end of file diff --git a/docs/02-usage/999_detailed-usage.md b/docs/02-usage/999_detailed-usage.md index 53dc4b27..a1471134 100644 --- a/docs/02-usage/999_detailed-usage.md +++ b/docs/02-usage/999_detailed-usage.md @@ -30,27 +30,6 @@ allowing all analysis and exploration capabilities. In general, be sure to back up your work and use a version control system in order to avoid losing any work. -#### Customization - -You can create your own contexts and modes to precisely tailor Serena to your needs in two ways: - -* You can use Serena's CLI to manage modes and contexts. Check out - - ```shell - uvx --from git+https://github.com/oraios/serena serena mode --help - ``` - - and - - ```shell - uvx --from git+https://github.com/oraios/serena serena context --help - ``` - - _NOTE_: Custom contexts/modes are simply YAML files in `/.serena`, they are automatically registered and available for use by their name (filename without the `.yml` extension). If you don't want to use Serena's CLI, you can create and manage them in any way you see fit. -* **Using external YAML files**: When starting Serena, you can also provide an absolute path to a custom `.yml` file for a context or mode. - -This customization allows for deep integration and adaptation of Serena to specific project requirements or personal preferences. - ### Prepare Your Project #### Structure Your Codebase From 1ec18595be707c02953de062a11efed6623c513a Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Fri, 7 Nov 2025 20:43:36 +0100 Subject: [PATCH 05/21] Add/improve docs on security --- docs/02-usage/070_security.md | 12 ++++++++++++ docs/02-usage/999_detailed-usage.md | 20 -------------------- 2 files changed, 12 insertions(+), 20 deletions(-) create mode 100644 docs/02-usage/070_security.md diff --git a/docs/02-usage/070_security.md b/docs/02-usage/070_security.md new file mode 100644 index 00000000..de1a83f2 --- /dev/null +++ b/docs/02-usage/070_security.md @@ -0,0 +1,12 @@ +## Security Considerations + +As fundamental abilities for a coding agent, Serena contains tools for executing shell commands and modifying files. +Therefore, if the respective tool calls are not monitored or restricted (and execution takes place in a sensitive environment), +there is a risk of unintended consequences. + +Therefore, to reduce the risk of unintended consequences when using Serena, it is recommended to + * back up your work regularly (e.g. use a version control system like Git), + * monitor tool executions carefully (e.g. via your MCP client, provided that it supports it), + * consider enabling read-only mode for your project (set `read_only: True` in project.yml) if you only want to analyze code without modifying it, + * restrict the set of allowed tools via the [configuration](050_configuration), + * use a sandboxed environment for running Serena (e.g. by [using Docker](020_running.md#using-docker-experimental)). diff --git a/docs/02-usage/999_detailed-usage.md b/docs/02-usage/999_detailed-usage.md index a1471134..63b05e07 100644 --- a/docs/02-usage/999_detailed-usage.md +++ b/docs/02-usage/999_detailed-usage.md @@ -10,26 +10,6 @@ The use of all tools is generally recommended, as this allows Serena to provide Only by executing shell commands (in particular, tests) can Serena identify and correct mistakes autonomously. -#### Shell Execution and Editing Tools - -Many clients have their own shell execution tool, and by default Serena's shell tool will be disabled in them -(e.g., when using the `ide-assistant` or `codex` context). However, when using Serena through something like -Claude Desktop or ChatGPT, it is recommended to enable Serena's `execute_shell_command` tool to allow -agentic behavior. - -It should be noted that the `execute_shell_command` tool allows for arbitrary code execution. -When using Serena as an MCP Server, clients will typically ask the user for permission -before executing a tool, so as long as the user inspects execution parameters beforehand, -this should not be a problem. -However, if you have concerns, you can choose to disable certain commands in your project's configuration file. -If you only want to use Serena purely for analyzing code and suggesting implementations -without modifying the codebase, you can enable read-only mode by setting `read_only: true` in your project configuration file. -This will automatically disable all editing tools and prevent any modifications to your codebase while still -allowing all analysis and exploration capabilities. - -In general, be sure to back up your work and use a version control system in order to avoid -losing any work. - ### Prepare Your Project #### Structure Your Codebase From f9580315552395383b7d32fc91bfc2deb9f01bee Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Fri, 7 Nov 2025 20:50:09 +0100 Subject: [PATCH 06/21] Add/improve docs on dashboard/GUI tool --- docs/02-usage/060_dashboard.md | 22 ++++++++++++++++++++++ docs/02-usage/999_detailed-usage.md | 22 ---------------------- 2 files changed, 22 insertions(+), 22 deletions(-) create mode 100644 docs/02-usage/060_dashboard.md diff --git a/docs/02-usage/060_dashboard.md b/docs/02-usage/060_dashboard.md new file mode 100644 index 00000000..c8babaac --- /dev/null +++ b/docs/02-usage/060_dashboard.md @@ -0,0 +1,22 @@ +## The Dashboard and GUI Tool + +Serena comes with built-in tools for monitoring and managing the current session: + +* the **web-based dashboard** (enabled by default) + + The dashboard provides detailed information on your Serena session, the current configuration and provides access to logs. + Some settings (e.g. the current set of active programming languages) can also be directly modified through the dashboard. + + The dashboard is supported on all platforms. + + By default, it will be accessible at `http://localhost:24282/dashboard/index.html`, + but a higher port may be used if the default port is unavailable/multiple instances are running. + +* the **GUI tool** (disabled by default) + + The GUI tool is a native application window which displays logs. + + This is mainly supported on Windows, but it may also work on Linux; macOS is unsupported. + +Both can be enabled, configured or disabled in Serena's [configuration](050_configuration) file (`serena_config.yml`). +If enabled, they will automatically be opened as soon as the Serena agent/MCP server is started. diff --git a/docs/02-usage/999_detailed-usage.md b/docs/02-usage/999_detailed-usage.md index 63b05e07..9cdeaaee 100644 --- a/docs/02-usage/999_detailed-usage.md +++ b/docs/02-usage/999_detailed-usage.md @@ -72,28 +72,6 @@ Moreover, Serena is instructed to be frugal with context but we found that Claude is not always very good in being frugal (Gemini seemed better at it). You can explicitly instruct it to not read the bodies if you know that it's not needed. -### Serena's Logs: The Dashboard and GUI Tool - -Serena provides two convenient ways of accessing the logs of the current session: - -* via the **web-based dashboard** (enabled by default) - - This is supported on all platforms. - By default, it will be accessible at `http://localhost:24282/dashboard/index.html`, - but a higher port may be used if the default port is unavailable/multiple instances are running. - -* via the **GUI tool** (disabled by default) - - This is mainly supported on Windows, but it may also work on Linux; macOS is unsupported. - -Both can be enabled, configured or disabled in Serena's configuration file (`serena_config.yml`, see above). -If enabled, they will automatically be opened as soon as the Serena agent/MCP server is started. -The web dashboard will display usage statistics of Serena's tools if you set `record_tool_usage_stats: True` in your config. - -In addition to viewing logs, both tools allow to shut down the Serena agent. -This function is provided, because clients like Claude Desktop may fail to terminate the MCP server subprocess -when they themselves are closed. - ### Serena and GIT worktrees [git-worktree](https://git-scm.com/docs/git-worktree) can be an excellent way to parallelize your work. More on this in [Anthropic: Run parallel Claude Code sessions with Git worktrees](https://docs.claude.com/en/docs/claude-code/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees). From 9dbbfe60b81d738d9fada5518d1f7dc4e68283fe Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Fri, 7 Nov 2025 20:54:38 +0100 Subject: [PATCH 07/21] Improve docs on 'Running Serena' --- docs/02-usage/020_running.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/02-usage/020_running.md b/docs/02-usage/020_running.md index 8233027c..a9682507 100644 --- a/docs/02-usage/020_running.md +++ b/docs/02-usage/020_running.md @@ -1,12 +1,13 @@ ## Running Serena Serena is a command-line tool with a variety of sub-commands. -The main command is `start-mcp-server`, which starts the MCP server that -provides Serena's functionality to LLM clients via the Model Context Protocol (MCP). +This section describes + * varies ways of running Serena + * how to run and configure the most important command, i.e. starting the MCP server + * other useful commands. ### Ways of Running Serena -There are several ways to run Serena, depending on your preferences and setup. In the following, we will refer to the command used to run Serena as ``, which you should replace with the appropriate command based on your chosen method. From 185c3b2065e1cd07ab89eaa5c07f3f282af66f9d Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Fri, 7 Nov 2025 21:10:15 +0100 Subject: [PATCH 08/21] Improve prerequisistes and language support docs --- docs/01-about/020_programming-languages.md | 77 ++++++++++++++-------- docs/02-usage/010_prerequisites.md | 14 +++- 2 files changed, 59 insertions(+), 32 deletions(-) diff --git a/docs/01-about/020_programming-languages.md b/docs/01-about/020_programming-languages.md index 3212dba7..f59e2a50 100644 --- a/docs/01-about/020_programming-languages.md +++ b/docs/01-about/020_programming-languages.md @@ -1,4 +1,4 @@ -## Programming Language Support & Semantic Analysis Capabilities +## Language Support Serena's semantic code analysis capabilities build on **language servers** using the widely implemented language server protocol (LSP). The LSP provides a set of versatile code querying @@ -12,34 +12,53 @@ than existing solutions that charge a premium. Language servers provide support for a wide range of programming languages. With Serena, we provide direct, out-of-the-box support for: -* Python -* TypeScript/Javascript -* PHP (uses Intelephense LSP; set `INTELEPHENSE_LICENSE_KEY` environment variable for premium features) -* Go (requires installation of gopls) -* R (requires installation of the `languageserver` R package) -* Rust (requires [rustup](https://rustup.rs/) - uses rust-analyzer from your toolchain) -* C/C++ (you may experience issues with finding references, we are working on it) -* Zig (requires installation of ZLS - Zig Language Server) -* C# -* Ruby (by default, uses [ruby-lsp](https://github.com/Shopify/ruby-lsp), specify ruby_solargraph as your language to use the previous solargraph based implementation) -* Swift -* Kotlin (uses the pre-alpha [official kotlin LS](https://github.com/Kotlin/kotlin-lsp), some issues may appear) -* Java (_Note_: startup is slow, initial startup especially so. There may be issues with java on macos and linux, we are working on it.) -* Clojure -* Dart -* Bash -* Lua (automatically downloads lua-language-server if not installed) -* Nix (requires nixd installation) -* Elixir (requires installation of NextLS and Elixir; **Windows not supported**) -* Elm (automatically downloads elm-language-server if not installed; requires Elm compiler) -* Scala (requires some [manual setup](docs/scala_setup_guide_for_serena.md); uses Metals LSP) -* Erlang (requires installation of beam and [erlang_ls](https://github.com/erlang-ls/erlang_ls), experimental, might be slow or hang) -* Perl (requires installation of Perl::LanguageServer) -* Fortran (requires installation of fortls: `pip install fortls`) -* Haskell (automatically locates HLS via ghcup, stack, or system PATH; supports Stack and Cabal projects) -* Julia -* AL -* Markdown (must be explicitly specified via `--language markdown` when generating project config, primarily useful for documentation-heavy projects) +* **AL** +* **Bash** +* **C#** +* **C/C++** + (you may experience issues with finding references, we are working on it) +* **Clojure** +* **Dart** +* **Elixir** + (requires installation of NextLS and Elixir; Windows not supported) +* **Elm** + (requires Elm compiler) +* **Erlang** + (requires installation of beam and [erlang_ls](https://github.com/erlang-ls/erlang_ls), experimental, might be slow or hang) +* **Fortran** + (requires installation of fortls: `pip install fortls`) +* **Go** + (requires installation of `gopls`) +* **Haskell** + (automatically locates HLS via ghcup, stack, or system PATH; supports Stack and Cabal projects) +* **Java** + (_Note_: Uses quirky symbol names for methods that include the full method signature; this causes a variety of problems!) +* **Javascript** +* **Julia** +* **Kotlin** + (uses the pre-alpha [official kotlin LS](https://github.com/Kotlin/kotlin-lsp), some issues may appear) +* **Lua** +* **Markdown** + (must be explicitly specified via `--language markdown` when generating project config, primarily useful for documentation-heavy projects) +* **Nix** + (requires nixd installation) +* **Perl** + (requires installation of Perl::LanguageServer) +* **PHP** + (uses Intelephense LSP; set `INTELEPHENSE_LICENSE_KEY` environment variable for premium features) +* **Python** +* **R** + (requires installation of the `languageserver` R package) +* **Ruby** + (by default, uses [ruby-lsp](https://github.com/Shopify/ruby-lsp), specify ruby_solargraph as your language to use the previous solargraph based implementation) +* **Rust** + (requires [rustup](https://rustup.rs/) - uses rust-analyzer from your toolchain) +* **Scala** + (requires some [manual setup](../03-special-guides/scala_setup_guide_for_serena); uses Metals LSP) +* **Swift** +* **TypeScript** +* **Zig** + (requires installation of ZLS - Zig Language Server) Support for further languages can easily be added by providing a shallow adapter for a new language server implementation, see Serena's [memory on that](.serena/memories/adding_new_language_support_guide.md). diff --git a/docs/02-usage/010_prerequisites.md b/docs/02-usage/010_prerequisites.md index e6265e67..0199fa5e 100644 --- a/docs/02-usage/010_prerequisites.md +++ b/docs/02-usage/010_prerequisites.md @@ -1,4 +1,12 @@ -## Install uv +## Prerequisites -Serena is managed by `uv`, and the only prerequesite for using Serena is to have `uv` installed. -To install it, follow the instructions [here](https://docs.astral.sh/uv/getting-started/installation/). \ No newline at end of file +### uv + +Serena is managed by `uv`. +If you do not have it yet, install it following the instructions [here](https://docs.astral.sh/uv/getting-started/installation/). + +### Language-Specific Requirements + +Depending on the programming language you intend to use with Serena, you may need to install additional tools or SDKs if you +intend to use the language server backend of Serena. +See the [language support documentation](../01-about/020_programming-languages) for details. From 9f2ed5965efcf21db9e62d1f920c7bc97406c2ed Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Fri, 7 Nov 2025 23:30:35 +0100 Subject: [PATCH 09/21] Improve docs on client configuration --- docs/02-usage/020_running.md | 1 + docs/02-usage/030_clients.md | 114 ++++++++++++++++++----------------- 2 files changed, 60 insertions(+), 55 deletions(-) diff --git a/docs/02-usage/020_running.md b/docs/02-usage/020_running.md index a9682507..e50506ae 100644 --- a/docs/02-usage/020_running.md +++ b/docs/02-usage/020_running.md @@ -123,6 +123,7 @@ and then configure your client to connect to `http://localhost:9121/mcp`. ℹ️ Note that while SSE transport is also supported, its use is discouraged. +(mcp-args)= #### MCP Server Command-Line Arguments The Serena MCP server supports a wide range of additional command-line options. diff --git a/docs/02-usage/030_clients.md b/docs/02-usage/030_clients.md index 3d4ab85f..1bf0dd58 100644 --- a/docs/02-usage/030_clients.md +++ b/docs/02-usage/030_clients.md @@ -1,5 +1,11 @@ ## Configuring Your MCP Client +In the following, we provide default configurations for popular MCP-enabled clients. + +Depending on your needs, you might want to customize Serena's behaviour by + * [adding command-line arguments](mcp-args) + * [adjusting configuration](050_configuration). + ### Claude Code Serena is a great way to make Claude Code both cheaper and more powerful! @@ -7,37 +13,38 @@ Serena is a great way to make Claude Code both cheaper and more powerful! From your project directory, add serena with a command like this, ```shell -claude mcp add serena -- --context ide-assistant --project "$(pwd)" +claude mcp add serena -- start-mcp-server --context ide-assistant --project "$(pwd)" ``` -where `` is your way of [running the Serena MCP server](#running-the-serena-mcp-server). -For example, when using `uvx`, you would run +where `` is [your way of running Serena](020_running). +For example, when using `uvx`, the above command becomes ```shell claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project "$(pwd)" ``` -ℹ️ Serena comes with an instruction text, and Claude needs to read it to properly use Serena's tools. -As of version `v1.0.52`, claude code reads the instructions of the MCP server, so this **is handled automatically**. -If you are using an older version, or if Claude fails to read the instructions, you can ask it explicitly -to "read Serena's initial instructions" or run `/mcp__serena__initial_instructions` to load the instruction text. -If you want to make use of that, you will have to enable the corresponding tool explicitly by adding `initial_instructions` to the `included_optional_tools` -in your config. -Note that you may have to make Claude read the instructions when you start a new conversation and after any compacting operation to ensure Claude remains properly configured to use Serena's tools. +Note: + * We use the `ide-assistant` context to disable unnecessary tools (avoiding duplication + with Claude Code's built-in capabilities). + * We specify the current directory as the project directory with `--project "$(pwd)"`, such + that Serena is configured to work on the current project from the get-go, following + Claude Code's mode of operation. + +Be sure to use at least `v1.0.52` of Claude Code (as earlier versions do not read MCP server system prompts upon startup). ### Codex Serena works with OpenAI's Codex CLI out of the box, but you have to use the `codex` context for it to work properly. (The technical reason is that Codex doesn't fully support the MCP specifications, so some massaging of tools is required.). -Unlike Claude Code, in Codex you add an MCP server globally and not per project. Add the following to -`~/.codex/config.toml` (create the file if it does not exist): +Add a [run command](020_running) to `~/.codex/config.toml` to configure Serena for all Codex sessions; +create the file if it does not exist. +For example, when using `uvx`, add the following section: ```toml [mcp_servers.serena] command = "uvx" args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"] ``` - After codex has started, you need to activate the project, which you can do by saying: "Activate the current dir as project using serena" @@ -46,28 +53,21 @@ After codex has started, you need to activate the project, which you can do by s That's it! Have a look at `~/.codex/log/codex-tui.log` to see if any errors occurred. -The Serena dashboard will run if you have not disabled it in the configuration, but due to Codex's sandboxing the webbrowser +Serena's dashboard will run if you have not disabled it in the configuration, but due to Codex's sandboxing, the web browser may not open automatically. You can open it manually by going to `http://localhost:24282/dashboard/index.html` (or a higher port, if that was already taken). > Codex will often show the tools as `failed` even though they are successfully executed. This is not a problem, seems to be a bug in Codex. Despite the error message, everything works as expected. -### Other Terminal-Based Clients - -There are many terminal-based coding assistants that support MCP servers, such as [Codex](https://github.com/openai/codex?tab=readme-ov-file#model-context-protocol-mcp), -[Gemini-CLI](https://github.com/google-gemini/gemini-cli), [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder), -[rovodev](https://community.atlassian.com/forums/Rovo-for-Software-Teams-Beta/Introducing-Rovo-Dev-CLI-AI-Powered-Development-in-your-terminal/ba-p/3043623), -the [OpenHands CLI](https://docs.all-hands.dev/usage/how-to/cli-mode) and [opencode](https://github.com/sst/opencode). - -They generally benefit from the symbolic tools provided by Serena. You might want to customize some aspects of Serena -by writing your own context, modes or prompts to adjust it to your workflow, to other MCP servers you are using, and to -the client's internal capabilities. - ### Claude Desktop -For [Claude Desktop](https://claude.ai/download) (available for Windows and macOS), go to File / Settings / Developer / MCP Servers / Edit Config, +On Windows and macOS there are official [Claude Desktop applications by Anthropic](https://claude.ai/download), for Linux there is an [open-source +community version](https://github.com/aaddrick/claude-desktop-debian). + +To configure MCP server settings, go to File / Settings / Developer / MCP Servers / Edit Config, which will let you open the JSON file `claude_desktop_config.json`. -Add the `serena` MCP server configuration, using a [run command](#running-the-serena-mcp-server) depending on your setup. + +Add the `serena` MCP server configuration, using a [run command](020_running.md) depending on your setup. * local installation: @@ -113,42 +113,46 @@ If you are using paths containing backslashes for paths on Windows That's it! Save the config and then restart Claude Desktop. You are ready for activating your first project. -ℹ️ You can further customize the run command using additional arguments (see [above](#command-line-arguments)). - -Note: on Windows and macOS there are official Claude Desktop applications by Anthropic, for Linux there is an [open-source -community version](https://github.com/aaddrick/claude-desktop-debian). - ⚠️ Be sure to fully quit the Claude Desktop application, as closing Claude will just minimize it to the system tray – at least on Windows. -⚠️ Some clients may leave behind zombie processes. You will have to find and terminate them manually then. -With Serena, you can activate the [dashboard](#serenas-logs-the-dashboard-and-gui-tool) to prevent unnoted processes and also use the dashboard -for shutting down Serena. - After restarting, you should see Serena's tools in your chat interface (notice the small hammer icon). For more information on MCP servers with Claude Desktop, see [the official quick start guide](https://modelcontextprotocol.io/quickstart/user). -### MCP Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) +### Other Clients -Being an MCP Server, Serena can be included in any MCP Client. The same configuration as above, -perhaps with small client-specific modifications, should work. Most of the popular -existing coding assistants (IDE extensions or VSCode-like IDEs) support connections -to MCP Servers. It is **recommended to use the `ide-assistant` context** for these integrations by adding `"--context", "ide-assistant"` to the `args` in your MCP client's configuration. Including Serena generally boosts their performance -by providing them tools for symbolic operations. +#### Terminal-Based Clients -In this case, the billing for the usage continues to be controlled by the client of your choice -(unlike with the Claude Desktop client). But you may still want to use Serena through such an approach, -e.g., for one of the following reasons: +There are many terminal-based coding assistants that support MCP servers, such as -1. You are already using a coding assistant (say Cline or Cursor) and just want to make it more powerful. -2. You are on Linux and don't want to use the [community-created Claude Desktop](https://github.com/aaddrick/claude-desktop-debian). -3. You want tighter integration of Serena into your IDE and don't mind paying for that. + * [Gemini-CLI](https://github.com/google-gemini/gemini-cli), + * [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder), + * [rovodev](https://community.atlassian.com/forums/Rovo-for-Software-Teams-Beta/Introducing-Rovo-Dev-CLI-AI-Powered-Development-in-your-terminal/ba-p/3043623), + * [OpenHands CLI](https://docs.all-hands.dev/usage/how-to/cli-mode) and + * [opencode](https://github.com/sst/opencode). -### Local GUIs and Frameworks +They generally benefit from the symbolic tools provided by Serena. You might want to customize some aspects of Serena +by writing your own context, modes or prompts to adjust it to the client's respective internal capabilities (and your general worflow). -Over the last months, several technologies have emerged that allow you to run a powerful local GUI -and connect it to an MCP server. They will work with Serena out of the box. -Some of the leading open source GUI technologies offering this are -[Jan](https://jan.ai/docs/mcp), [OpenHands](https://github.com/All-Hands-AI/OpenHands/), -[OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp) and [Agno](https://docs.agno.com/introduction/playground). -They allow combining Serena with almost any LLM (including locally running ones) and offer various other integrations. +#### MCP-Enabled IDEs and Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) + +Being an MCP Server, Serena can be included in any MCP Client. Most of the popular +existing coding assistants (e.g. IDE extensions) and AI-enabled IDEs themselves support connections +to MCP Servers. Serena generally boosts performance by providing efficient tools for symbolic operations. + +We generally **recommend to use the `ide-assistant` context** for these integrations by adding the arguments `--context ide-assistant` +in order to reduce tool duplication. + +#### Local GUIs and Agent Frameworks + +Over the last months, several technologies have emerged that allow you to run a local GUI client +and connect it to an MCP server. The respective applications will typically work with Serena out of the box. +Some of the leading open source GUI applications are + + * [Jan](https://jan.ai/docs/mcp), + * [OpenHands](https://github.com/All-Hands-AI/OpenHands/), + * [OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp) and + * [Agno](https://docs.agno.com/introduction/playground). + +These applications allow to combine Serena with almost any LLM (including locally running ones) +and offer various other integrations. From ec41c32a0f13c2147914b611e6bc70d214607bf3 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Sat, 8 Nov 2025 00:11:25 +0100 Subject: [PATCH 10/21] Improve docs on workflow --- docs/02-usage/040_workflow.md | 75 +++++++++++++++++++++++++---------- 1 file changed, 55 insertions(+), 20 deletions(-) diff --git a/docs/02-usage/040_workflow.md b/docs/02-usage/040_workflow.md index 7c949870..b9958c4e 100644 --- a/docs/02-usage/040_workflow.md +++ b/docs/02-usage/040_workflow.md @@ -1,33 +1,68 @@ ## The Project Workflow -### Project Activation & Indexing +Serena uses a project-based workflow. +A **project** is simply a directory on your filesystem that contains code and other files +that you want Serena to work with. -If you are mostly working with the same project, you can configure to always activate it at startup -by passing `--project ` to the `start-mcp-server` command in your client's MCP config. -This is especially useful for clients which configure MCP servers on a per-project basis, like Claude Code. +Assuming that you have project you want to work with (which may initially be empty), +setting up a project with Serena typically involves the following steps: -Otherwise, the recommended way is to just ask the LLM to activate a project by providing it an absolute path to, or, -in case the project was activated in the past, by its name. The default project name is the directory name. +1. **Project creation**: Configuring project settings for Serena (and indexing the project, if desired) +2. **Project activation**: Making Serena aware of the project you want to work with +3. **Onboarding**: Getting Serena familiar with the project (creating memories) +4. **Working on coding tasks**: Using Serena to help you with actual coding tasks in the project -* "Activate the project /path/to/my_project" -* "Activate the project my_project" +### Project Creation & Indexing -All projects that have been activated will be automatically added to your `serena_config.yml`, and for each -project, the file `.serena/project.yml` will be generated. You can adjust the latter, e.g., by changing the name -(which you refer to during the activation) or other options. Make sure to not have two different projects with the -same name. +You can create a project either + * implicitly, by just activating a directory as a project while already in a conversation; this will use default settings for your project (skip to the next section). + * explicitly, using the project creation command, or -ℹ️ For larger projects, we recommend that you index your project to accelerate Serena's tools; otherwise the first -tool application may be very slow. -To do so, run this from the project directory (or pass the path to the project as an argument): +#### Explicit Project Creation -```shell -uvx --from git+https://github.com/oraios/serena serena project index -``` +To explicitly create a project, use the following command while in the project directory: -(or use the `--directory` command version). + project generate-yml [options] -### Onboarding and Memories +For instance, when using `uvx`, run + + uvx --from git+https://github.com/oraios/serena serena project generate-yml [options] + + * For an empty project, you will need to specify the programming language + (e.g., `--language python`). + * For an existing project, the main programming language will be detected automatically, + but you can choose to explicitly specify multiple languages by passing the `--language` parameter + multiple times (e.g. `--language python --language typescript`). + +After creation, you can adjust the project settings in the generated `.serena/project.yml` file. + +#### Indexing + +Especially for larger project, it is advisable to index the project after creation (in order to avoid +delays during MCP server startup or the first tool application): + +While in the project directory, run this command: + + project index + +Indexing has to be called only once. During regular usage, Serena will automatically update the index whenever files change. + +### Project Activation + +Project activation makes Serena aware of the project you want to work with. +You can either choose to do this + * while in a conversation, by telling the model to activate a project, e.g., + + * "Activate the project /path/to/my_project" (for first-time activation with auto-creation) + * "Activate the project my_project" + + Note that this option requires the `activate_project` tool to be active (which it isn't in context `ide-assistant` where t. + + * when the MCP server starts, by passing the project path or name as a command-line argument + (e.g. when working on a fixed project in `ide-assistant` mode): `--project ` + + +### Onboarding & Memories By default, Serena will perform an **onboarding process** when it is started for the first time for a project. From 6833044a852e9f7491af42aacdafe2459ad959fb Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Sat, 8 Nov 2025 00:33:06 +0100 Subject: [PATCH 11/21] Update docs build in CI --- .github/workflows/docs.yaml | 66 ++++++++++++++++++++++++++++ .github/workflows/lint_and_docs.yaml | 47 -------------------- 2 files changed, 66 insertions(+), 47 deletions(-) create mode 100644 .github/workflows/docs.yaml delete mode 100644 .github/workflows/lint_and_docs.yaml diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 00000000..e74752d5 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,66 @@ +name: Docs Build + +on: + push: + # TODO change branch to main once docs is merged + branches: [ docs ] + # Manual trigger, as you have — you can also add "push" later if desired + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + timeout-minutes: 10 # give yourself more headroom for builds + + steps: + - name: Checkout + uses: actions/checkout@v4 # use latest v4 instead of v3 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: 3.11 + + - name: Install uv + run: pip install uv + + - name: Cache dependencies + uses: actions/cache@v4 + with: + path: ~/.cache/uv + key: uv-${{ hashFiles('pyproject.toml') }} + + - name: Install dependencies + run: | + uv venv + uv pip install -e ".[dev]" + + - name: Build docs + run: uv run poe doc-build + # TODO: change once errors are resolved + continue-on-error: true + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/_build # ✅ confirm this is your static HTML output directory + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/lint_and_docs.yaml b/.github/workflows/lint_and_docs.yaml deleted file mode 100644 index daef60c8..00000000 --- a/.github/workflows/lint_and_docs.yaml +++ /dev/null @@ -1,47 +0,0 @@ -name: Linting, Types and Docs Check - -on: - workflow_dispatch: # Manual trigger only - workflow disabled from auto-running - -jobs: - check: - runs-on: ubuntu-latest - timeout-minutes: 5 - permissions: - id-token: write - pages: write - actions: write - contents: read - steps: - - uses: actions/checkout@v3 - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: 3.11 - - - # use uv package manager - - name: Install uv - run: pip install uv - - uses: actions/cache@v3 - name: Cache dependencies - with: - path: ~/.cache/uv - key: uv-${{ hashFiles('pyproject.toml') }} - - name: Install dependencies - run: | - uv venv - uv pip install -e ".[dev]" - - name: Lint - run: uv run poe lint - - name: Types - run: uv run poe type-check - - name: Docs - run: uv run poe doc-build - - name: Upload artifact - uses: actions/upload-pages-artifact@v2 - with: - path: "docs/_build" - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v2 \ No newline at end of file From 63fd5bfb5996ada92ebfe71beaffba4f1d0027b2 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Sat, 8 Nov 2025 01:09:15 +0100 Subject: [PATCH 12/21] Update README, removing parts now in the user guide and adding links instead --- README.md | 727 ++---------------------------------------------------- 1 file changed, 25 insertions(+), 702 deletions(-) diff --git a/README.md b/README.md index 4c220ba8..90a53862 100644 --- a/README.md +++ b/README.md @@ -8,23 +8,18 @@ * :wrench: Serena provides essential **semantic code retrieval and editing tools** that are akin to an IDE's capabilities, extracting code entities at the symbol level and exploiting relational structure. When combined with an existing coding agent, these tools greatly enhance (token) efficiency. * :free: Serena is **free & open-source**, enhancing the capabilities of LLMs you already have access to free of charge. -You can think of Serena as providing IDE-like tools to your LLM/coding agent. With it, the agent no longer needs to read entire -files, perform grep-like searches or string replacements to find and edit the right code. Instead, it can use code centered tools like `find_symbol`, `find_referencing_symbols` and `insert_after_symbol`. +You can think of Serena as providing IDE-like tools to your LLM/coding agent. +With it, the agent no longer needs to read entire files, perform grep-like searches or basic string replacements to find the right parts of the code and to edit code. +Instead, it can use code-centric tools like `find_symbol`, `find_referencing_symbols` and `insert_after_symbol`.

Serena is under active development! See the latest updates, upcoming features, and lessons learned to stay up to date.

- - Changelog - - - Roadmap - - - Lessons Learned - + Changelog + Roadmap + Lessons Learned

### LLM Integration @@ -39,7 +34,7 @@ In general, Serena can be integrated with an LLM in several ways: * by using the **model context protocol (MCP)**. Serena provides an MCP server which integrates with * Claude Code and Claude Desktop, - * Terminal-based clients like Codex, Gemini-CLI, Qwen3-Coder, rovodev, OpenHands CLI and others, + * terminal-based clients like Codex, Gemini-CLI, Qwen3-Coder, rovodev, OpenHands CLI and others, * IDEs like VSCode, Cursor or IntelliJ, * Extensions like Cline or Roo Code * Local clients like [OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp), [Jan](https://jan.ai/docs/mcp-examples/browser/browserbase#enable-mcp), [Agno](https://docs.agno.com/introduction/playground) and others @@ -74,39 +69,15 @@ complex projects! So not only is it free and open-source, it frequently achieves than existing solutions that charge a premium. Language servers provide support for a wide range of programming languages. -With Serena, we provide direct, out-of-the-box support for: +With Serena's LSP library, we provide **support for over 30 programming languages**, including +AL, Bash, C#, C/C++, Clojure, Dart, Elixir, Elm, Erlang, Fortran, Go, Haskell, Java, Javascript, Julia, Kotlin, Lua, Markdown, Nix, Perl, PHP, Python, R, Ruby, Rust, Scala, Swift, TypeScript and Zig. - * Python - * TypeScript/Javascript - * PHP (uses Intelephense LSP; set `INTELEPHENSE_LICENSE_KEY` environment variable for premium features) - * Go (requires installation of gopls) - * R (requires installation of the `languageserver` R package) - * Rust (requires [rustup](https://rustup.rs/) - uses rust-analyzer from your toolchain) - * C/C++ (you may experience issues with finding references, we are working on it) - * Zig (requires installation of ZLS - Zig Language Server) - * C# - * Ruby (by default, uses [ruby-lsp](https://github.com/Shopify/ruby-lsp), specify ruby_solargraph as your language to use the previous solargraph based implementation) - * Swift - * Kotlin (uses the pre-alpha [official kotlin LS](https://github.com/Kotlin/kotlin-lsp), some issues may appear) - * Java (_Note_: startup is slow, initial startup especially so. There may be issues with java on macos and linux, we are working on it.) - * Clojure - * Dart - * Bash - * Lua (automatically downloads lua-language-server if not installed) - * Nix (requires nixd installation) - * Elixir (requires installation of NextLS and Elixir; **Windows not supported**) - * Elm (automatically downloads elm-language-server if not installed; requires Elm compiler) - * Scala (requires some [manual setup](docs/scala_setup_guide_for_serena.md); uses Metals LSP) - * Erlang (requires installation of beam and [erlang_ls](https://github.com/erlang-ls/erlang_ls), experimental, might be slow or hang) - * Perl (requires installation of Perl::LanguageServer) - * Fortran (requires installation of fortls: `pip install fortls`) - * Haskell (automatically locates HLS via ghcup, stack, or system PATH; supports Stack and Cabal projects) - * Julia - * AL - * Markdown (must be explicitly specified via `--language markdown` when generating project config, primarily useful for documentation-heavy projects) +> [!IMPORTANT] +> Some languages require additional dependencies to be installed; see the [Language Support](https://oraios.github.io/serena/01-about/020_programming-languages.html) page for details. -Support for further languages can easily be added by providing a shallow adapter for a new language server implementation, -see Serena's [memory on that](.serena/memories/adding_new_language_support_guide.md). +> [!TIP] +> Support for further languages can easily be added by providing a shallow adapter for a new language server implementation, +> see Serena's [memory on that](.serena/memories/adding_new_language_support_guide.md). ### Community Feedback @@ -129,672 +100,24 @@ Several videos and blog posts have talked about Serena: * [Serena with Claude Code (in Japanese)](https://blog.lai.so/serena/) * [Turning Claude Code into a Development Powerhouse](https://robertmarshall.dev/blog/turning-claude-code-into-a-development-powerhouse/) -## Table of Contents - - - - - - -- [Quick Start](#quick-start) - * [Running the Serena MCP Server](#running-the-serena-mcp-server) - + [Usage](#usage) - + [Using uvx](#using-uvx) - + [Local Installation](#local-installation) - + [Using Docker (Experimental)](#using-docker-experimental) - + [Using Nix](#using-nix) - + [Streamable HTTP Mode](#streamable-http-mode) - + [Command-Line Arguments](#command-line-arguments) - * [Configuration](#configuration) - * [Project Activation & Indexing](#project-activation--indexing) - * [Claude Code](#claude-code) - * [Codex](#codex) - * [Other Terminal-Based Clients](#other-terminal-based-clients) - * [Claude Desktop](#claude-desktop) - * [MCP Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.)](#mcp-coding-clients-cline-roo-code-cursor-windsurf-etc) - * [Local GUIs and Frameworks](#local-guis-and-frameworks) -- [Detailed Usage and Recommendations](#detailed-usage-and-recommendations) - * [Tool Execution](#tool-execution) - + [Shell Execution and Editing Tools](#shell-execution-and-editing-tools) - * [Modes and Contexts](#modes-and-contexts) - + [Contexts](#contexts) - + [Modes](#modes) - + [Customization](#customization) - * [Onboarding and Memories](#onboarding-and-memories) - * [Prepare Your Project](#prepare-your-project) - + [Structure Your Codebase](#structure-your-codebase) - + [Start from a Clean State](#start-from-a-clean-state) - + [Logging, Linting, and Automated Tests](#logging-linting-and-automated-tests) - * [Prompting Strategies](#prompting-strategies) - * [Running Out of Context](#running-out-of-context) - * [Serena's Logs: The Dashboard and GUI Tool](#serenas-logs-the-dashboard-and-gui-tool) - * [Serena and GIT worktrees](#serena-and-git-worktrees) -- [Comparison with Other Coding Agents](#comparison-with-other-coding-agents) - * [Subscription-Based Coding Agents](#subscription-based-coding-agents) - * [API-Based Coding Agents](#api-based-coding-agents) - * [Other MCP-Based Coding Agents](#other-mcp-based-coding-agents) -- [Acknowledgements](#acknowledgements) - * [Sponsors](#sponsors) - * [Community Contributions](#community-contributions) - * [Technologies](#technologies) -- [Customizing and Extending Serena](#customizing-and-extending-serena) -- [List of Tools](#list-of-tools) - - - ## Quick Start -Serena can be used in various ways, below you will find instructions for selected integrations. +Serena is managed with **uv**. If you don’t already have it installed, you will need to [install it](https://docs.astral.sh/uv/getting-started/installation/). -* For coding with Claude, we recommend using Serena through [Claude Code](#claude-code) or [Claude Desktop](#claude-desktop). You can also use Serena in most other [terminal-based clients](#other-terminal-based-clients). -* If you want a GUI experience outside an IDE, you can use one of the many [local GUIs](#local-guis-and-frameworks) that support MCP servers. - You can also connect Serena to many web clients (including ChatGPT) using [mcpo](docs/03-special-guides/serena_on_chatgpt.md). -* If you want to use Serena integrated in your IDE, see the section on [other MCP clients](#other-mcp-clients---cline-roo-code-cursor-windsurf-etc). -* You can use Serena as a library for building your own applications. We try to keep the public API stable, but you should still - expect breaking changes and pin Serena to a fixed version if you use it as a dependency. +To get started as quickly as possible, you can directly enable the Serena MCP server in your client of choice (by following the links provided): -Serena is managed by `uv`, so you will need to [install it](https://docs.astral.sh/uv/getting-started/installation/). +* For coding with Claude, we recommend using Serena through [Claude Code](https://oraios.github.io/serena/02-usage/030_clients.html#claude-code) or [Claude Desktop](#claude-desktop). You can also use Serena in [Codex](https://oraios.github.io/serena/02-usage/030_clients.html#codex) and a wide variety of [other clients](https://oraios.github.io/serena/02-usage/030_clients.html#other-clients). +* If you want a GUI experience outside an IDE, you can use one of the many [local GUIs](https://oraios.github.io/serena/02-usage/030_clients.html#local-guis-and-agent-frameworks) that support MCP servers. + You can also connect Serena to many web clients (including ChatGPT) using [mcpo](https://oraios.github.io/serena/03-special-guides/serena_on_chatgpt.html). +* If you want to integrate Serena with your IDE, see the section on [other MCP clients](https://oraios.github.io/serena/02-usage/030_clients.html#mcp-enabled-ides-and-coding-clients-cline-roo-code-cursor-windsurf-etc). -### Running the Serena MCP Server +> [!TIP] +> While getting started quickly is easy, Serena is a powerful toolkit with many configuration options. +> We highly recommend reading through the [user guide](https://oraios.github.io/serena/) to get the most out of Serena. -You have several options for running the MCP server, which are explained in the subsections below. +## User Guide -#### Usage - -The typical usage involves the client (Claude Code, Claude Desktop, etc.) running -the MCP server as a subprocess (using stdio communication), -so the client needs to be provided with the command to run the MCP server. -(Alternatively, you can run the MCP server in Streamable HTTP or SSE mode and tell your client -how to connect to it.) - -Note that no matter how you run the MCP server, Serena will, by default, start a small web-based dashboard on localhost that will display logs and allow shutting down the -MCP server (since many clients fail to clean up processes correctly). -This and other settings can be adjusted in the [configuration](#configuration) and/or by providing [command-line arguments](#command-line-arguments). - -#### Using uvx - -`uvx` can be used to run the latest version of Serena directly from the repository, without an explicit local installation. - -```shell -uvx --from git+https://github.com/oraios/serena serena start-mcp-server -``` - -Explore the CLI to see some of the customization options that serena provides (more info on them below). - -#### Local Installation - -1. Clone the repository and change into it. - - ```shell - git clone https://github.com/oraios/serena - cd serena - ``` - -2. Optionally edit the configuration file in your home directory with - - ```shell - uv run serena config edit - ``` - - If you just want the default config, you can skip this part, and a config file will be created when you first run Serena. -3. Run the server with `uv`: - - ```shell - uv run serena start-mcp-server - ``` - - When running from outside the serena installation directory, be sure to pass it, i.e., use - - ```shell - uv run --directory /abs/path/to/serena serena start-mcp-server - ``` - -#### Using Docker (Experimental) - -⚠️ Docker support is currently experimental with several limitations. Please read the [Docker documentation](DOCKER.md) for important caveats before using it. - -You can run the Serena MCP server directly via docker as follows, -assuming that the projects you want to work on are all located in `/path/to/your/projects`: - -```shell -docker run --rm -i --network host -v /path/to/your/projects:/workspaces/projects ghcr.io/oraios/serena:latest serena start-mcp-server --transport stdio -``` - -Replace `/path/to/your/projects` with the absolute path to your projects directory. The Docker approach provides: - -* Better security isolation for shell command execution -* No need to install language servers and dependencies locally -* Consistent environment across different systems - -Alternatively, use docker compose with the `compose.yml` file provided in the repository. - -See the [Docker documentation](DOCKER.md) for detailed setup instructions, configuration options, and known limitations. - -#### Using Nix - -If you are using Nix and [have enabled the `nix-command` and `flakes` features](https://nixos.wiki/wiki/flakes), you can run Serena using the following command: - -```bash -nix run github:oraios/serena -- start-mcp-server --transport stdio -``` - -You can also install Serena by referencing this repo (`github:oraios/serena`) and using it in your Nix flake. The package is exported as `serena`. - -#### Streamable HTTP Mode - -ℹ️ Note that MCP servers which use stdio as a protocol are somewhat unusual as far as client/server architectures go, as the server -necessarily has to be started by the client in order for communication to take place via the server's standard input/output stream. -In other words, you do not need to start the server yourself. The client application (e.g. Claude Desktop) takes care of this and -therefore needs to be configured with a launch command. - -When using instead the *Streamable HTTP* mode, you control the server lifecycle yourself, -i.e. you start the server and provide the client with the URL to connect to it. - -Simply provide `start-mcp-server` with the `--transport streamable-http` option and optionally provide the port. -For example, to run the Serena MCP server in Streamable HTTP mode on port 9121 using a local installation, -you would run this command from the Serena directory, - -```shell -uv run serena start-mcp-server --transport streamable-http --port 9121 -``` - -and then configure your client to connect to `http://localhost:9121/mcp`. - -ℹ️ Note that SSE transport is supported as well, but its use is discouraged. -Use Streamable HTTP instead. - -#### Command-Line Arguments - -The Serena MCP server supports a wide range of additional command-line options, including the option to run in Streamable HTTP or SSE mode -and to adapt Serena to various [contexts and modes of operation](#modes-and-contexts). - -Run with parameter `--help` to get a list of available options. - -### Configuration - -Serena is very flexible in terms of configuration. While for most users, the default configurations will work, -you can fully adjust it to your needs by editing a few yaml files. You can disable tools, change Serena's instructions -(what we denote as the `system_prompt`), adjust the output of tools that just provide a prompt, and even adjust tool descriptions. - -Serena is configured in four places: - -1. The `serena_config.yml` for general settings that apply to all clients and projects. - It is located in your user directory under `.serena/serena_config.yml`. - If you do not explicitly create the file, it will be auto-generated when you first run Serena. - You can edit it directly or use - - ```shell - uvx --from git+https://github.com/oraios/serena serena config edit - ``` - - (or use the `--directory` command version). -2. In the arguments passed to the `start-mcp-server` in your client's config (see below), - which will apply to all sessions started by the respective client. In particular, the [context](#contexts) parameter - should be set appropriately for Serena to be best adjusted to existing tools and capabilities of your client. - See for a detailed explanation. You can override all entries from the `serena_config.yml` through command line arguments. -3. In the `.serena/project.yml` file within your project. This will hold project-level configuration that is used whenever - that project is activated. This file will be autogenerated when you first use Serena on that project, but you can also - generate it explicitly with - - ```shell - uvx --from git+https://github.com/oraios/serena serena project generate-yml - ``` - - (or use the `--directory` command version). -4. Through the context and modes. Explore the [modes and contexts](#modes-and-contexts) section for more details. - -After the initial setup, continue with one of the sections below, depending on how you -want to use Serena. - -### Project Activation & Indexing - -If you are mostly working with the same project, you can configure to always activate it at startup -by passing `--project ` to the `start-mcp-server` command in your client's MCP config. -This is especially useful for clients which configure MCP servers on a per-project basis, like Claude Code. - -Otherwise, the recommended way is to just ask the LLM to activate a project by providing it an absolute path to, or, -in case the project was activated in the past, by its name. The default project name is the directory name. - -* "Activate the project /path/to/my_project" -* "Activate the project my_project" - -All projects that have been activated will be automatically added to your `serena_config.yml`, and for each -project, the file `.serena/project.yml` will be generated. You can adjust the latter, e.g., by changing the name -(which you refer to during the activation) or other options. Make sure to not have two different projects with the -same name. - -ℹ️ For larger projects, we recommend that you index your project to accelerate Serena's tools; otherwise the first -tool application may be very slow. -To do so, run this from the project directory (or pass the path to the project as an argument): - -```shell -uvx --from git+https://github.com/oraios/serena serena project index -``` - -(or use the `--directory` command version). - -### Claude Code - -Serena is a great way to make Claude Code both cheaper and more powerful! - -From your project directory, add serena with a command like this, - -```shell -claude mcp add serena -- --context ide-assistant --project "$(pwd)" -``` - -where `` is your way of [running the Serena MCP server](#running-the-serena-mcp-server). -For example, when using `uvx`, you would run - -```shell -claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project "$(pwd)" -``` - -ℹ️ Serena comes with an instruction text, and Claude needs to read it to properly use Serena's tools. - As of version `v1.0.52`, claude code reads the instructions of the MCP server, so this **is handled automatically**. - If you are using an older version, or if Claude fails to read the instructions, you can ask it explicitly - to "read Serena's initial instructions" or run `/mcp__serena__initial_instructions` to load the instruction text. - If you want to make use of that, you will have to enable the corresponding tool explicitly by adding `initial_instructions` to the `included_optional_tools` - in your config. - Note that you may have to make Claude read the instructions when you start a new conversation and after any compacting operation to ensure Claude remains properly configured to use Serena's tools. - -### Codex - -Serena works with OpenAI's Codex CLI out of the box, but you have to use the `codex` context for it to work properly. (The technical reason is that Codex doesn't fully support the MCP specifications, so some massaging of tools is required.). - -Unlike Claude Code, in Codex you add an MCP server globally and not per project. Add the following to -`~/.codex/config.toml` (create the file if it does not exist): - -```toml -[mcp_servers.serena] -command = "uvx" -args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"] -``` - -After codex has started, you need to activate the project, which you can do by saying: - -"Activate the current dir as project using serena" - -> If you don't activate the project, you will not be able to use Serena's tools! - -That's it! Have a look at `~/.codex/log/codex-tui.log` to see if any errors occurred. - -The Serena dashboard will run if you have not disabled it in the configuration, but due to Codex's sandboxing the webbrowser -may not open automatically. You can open it manually by going to `http://localhost:24282/dashboard/index.html` (or a higher port, if -that was already taken). - -> Codex will often show the tools as `failed` even though they are successfully executed. This is not a problem, seems to be a bug in Codex. Despite the error message, everything works as expected. - -### Other Terminal-Based Clients - -There are many terminal-based coding assistants that support MCP servers, such as [Codex](https://github.com/openai/codex?tab=readme-ov-file#model-context-protocol-mcp), -[Gemini-CLI](https://github.com/google-gemini/gemini-cli), [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder), -[rovodev](https://community.atlassian.com/forums/Rovo-for-Software-Teams-Beta/Introducing-Rovo-Dev-CLI-AI-Powered-Development-in-your-terminal/ba-p/3043623), -the [OpenHands CLI](https://docs.all-hands.dev/usage/how-to/cli-mode) and [opencode](https://github.com/sst/opencode). - -They generally benefit from the symbolic tools provided by Serena. You might want to customize some aspects of Serena -by writing your own context, modes or prompts to adjust it to your workflow, to other MCP servers you are using, and to -the client's internal capabilities. - -### Claude Desktop - -For [Claude Desktop](https://claude.ai/download) (available for Windows and macOS), go to File / Settings / Developer / MCP Servers / Edit Config, -which will let you open the JSON file `claude_desktop_config.json`. -Add the `serena` MCP server configuration, using a [run command](#running-the-serena-mcp-server) depending on your setup. - -* local installation: - - ```json - { - "mcpServers": { - "serena": { - "command": "/abs/path/to/uv", - "args": ["run", "--directory", "/abs/path/to/serena", "serena", "start-mcp-server"] - } - } - } - ``` - -* uvx: - - ```json - { - "mcpServers": { - "serena": { - "command": "/abs/path/to/uvx", - "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"] - } - } - } - ``` - -* docker: - - ```json - { - "mcpServers": { - "serena": { - "command": "docker", - "args": ["run", "--rm", "-i", "--network", "host", "-v", "/path/to/your/projects:/workspaces/projects", "ghcr.io/oraios/serena:latest", "serena", "start-mcp-server", "--transport", "stdio"] - } - } - } - ``` - -If you are using paths containing backslashes for paths on Windows -(note that you can also just use forward slashes), be sure to escape them correctly (`\\`). - -That's it! Save the config and then restart Claude Desktop. You are ready for activating your first project. - -ℹ️ You can further customize the run command using additional arguments (see [above](#command-line-arguments)). - -Note: on Windows and macOS there are official Claude Desktop applications by Anthropic, for Linux there is an [open-source -community version](https://github.com/aaddrick/claude-desktop-debian). - -⚠️ Be sure to fully quit the Claude Desktop application, as closing Claude will just minimize it to the system tray – at least on Windows. - -⚠️ Some clients may leave behind zombie processes. You will have to find and terminate them manually then. - With Serena, you can activate the [dashboard](#serenas-logs-the-dashboard-and-gui-tool) to prevent unnoted processes and also use the dashboard - for shutting down Serena. - -After restarting, you should see Serena's tools in your chat interface (notice the small hammer icon). - -For more information on MCP servers with Claude Desktop, see [the official quick start guide](https://modelcontextprotocol.io/quickstart/user). - -### MCP Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) - -Being an MCP Server, Serena can be included in any MCP Client. The same configuration as above, -perhaps with small client-specific modifications, should work. Most of the popular -existing coding assistants (IDE extensions or VSCode-like IDEs) support connections -to MCP Servers. It is **recommended to use the `ide-assistant` context** for these integrations by adding `"--context", "ide-assistant"` to the `args` in your MCP client's configuration. Including Serena generally boosts their performance -by providing them tools for symbolic operations. - -In this case, the billing for the usage continues to be controlled by the client of your choice -(unlike with the Claude Desktop client). But you may still want to use Serena through such an approach, -e.g., for one of the following reasons: - -1. You are already using a coding assistant (say Cline or Cursor) and just want to make it more powerful. -2. You are on Linux and don't want to use the [community-created Claude Desktop](https://github.com/aaddrick/claude-desktop-debian). -3. You want tighter integration of Serena into your IDE and don't mind paying for that. - -### Local GUIs and Frameworks - -Over the last months, several technologies have emerged that allow you to run a powerful local GUI -and connect it to an MCP server. They will work with Serena out of the box. -Some of the leading open source GUI technologies offering this are -[Jan](https://jan.ai/docs/mcp), [OpenHands](https://github.com/All-Hands-AI/OpenHands/), -[OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp) and [Agno](https://docs.agno.com/introduction/playground). -They allow combining Serena with almost any LLM (including locally running ones) and offer various other integrations. - -## Detailed Usage and Recommendations - -### Tool Execution - -Serena combines tools for semantic code retrieval with editing capabilities and shell execution. -Serena's behavior can be further customized through [Modes and Contexts](#modes-and-contexts). -Find the complete list of tools [below](#full-list-of-tools). - -The use of all tools is generally recommended, as this allows Serena to provide the most value: -Only by executing shell commands (in particular, tests) can Serena identify and correct mistakes -autonomously. - -#### Shell Execution and Editing Tools - -Many clients have their own shell execution tool, and by default Serena's shell tool will be disabled in them -(e.g., when using the `ide-assistant` or `codex` context). However, when using Serena through something like -Claude Desktop or ChatGPT, it is recommended to enable Serena's `execute_shell_command` tool to allow -agentic behavior. - -It should be noted that the `execute_shell_command` tool allows for arbitrary code execution. -When using Serena as an MCP Server, clients will typically ask the user for permission -before executing a tool, so as long as the user inspects execution parameters beforehand, -this should not be a problem. -However, if you have concerns, you can choose to disable certain commands in your project's configuration file. -If you only want to use Serena purely for analyzing code and suggesting implementations -without modifying the codebase, you can enable read-only mode by setting `read_only: true` in your project configuration file. -This will automatically disable all editing tools and prevent any modifications to your codebase while still -allowing all analysis and exploration capabilities. - -In general, be sure to back up your work and use a version control system in order to avoid -losing any work. - -### Modes and Contexts - -Serena's behavior and toolset can be adjusted using contexts and modes. -These allow for a high degree of customization to best suit your workflow and the environment Serena is operating in. - -#### Contexts - -A context defines the general environment in which Serena is operating. -It influences the initial system prompt and the set of available tools. -A context is set at startup when launching Serena (e.g., via CLI options for an MCP server or in the agent script) and cannot be changed during an active session. - -Serena comes with pre-defined contexts: - -* `desktop-app`: Tailored for use with desktop applications like Claude Desktop. This is the default. -* `agent`: Designed for scenarios where Serena acts as a more autonomous agent, for example, when used with Agno. -* `ide-assistant`: Optimized for integration into IDEs like VSCode, Cursor, or Cline, focusing on in-editor coding assistance. -Choose the context that best matches the type of integration you are using. - -When launching Serena, specify the context using `--context `. -Note that for cases where parameter lists are specified (e.g. Claude Desktop), you must add two parameters to the list. - -If you are using a local server (such as Llama.cpp) which requires you to use OpenAI-compatible tool descriptions, use context `oaicompat-agent` instead of `agent`. - -#### Modes - -Modes further refine Serena's behavior for specific types of tasks or interaction styles. Multiple modes can be active simultaneously, allowing you to combine their effects. Modes influence the system prompt and can also alter the set of available tools by excluding certain ones. - -Examples of built-in modes include: - -* `planning`: Focuses Serena on planning and analysis tasks. -* `editing`: Optimizes Serena for direct code modification tasks. -* `interactive`: Suitable for a conversational, back-and-forth interaction style. -* `one-shot`: Configures Serena for tasks that should be completed in a single response, often used with `planning` for generating reports or initial plans. -* `no-onboarding`: Skips the initial onboarding process if it's not needed for a particular session. -* `onboarding`: (Usually triggered automatically) Focuses on the project onboarding process. - -Modes can be set at startup (similar to contexts) but can also be _switched dynamically_ during a session. You can instruct the LLM to use the `switch_modes` tool to activate a different set of modes (e.g., "switch to planning and one-shot modes"). - -When launching Serena, specify modes using `--mode `; multiple modes can be specified, e.g. `--mode planning --mode no-onboarding`. - -:warning: **Mode Compatibility**: While you can combine modes, some may be semantically incompatible (e.g., `interactive` and `one-shot`). Serena currently does not prevent incompatible combinations; it is up to the user to choose sensible mode configurations. - -#### Customization - -You can create your own contexts and modes to precisely tailor Serena to your needs in two ways: - -* You can use Serena's CLI to manage modes and contexts. Check out - - ```shell - uvx --from git+https://github.com/oraios/serena serena mode --help - ``` - - and - - ```shell - uvx --from git+https://github.com/oraios/serena serena context --help - ``` - - _NOTE_: Custom contexts/modes are simply YAML files in `/.serena`, they are automatically registered and available for use by their name (filename without the `.yml` extension). If you don't want to use Serena's CLI, you can create and manage them in any way you see fit. -* **Using external YAML files**: When starting Serena, you can also provide an absolute path to a custom `.yml` file for a context or mode. - -This customization allows for deep integration and adaptation of Serena to specific project requirements or personal preferences. - -### Onboarding and Memories - -By default, Serena will perform an **onboarding process** when -it is started for the first time for a project. -The goal of the onboarding is for Serena to get familiar with the project -and to store memories, which it can then draw upon in future interactions. -If an LLM should fail to complete the onboarding and does not actually write the -respective memories to disk, you may need to ask it to do so explicitly. - -The onboarding will usually read a lot of content from the project, thus filling -up the context. It can therefore be advisable to switch to another conversation -once the onboarding is complete. -After the onboarding, we recommend that you have a quick look at the memories and, -if necessary, edit them or add additional ones. - -**Memories** are files stored in `.serena/memories/` in the project directory, -which the agent can choose to read in subsequent interactions. -Feel free to read and adjust them as needed; you can also add new ones manually. -Every file in the `.serena/memories/` directory is a memory file. -Whenever Serena starts working on a project, the list of memories is -provided, and the agent can decide to read them. -We found that memories can significantly improve the user experience with Serena. - -### Prepare Your Project - -#### Structure Your Codebase - -Serena uses the code structure for finding, reading and editing code. This means that it will -work well with well-structured code but may perform poorly on fully unstructured one (like a "God class" -with enormous, non-modular functions). -Furthermore, for languages that are not statically typed, type annotations are highly beneficial. - -#### Start from a Clean State - -It is best to start a code generation task from a clean git state. Not only will -this make it easier for you to inspect the changes, but also the model itself will -have a chance of seeing what it has changed by calling `git diff` and thereby -correct itself or continue working in a followup conversation if needed. - -:warning: **Important**: since Serena will write to files using the system-native line endings -and it might want to look at the git diff, it is important to -set `git config core.autocrlf` to `true` on Windows. -With `git config core.autocrlf` set to `false` on Windows, you may end up with huge diffs -only due to line endings. It is generally a good idea to globally enable this git setting on Windows: - -```shell -git config --global core.autocrlf true -``` - -#### Logging, Linting, and Automated Tests - -Serena can successfully complete tasks in an _agent loop_, where it iteratively -acquires information, performs actions, and reflects on the results. -However, Serena cannot use a debugger; it must rely on the results of program executions, -linting results, and test results to assess the correctness of its actions. -Therefore, software that is designed to meaningful interpretable outputs (e.g. log messages) -and that has a good test coverage is much easier to work with for Serena. - -We generally recommend to start an editing task from a state where all linting checks and tests pass. - -### Prompting Strategies - -We found that it is often a good idea to spend some time conceptualizing and planning a task -before actually implementing it, especially for non-trivial task. This helps both in achieving -better results and in increasing the feeling of control and staying in the loop. You can -make a detailed plan in one session, where Serena may read a lot of your code to build up the context, -and then continue with the implementation in another (potentially after creating suitable memories). - -### Running Out of Context - -For long and complicated tasks, or tasks where Serena has read a lot of content, you -may come close to the limits of context tokens. In that case, it is often a good idea to continue -in a new conversation. Serena has a dedicated tool to create a summary of the current state -of the progress and all relevant info for continuing it. You can request to create this summary and -write it to a memory. Then, in a new conversation, you can just ask Serena to read the memory and -continue with the task. In our experience, this worked really well. On the up-side, since in a -single session there is no summarization involved, Serena does not usually get lost (unlike some -other agents that summarize under the hood), and it is also instructed to occasionally check whether -it's on the right track. - -Moreover, Serena is instructed to be frugal with context -(e.g., to not read bodies of code symbols unnecessarily), -but we found that Claude is not always very good in being frugal (Gemini seemed better at it). -You can explicitly instruct it to not read the bodies if you know that it's not needed. - -### Serena's Logs: The Dashboard and GUI Tool - -Serena provides two convenient ways of accessing the logs of the current session: - -* via the **web-based dashboard** (enabled by default) - - This is supported on all platforms. - By default, it will be accessible at `http://localhost:24282/dashboard/index.html`, - but a higher port may be used if the default port is unavailable/multiple instances are running. - -* via the **GUI tool** (disabled by default) - - This is mainly supported on Windows, but it may also work on Linux; macOS is unsupported. - -Both can be enabled, configured or disabled in Serena's configuration file (`serena_config.yml`, see above). -If enabled, they will automatically be opened as soon as the Serena agent/MCP server is started. -The web dashboard will display usage statistics of Serena's tools if you set `record_tool_usage_stats: True` in your config. - -In addition to viewing logs, both tools allow to shut down the Serena agent. -This function is provided, because clients like Claude Desktop may fail to terminate the MCP server subprocess -when they themselves are closed. - -### Serena and GIT worktrees -[git-worktree](https://git-scm.com/docs/git-worktree) can be an excellent way to parallelize your work. More on this in [Anthropic: Run parallel Claude Code sessions with Git worktrees](https://docs.claude.com/en/docs/claude-code/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees). - -When it comes to serena AND git-worktree AND larger projects (that take longer to index), the recommended way is to COPY your `$ORIG_PROJECT/.serena/cache` to `$GIT_WORKTREE/.serena/cache`. After you have performed pre-indexing of your project described in [Project Activation & Indexing](#project-activation--indexing) section. To avoid having to re-index per each git work tree that you create. - - -## Comparison with Other Coding Agents - -To our knowledge, Serena is the first fully-featured coding agent where the -entire functionality -is available through an MCP server, thus not requiring API keys or -subscriptions. - -### Subscription-Based Coding Agents - -Many prominent subscription-based coding agents are parts of IDEs like -Windsurf, Cursor and VSCode. -Serena's functionality is similar to Cursor's Agent, Windsurf's Cascade or -VSCode's agent mode. - -Serena has the advantage of not requiring a subscription. -A potential disadvantage is that it -is not directly integrated into an IDE, so the inspection of newly written code -is not as seamless. - -More technical differences are: - -* Serena is not bound to a specific IDE or CLI. - Serena's MCP server can be used with any MCP client (including some IDEs), - and the Agno-based agent provides additional ways of applying its functionality. -* Serena is not bound to a specific large language model or API. -* Serena navigates and edits code using a language server, so it has a symbolic - understanding of the code. - IDE-based tools often use a RAG-based or purely text-based approach, which is often - less powerful, especially for large codebases. -* Serena is open-source and has a small codebase, so it can be easily extended - and modified. - -### API-Based Coding Agents - -An alternative to subscription-based agents are API-based agents like Claude -Code, Cline, Aider, Roo Code and others, where the usage costs map directly -to the API costs of the underlying LLM. -Some of them (like Cline) can even be included in IDEs as an extension. -They are often very powerful and their main downside are the (potentially very -high) API costs. - -Serena itself can be used as an API-based agent (see the section on Agno above). -We have not yet written a CLI tool or a -dedicated IDE extension for Serena (and there is probably no need for the latter, as -Serena can already be used with any IDE that supports MCP servers). -If there is demand for a Serena as a CLI tool like Claude Code, we will -consider writing one. - -The main difference between Serena and other API-based agents is that Serena can -also be used as an MCP server, thus not requiring -an API key and bypassing the API costs. This is a unique feature of Serena. - -### Other MCP-Based Coding Agents - -There are other MCP servers designed for coding, like [DesktopCommander](https://github.com/wonderwhy-er/DesktopCommanderMCP) and -[codemcp](https://github.com/ezyang/codemcp). -However, to the best of our knowledge, none of them provide semantic code -retrieval and editing tools; they rely purely on text-based analysis. -It is the integration of language servers and the MCP that makes Serena unique -and so powerful for challenging coding tasks, especially in the context of -larger codebases. +Please refer to the [user guide](https://oraios.github.io/serena/) for detailed instructions on how to use Serena effectively. ## Acknowledgements From 766ecbccd49d12a7b5771d93c5761d03beef4f7d Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Sat, 8 Nov 2025 01:21:11 +0100 Subject: [PATCH 13/21] Move tool list to docs, restructure README --- README.md | 115 +++++++++---------------------------- docs/01-about/035_tools.md | 47 +++++++++++++++ 2 files changed, 74 insertions(+), 88 deletions(-) create mode 100644 docs/01-about/035_tools.md diff --git a/README.md b/README.md index 90a53862..12bd2861 100644 --- a/README.md +++ b/README.md @@ -22,13 +22,11 @@ Instead, it can use code-centric tools like `find_symbol`, `find_referencing_sym Lessons Learned

-### LLM Integration +## LLM Integration -Serena provides the necessary [tools](#list-of-tools) for coding workflows, but an LLM is required to do the actual work, +Serena provides the necessary [tools](https://oraios.github.io/serena/01-about/035_tools.html) for coding workflows, but an LLM is required to do the actual work, orchestrating tool use. -For example, **supercharge the performance of Claude Code** with a [one-line shell command](#claude-code). - In general, Serena can be integrated with an LLM in several ways: * by using the **model context protocol (MCP)**. @@ -42,7 +40,7 @@ In general, Serena can be integrated with an LLM in several ways: * by incorporating Serena's tools into an agent framework of your choice, as illustrated [here](docs/03-special-guides/custom_agent.md). Serena's tool implementation is decoupled from the framework-specific code and can thus easily be adapted to any agent framework. -### Serena in Action +## Serena in Action #### Demonstration 1: Efficient Operation in Claude Code @@ -75,31 +73,6 @@ AL, Bash, C#, C/C++, Clojure, Dart, Elixir, Elm, Erlang, Fortran, Go, Haskell, J > [!IMPORTANT] > Some languages require additional dependencies to be installed; see the [Language Support](https://oraios.github.io/serena/01-about/020_programming-languages.html) page for details. -> [!TIP] -> Support for further languages can easily be added by providing a shallow adapter for a new language server implementation, -> see Serena's [memory on that](.serena/memories/adding_new_language_support_guide.md). - -### Community Feedback - -Most users report that Serena has strong positive effects on the results of their coding agents, even when used within -very capable agents like Claude Code. Serena is often described to be a [game changer](https://www.reddit.com/r/ClaudeAI/comments/1lfsdll/try_out_serena_mcp_thank_me_later/), providing an enormous [productivity boost](https://www.reddit.com/r/ClaudeCode/comments/1mguoia/absolutely_insane_improvement_of_claude_code). - -Serena excels at navigating and manipulating complex codebases, providing tools that support precise code retrieval and editing in the presence of large, strongly structured codebases. -However, when dealing with tasks that involve only very few/small files, you may not benefit from including Serena on top of your existing coding agent. -In particular, when writing code from scratch, Serena will not provide much value initially, as the more complex structures that Serena handles more gracefully than simplistic, file-based approaches are yet to be created. - -Several videos and blog posts have talked about Serena: - -* YouTube: - * [AI Labs](https://www.youtube.com/watch?v=wYWyJNs1HVk&t=1s) - * [Yo Van Eyck](https://www.youtube.com/watch?v=UqfxuQKuMo8&t=45s) - * [JeredBlu](https://www.youtube.com/watch?v=fzPnM3ySmjE&t=32s) - -* Blog posts: - * [Serena's Design Principles](https://medium.com/@souradip1000/deconstructing-serenas-mcp-powered-semantic-code-understanding-architecture-75802515d116) - * [Serena with Claude Code (in Japanese)](https://blog.lai.so/serena/) - * [Turning Claude Code into a Development Powerhouse](https://robertmarshall.dev/blog/turning-claude-code-into-a-development-powerhouse/) - ## Quick Start Serena is managed with **uv**. If you don’t already have it installed, you will need to [install it](https://docs.astral.sh/uv/getting-started/installation/). @@ -119,6 +92,27 @@ To get started as quickly as possible, you can directly enable the Serena MCP se Please refer to the [user guide](https://oraios.github.io/serena/) for detailed instructions on how to use Serena effectively. +## Community Feedback + +Most users report that Serena has strong positive effects on the results of their coding agents, even when used within +very capable agents like Claude Code. Serena is often described to be a [game changer](https://www.reddit.com/r/ClaudeAI/comments/1lfsdll/try_out_serena_mcp_thank_me_later/), providing an enormous [productivity boost](https://www.reddit.com/r/ClaudeCode/comments/1mguoia/absolutely_insane_improvement_of_claude_code). + +Serena excels at navigating and manipulating complex codebases, providing tools that support precise code retrieval and editing in the presence of large, strongly structured codebases. +However, when dealing with tasks that involve only very few/small files, you may not benefit from including Serena on top of your existing coding agent. +In particular, when writing code from scratch, Serena will not provide much value initially, as the more complex structures that Serena handles more gracefully than simplistic, file-based approaches are yet to be created. + +Several videos and blog posts have talked about Serena: + +* YouTube: + * [AI Labs](https://www.youtube.com/watch?v=wYWyJNs1HVk&t=1s) + * [Yo Van Eyck](https://www.youtube.com/watch?v=UqfxuQKuMo8&t=45s) + * [JeredBlu](https://www.youtube.com/watch?v=fzPnM3ySmjE&t=32s) + +* Blog posts: + * [Serena's Design Principles](https://medium.com/@souradip1000/deconstructing-serenas-mcp-powered-semantic-code-understanding-architecture-75802515d116) + * [Serena with Claude Code (in Japanese)](https://blog.lai.so/serena/) + * [Turning Claude Code into a Development Powerhouse](https://robertmarshall.dev/blog/turning-claude-code-into-a-development-powerhouse/) + ## Acknowledgements ### Sponsors @@ -148,16 +142,12 @@ what it is today. We built Serena on top of multiple existing open-source technologies, the most important ones being: 1. [multilspy](https://github.com/microsoft/multilspy). - A library which wraps language server implementations and adapts them for interaction via Python - and which provided the basis for our library Solid-LSP (src/solidlsp). + A library which wraps language server implementations and adapts them for interaction via Python. + It provided the basis for our library Solid-LSP (`src/solidlsp`). Solid-LSP provides pure synchronous LSP calls and extends the original library with the symbolic logic that Serena required. 2. [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk) -3. [Agno](https://github.com/agno-agi/agno) and - the associated [agent-ui](https://github.com/agno-agi/agent-ui), - which we use to allow Serena to work with any model, beyond the ones - supporting the MCP. -4. All the language servers that we use through Solid-LSP. +3. All the language servers that we use through Solid-LSP. Without these projects, Serena would not have been possible (or would have been significantly more difficult to build). @@ -173,54 +163,3 @@ It is also relatively straightforward to add [support for a new programming lang We look forward to seeing what the community will come up with! For details on contributing, see [contributing guidelines](/CONTRIBUTING.md). - -## List of Tools - -Here is the list of Serena's default tools with a short description (output of `uv run serena tools list`): - -* `activate_project`: Activates a project based on the project name or path. -* `check_onboarding_performed`: Checks whether project onboarding was already performed. -* `create_text_file`: Creates/overwrites a file in the project directory. -* `delete_memory`: Deletes a memory from Serena's project-specific memory store. -* `execute_shell_command`: Executes a shell command. -* `find_file`: Finds files in the given relative paths -* `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type). -* `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type). -* `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes. -* `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file. -* `insert_after_symbol`: Inserts content after the end of the definition of a given symbol. -* `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol. -* `list_dir`: Lists files and directories in the given directory (optionally with recursion). -* `list_memories`: Lists memories in Serena's project-specific memory store. -* `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building). -* `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context). -* `read_file`: Reads a file within the project directory. -* `read_memory`: Reads the memory with the given name from Serena's project-specific memory store. -* `rename_symbol`: Renames a symbol throughout the codebase using language server refactoring capabilities. -* `replace_regex`: Replaces content in a file by using regular expressions. -* `replace_symbol_body`: Replaces the full definition of a symbol. -* `search_for_pattern`: Performs a search for a pattern in the project. -* `think_about_collected_information`: Thinking tool for pondering the completeness of collected information. -* `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task. -* `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed. -* `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store. - -There are several tools that are disabled by default, and have to be enabled explicitly, e.g., through the context or modes. -Note that several of our default contexts do enable some of these tools. For example, the `desktop-app` context enables the `execute_shell_command` tool. - -The full list of optional tools is (output of `uv run serena tools list --only-optional`): - -* `delete_lines`: Deletes a range of lines within a file. -* `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes. -* `initial_instructions`: Gets the initial instructions for the current project. - Should only be used in settings where the system prompt cannot be set, - e.g. in clients you have no control over, like Claude Desktop. -* `insert_at_line`: Inserts content at a given line in a file. -* `jet_brains_find_referencing_symbols`: Finds symbols that reference the given symbol -* `jet_brains_find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type). -* `jet_brains_get_symbols_overview`: Retrieves an overview of the top-level symbols within a specified file -* `remove_project`: Removes a project from the Serena configuration. -* `replace_lines`: Replaces a range of lines within a file with new content. -* `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen. -* `summarize_changes`: Provides instructions for summarizing the changes made to the codebase. -* `switch_modes`: Activates modes by providing a list of their names diff --git a/docs/01-about/035_tools.md b/docs/01-about/035_tools.md new file mode 100644 index 00000000..67078ded --- /dev/null +++ b/docs/01-about/035_tools.md @@ -0,0 +1,47 @@ +## List of Tools + +Find the full list of Serena's tools below (output of ` tools list --all`). + +Note that in most configurations, only a subset of these tools will be enabled simultaneously (see the section on [configuration](../02-usage/050_configuration) for details). + +* `activate_project`: Activates a project based on the project name or path. +* `check_onboarding_performed`: Checks whether project onboarding was already performed. +* `create_text_file`: Creates/overwrites a file in the project directory. +* `delete_lines`: Deletes a range of lines within a file. +* `delete_memory`: Deletes a memory from Serena's project-specific memory store. +* `execute_shell_command`: Executes a shell command. +* `find_file`: Finds files in the given relative paths +* `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type). +* `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filter + ed by type). +* `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, + contexts, and modes. +* `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file. +* `initial_instructions`: Provides instructions on how to use the Serena toolbox. +* `insert_after_symbol`: Inserts content after the end of the definition of a given symbol. +* `insert_at_line`: Inserts content at a given line in a file. +* `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol. +* `jet_brains_find_referencing_symbols`: Finds symbols that reference the given symbol +* `jet_brains_find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (option + ally filtered by type). +* `jet_brains_get_symbols_overview`: Retrieves an overview of the top-level symbols within a specified file +* `list_dir`: Lists files and directories in the given directory (optionally with recursion). +* `list_memories`: Lists memories in Serena's project-specific memory store. +* `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building). +* `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with th + e necessary context). +* `read_file`: Reads a file within the project directory. +* `read_memory`: Reads the memory with the given name from Serena's project-specific memory store. +* `remove_project`: Removes a project from the Serena configuration. +* `rename_symbol`: Renames a symbol throughout the codebase using language server refactoring capabilities. +* `replace_lines`: Replaces a range of lines within a file with new content. +* `replace_regex`: Replaces content in a file by using regular expressions. +* `replace_symbol_body`: Replaces the full definition of a symbol. +* `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen. +* `search_for_pattern`: Performs a search for a pattern in the project. +* `summarize_changes`: Provides instructions for summarizing the changes made to the codebase. +* `switch_modes`: Activates modes by providing a list of their names +* `think_about_collected_information`: Thinking tool for pondering the completeness of collected information. +* `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task. +* `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed. +* `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store. From 530926c83679d54a6bf8506e204395b226569cb8 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Sat, 8 Nov 2025 12:24:46 +0100 Subject: [PATCH 14/21] Several docs improvements (proof-reading) --- docs/01-about/000_intro.md | 1 + docs/01-about/010_llm-integration.md | 6 +- docs/01-about/020_programming-languages.md | 12 +-- .../040_comparison-to-other-agents.md | 28 +++---- docs/01-about/050_acknowledgements.md | 30 ++----- docs/02-usage/000_intro.md | 11 +-- docs/02-usage/010_prerequisites.md | 2 +- docs/02-usage/020_running.md | 4 +- docs/02-usage/030_clients.md | 2 +- docs/02-usage/040_workflow.md | 47 ++++++++++- docs/02-usage/050_configuration.md | 2 + docs/02-usage/060_dashboard.md | 2 +- docs/02-usage/999_additional-usage.md | 30 +++++++ docs/02-usage/999_detailed-usage.md | 78 ------------------- src/solidlsp/language_servers/intelephense.py | 2 +- 15 files changed, 110 insertions(+), 147 deletions(-) create mode 100644 docs/02-usage/999_additional-usage.md delete mode 100644 docs/02-usage/999_detailed-usage.md diff --git a/docs/01-about/000_intro.md b/docs/01-about/000_intro.md index 388ef411..3b19f2b4 100644 --- a/docs/01-about/000_intro.md +++ b/docs/01-about/000_intro.md @@ -1,2 +1,3 @@ # About Serena +In this section, we provide an overview of Serena, its purpose, and its key features. \ No newline at end of file diff --git a/docs/01-about/010_llm-integration.md b/docs/01-about/010_llm-integration.md index 2b2ac314..874812b5 100644 --- a/docs/01-about/010_llm-integration.md +++ b/docs/01-about/010_llm-integration.md @@ -1,10 +1,8 @@ ## LLM Integration -Serena provides the necessary [tools](#list-of-tools) for coding workflows, but an LLM is required to do the actual work, +Serena provides the necessary [tools](035_tools) for coding workflows, but an LLM is required to do the actual work, orchestrating tool use. -For example, **supercharge the performance of Claude Code** with a [one-line shell command](#claude-code). - In general, Serena can be integrated with an LLM in several ways: * by using the **model context protocol (MCP)**. @@ -14,6 +12,6 @@ In general, Serena can be integrated with an LLM in several ways: * IDEs like VSCode, Cursor or IntelliJ, * Extensions like Cline or Roo Code * Local clients like [OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp), [Jan](https://jan.ai/docs/mcp-examples/browser/browserbase#enable-mcp), [Agno](https://docs.agno.com/introduction/playground) and others -* by using [mcpo to connect it to ChatGPT](docs/serena_on_chatgpt.md) or other clients that don't support MCP but do support tool calling via OpenAPI. +* by using [mcpo to connect it to ChatGPT](../03-special-guides/serena_on_chatgpt.md) or other clients that don't support MCP but do support tool calling via OpenAPI. * by incorporating Serena's tools into an agent framework of your choice, as illustrated [here](docs/custom_agent.md). Serena's tool implementation is decoupled from the framework-specific code and can thus easily be adapted to any agent framework. diff --git a/docs/01-about/020_programming-languages.md b/docs/01-about/020_programming-languages.md index f59e2a50..12137dc8 100644 --- a/docs/01-about/020_programming-languages.md +++ b/docs/01-about/020_programming-languages.md @@ -25,20 +25,20 @@ With Serena, we provide direct, out-of-the-box support for: (requires Elm compiler) * **Erlang** (requires installation of beam and [erlang_ls](https://github.com/erlang-ls/erlang_ls), experimental, might be slow or hang) -* **Fortran** +* **Fortran** (requires installation of fortls: `pip install fortls`) -* **Go** +* **Go** (requires installation of `gopls`) * **Haskell** (automatically locates HLS via ghcup, stack, or system PATH; supports Stack and Cabal projects) * **Java** (_Note_: Uses quirky symbol names for methods that include the full method signature; this causes a variety of problems!) -* **Javascript** +* **JavaScript** * **Julia** * **Kotlin** (uses the pre-alpha [official kotlin LS](https://github.com/Kotlin/kotlin-lsp), some issues may appear) * **Lua** -* **Markdown** +* **Markdown** (must be explicitly specified via `--language markdown` when generating project config, primarily useful for documentation-heavy projects) * **Nix** (requires nixd installation) @@ -47,9 +47,9 @@ With Serena, we provide direct, out-of-the-box support for: * **PHP** (uses Intelephense LSP; set `INTELEPHENSE_LICENSE_KEY` environment variable for premium features) * **Python** -* **R** +* **R** (requires installation of the `languageserver` R package) -* **Ruby** +* **Ruby** (by default, uses [ruby-lsp](https://github.com/Shopify/ruby-lsp), specify ruby_solargraph as your language to use the previous solargraph based implementation) * **Rust** (requires [rustup](https://rustup.rs/) - uses rust-analyzer from your toolchain) diff --git a/docs/01-about/040_comparison-to-other-agents.md b/docs/01-about/040_comparison-to-other-agents.md index b65085a0..f9baf158 100644 --- a/docs/01-about/040_comparison-to-other-agents.md +++ b/docs/01-about/040_comparison-to-other-agents.md @@ -1,9 +1,9 @@ ## Comparison with Other Coding Agents To our knowledge, Serena is the first fully-featured coding agent where the -entire functionality -is available through an MCP server, thus not requiring API keys or -subscriptions. +entire functionality is made available through an MCP server, +thus not requiring additional API keys or subscriptions if access to an LLM +is already available through an MCP-compatible client. ### Subscription-Based Coding Agents @@ -13,20 +13,16 @@ Serena's functionality is similar to Cursor's Agent, Windsurf's Cascade or VSCode's agent mode. Serena has the advantage of not requiring a subscription. -A potential disadvantage is that it -is not directly integrated into an IDE, so the inspection of newly written code -is not as seamless. More technical differences are: -* Serena is not bound to a specific IDE or CLI. - Serena's MCP server can be used with any MCP client (including some IDEs), - and the Agno-based agent provides additional ways of applying its functionality. -* Serena is not bound to a specific large language model or API. * Serena navigates and edits code using a language server, so it has a symbolic understanding of the code. - IDE-based tools often use a RAG-based or purely text-based approach, which is often + IDE-based tools often use a text search-based or purely text file-based approach, which is often less powerful, especially for large codebases. +* Serena is not bound to a specific interface (IDE or CLI). + Serena's MCP server can be used with any MCP client (including some IDEs). +* Serena is not bound to a specific large language model or API. * Serena is open-source and has a small codebase, so it can be easily extended and modified. @@ -38,17 +34,11 @@ to the API costs of the underlying LLM. Some of them (like Cline) can even be included in IDEs as an extension. They are often very powerful and their main downside are the (potentially very high) API costs. - -Serena itself can be used as an API-based agent (see the section on Agno above). -We have not yet written a CLI tool or a -dedicated IDE extension for Serena (and there is probably no need for the latter, as -Serena can already be used with any IDE that supports MCP servers). -If there is demand for a Serena as a CLI tool like Claude Code, we will -consider writing one. +Serena itself can be used as an API-based agent (see the [section on Agno](../03-special-guides/custom_agent.md)). The main difference between Serena and other API-based agents is that Serena can also be used as an MCP server, thus not requiring -an API key and bypassing the API costs. This is a unique feature of Serena. +an API key and bypassing the API costs. ### Other MCP-Based Coding Agents diff --git a/docs/01-about/050_acknowledgements.md b/docs/01-about/050_acknowledgements.md index e2e024da..6831e898 100644 --- a/docs/01-about/050_acknowledgements.md +++ b/docs/01-about/050_acknowledgements.md @@ -2,21 +2,17 @@ ### Sponsors -We are very grateful to our [sponsors](https://github.com/sponsors/oraios) who help us drive Serena's development. The core team -(the founders of [Oraios AI](https://oraios-ai.de/)) put in a lot of work in order to turn Serena into a useful open source project. +We are very grateful to our [sponsors](https://github.com/sponsors/oraios), who help us drive Serena's development. +The core team (the founders of [Oraios AI](https://oraios-ai.de/)) put in a lot of work in order to turn Serena into a useful open source project. So far, there is no business model behind this project, and sponsors are our only source of income from it. -Sponsors help us dedicating more time to the project, managing contributions, and working on larger features (like better tooling based on more advanced +Sponsors help us dedicate more time to the project, managing contributions, and working on larger features (like better tooling based on more advanced LSP features, VSCode integration, debugging via the DAP, and several others). If you find this project useful to your work, or would like to accelerate the development of Serena, consider becoming a sponsor. We are proud to announce that the Visual Studio Code team, together with Microsoft’s Open Source Programs Office and GitHub Open Source have decided to sponsor Serena with a one-time contribution! -

- Visual Studio Code sponsor logo -

- ### Community Contributions A significant part of Serena, especially support for various languages, was contributed by the open source community. @@ -24,6 +20,7 @@ We are very grateful for the many contributors who made this possible and who pl what it is today. ### Technologies + We built Serena on top of multiple existing open-source technologies, the most important ones being: 1. [multilspy](https://github.com/microsoft/multilspy). @@ -32,23 +29,6 @@ We built Serena on top of multiple existing open-source technologies, the most i Solid-LSP provides pure synchronous LSP calls and extends the original library with the symbolic logic that Serena required. 2. [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk) -3. [Agno](https://github.com/agno-agi/agno) and - the associated [agent-ui](https://github.com/agno-agi/agent-ui), - which we use to allow Serena to work with any model, beyond the ones - supporting the MCP. -4. All the language servers that we use through Solid-LSP. +3. All the language servers that we use through Solid-LSP. Without these projects, Serena would not have been possible (or would have been significantly more difficult to build). - -## Customizing and Extending Serena - -It is straightforward to extend Serena's AI functionality with your own ideas. -Simply implement a new tool by subclassing -`serena.agent.Tool` and implement the `apply` method with a signature -that matches the tool's requirements. -Once implemented, `SerenaAgent` will automatically have access to the new tool. - -It is also relatively straightforward to add [support for a new programming language](/.serena/memories/adding_new_language_support_guide.md). - -We look forward to seeing what the community will come up with! -For details on contributing, see [contributing guidelines](/CONTRIBUTING.md). \ No newline at end of file diff --git a/docs/02-usage/000_intro.md b/docs/02-usage/000_intro.md index 110763f1..a2f1fb05 100644 --- a/docs/02-usage/000_intro.md +++ b/docs/02-usage/000_intro.md @@ -1,11 +1,6 @@ # Usage -Serena can be used in various ways. -In this section, you will find general usage instructions as well as concrete instructions for selected integrations. +Serena can be used in various ways and supports coding workflows through a project-based approach. +Its configuration is flexible and allows tailoring it to your specific needs. -* For coding with Claude, we recommend using Serena through [Claude Code](#claude-code) or [Claude Desktop](#claude-desktop). You can also use Serena in most other [terminal-based clients](#other-terminal-based-clients). -* If you want a GUI experience outside an IDE, you can use one of the many [local GUIs](#local-guis-and-frameworks) that support MCP servers. - You can also connect Serena to many web clients (including ChatGPT) using [mcpo](docs/serena_on_chatgpt.md). -* If you want to use Serena integrated in your IDE, see the section on [other MCP clients](#other-mcp-clients---cline-roo-code-cursor-windsurf-etc). -* You can use Serena as a library for building your own applications. We try to keep the public API stable, but you should still - expect breaking changes and pin Serena to a fixed version if you use it as a dependency. +In this section, you will find general usage instructions as well as concrete instructions for selected integrations. diff --git a/docs/02-usage/010_prerequisites.md b/docs/02-usage/010_prerequisites.md index 0199fa5e..5a59feeb 100644 --- a/docs/02-usage/010_prerequisites.md +++ b/docs/02-usage/010_prerequisites.md @@ -1,6 +1,6 @@ ## Prerequisites -### uv +### Package Manager: uv Serena is managed by `uv`. If you do not have it yet, install it following the instructions [here](https://docs.astral.sh/uv/getting-started/installation/). diff --git a/docs/02-usage/020_running.md b/docs/02-usage/020_running.md index e50506ae..0e79c4f7 100644 --- a/docs/02-usage/020_running.md +++ b/docs/02-usage/020_running.md @@ -136,8 +136,8 @@ to get a list of all available options. Some useful options include: * `--project `: specify the project to work on by name or path. - * `--context `: specify the operation [context]() in which Serena shall operate - * `--mode `: specify one or more [modes]() to enable (can be passed several times) + * `--context `: specify the operation [context](contexts) in which Serena shall operate + * `--mode `: specify one or more [modes](modes) to enable (can be passed several times) * `--enable-web-dashboard `: enable or disable the web dashboard (enabled by default) ### Other Commands diff --git a/docs/02-usage/030_clients.md b/docs/02-usage/030_clients.md index 1bf0dd58..9f6dcc3e 100644 --- a/docs/02-usage/030_clients.md +++ b/docs/02-usage/030_clients.md @@ -132,7 +132,7 @@ There are many terminal-based coding assistants that support MCP servers, such a * [opencode](https://github.com/sst/opencode). They generally benefit from the symbolic tools provided by Serena. You might want to customize some aspects of Serena -by writing your own context, modes or prompts to adjust it to the client's respective internal capabilities (and your general worflow). +by writing your own context, modes or prompts to adjust it to the client's respective internal capabilities (and your general workflow). #### MCP-Enabled IDEs and Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) diff --git a/docs/02-usage/040_workflow.md b/docs/02-usage/040_workflow.md index b9958c4e..fe2c5490 100644 --- a/docs/02-usage/040_workflow.md +++ b/docs/02-usage/040_workflow.md @@ -83,4 +83,49 @@ Feel free to read and adjust them as needed; you can also add new ones manually. Every file in the `.serena/memories/` directory is a memory file. Whenever Serena starts working on a project, the list of memories is provided, and the agent can decide to read them. -We found that memories can significantly improve the user experience with Serena. \ No newline at end of file +We found that memories can significantly improve the user experience with Serena. + + +### Preparing Your Project + +When using Serena to work on your project, it can be helpful to follow a few best practices. + +#### Structure Your Codebase + +Serena uses the code structure for finding, reading and editing code. This means that it will +work well with well-structured code but may perform poorly on fully unstructured one (like a "God class" +with enormous, non-modular functions). + +Furthermore, for languages that are not statically typed, the use of type annotations (if supported) +are highly beneficial. + +#### Start from a Clean State + +It is best to start a code generation task from a clean git state. Not only will +this make it easier for you to inspect the changes, but also the model itself will +have a chance of seeing what it has changed by calling `git diff` and thereby +correct itself or continue working in a followup conversation if needed. + +##### Use Platform-Native Line Endings + +**Important**: since Serena will write to files using the system-native line endings +and it might want to look at the git diff, it is important to +set `git config core.autocrlf` to `true` on Windows. +With `git config core.autocrlf` set to `false` on Windows, you may end up with huge diffs +due to line endings only. +It is generally a good idea to globally enable this git setting on Windows: + +```shell +git config --global core.autocrlf true +``` + +##### Logging, Linting, and Automated Tests + +Serena can successfully complete tasks in an _agent loop_, where it iteratively +acquires information, performs actions, and reflects on the results. +However, Serena cannot use a debugger; it must rely on the results of program executions, +linting results, and test results to assess the correctness of its actions. +Therefore, software that is designed to meaningful interpretable outputs (e.g. log messages) +and that has a good test coverage is much easier to work with for Serena. + +We generally recommend to start an editing task from a state where all linting checks and tests pass. \ No newline at end of file diff --git a/docs/02-usage/050_configuration.md b/docs/02-usage/050_configuration.md index 31de3420..ae149b12 100644 --- a/docs/02-usage/050_configuration.md +++ b/docs/02-usage/050_configuration.md @@ -39,6 +39,7 @@ want to use Serena. Serena's behavior and toolset can be adjusted using contexts and modes. These allow for a high degree of customization to best suit your workflow and the environment Serena is operating in. +(contexts)= #### Contexts A **context** defines the general environment in which Serena is operating. @@ -67,6 +68,7 @@ You can manage contexts using the `context` command, where `` is [your way of running Serena](020_running). +(modes)= #### Modes Modes further refine Serena's behavior for specific types of tasks or interaction styles. Multiple modes can be active simultaneously, allowing you to combine their effects. Modes influence the system prompt and can also alter the set of available tools by excluding certain ones. diff --git a/docs/02-usage/060_dashboard.md b/docs/02-usage/060_dashboard.md index c8babaac..594a6fd4 100644 --- a/docs/02-usage/060_dashboard.md +++ b/docs/02-usage/060_dashboard.md @@ -18,5 +18,5 @@ Serena comes with built-in tools for monitoring and managing the current session This is mainly supported on Windows, but it may also work on Linux; macOS is unsupported. -Both can be enabled, configured or disabled in Serena's [configuration](050_configuration) file (`serena_config.yml`). +Both can be configured in Serena's [configuration](050_configuration) file (`serena_config.yml`). If enabled, they will automatically be opened as soon as the Serena agent/MCP server is started. diff --git a/docs/02-usage/999_additional-usage.md b/docs/02-usage/999_additional-usage.md new file mode 100644 index 00000000..5bb9aac4 --- /dev/null +++ b/docs/02-usage/999_additional-usage.md @@ -0,0 +1,30 @@ +## Additional Usage Pointers + +### Prompting Strategies + +We found that it is often a good idea to spend some time conceptualizing and planning a task +before actually implementing it, especially for non-trivial task. This helps both in achieving +better results and in increasing the feeling of control and staying in the loop. You can +make a detailed plan in one session, where Serena may read a lot of your code to build up the context, +and then continue with the implementation in another (potentially after creating suitable memories). + +### Running Out of Context + +For long and complicated tasks, or tasks where Serena has read a lot of content, you +may come close to the limits of context tokens. In that case, it is often a good idea to continue +in a new conversation. Serena has a dedicated tool to create a summary of the current state +of the progress and all relevant info for continuing it. You can request to create this summary and +write it to a memory. Then, in a new conversation, you can just ask Serena to read the memory and +continue with the task. In our experience, this worked really well. On the up-side, since in a +single session there is no summarization involved, Serena does not usually get lost (unlike some +other agents that summarize under the hood), and it is also instructed to occasionally check whether +it's on the right track. + +Serena instructs the LLM to be economical in general, so the problem of running out of context +should not occur too often, unless the task is very large or complicated. + +### Serena and Git Worktrees + +[git-worktree](https://git-scm.com/docs/git-worktree) can be an excellent way to parallelize your work. More on this in [Anthropic: Run parallel Claude Code sessions with Git worktrees](https://docs.claude.com/en/docs/claude-code/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees). + +When it comes to serena AND git-worktree AND larger projects (that take longer to index), the recommended way is to COPY your `$ORIG_PROJECT/.serena/cache` to `$GIT_WORKTREE/.serena/cache`. After you have performed pre-indexing of your project described in [Project Activation & Indexing](#project-activation--indexing) section. To avoid having to re-index per each git work tree that you create. diff --git a/docs/02-usage/999_detailed-usage.md b/docs/02-usage/999_detailed-usage.md deleted file mode 100644 index 9cdeaaee..00000000 --- a/docs/02-usage/999_detailed-usage.md +++ /dev/null @@ -1,78 +0,0 @@ -## Detailed Usage and Recommendations - -### Tool Execution - -Serena combines tools for semantic code retrieval with editing capabilities and shell execution. -Serena's behavior can be further customized through [Modes and Contexts](#modes-and-contexts). -Find the complete list of tools [below](#full-list-of-tools). - -The use of all tools is generally recommended, as this allows Serena to provide the most value: -Only by executing shell commands (in particular, tests) can Serena identify and correct mistakes -autonomously. - -### Prepare Your Project - -#### Structure Your Codebase - -Serena uses the code structure for finding, reading and editing code. This means that it will -work well with well-structured code but may perform poorly on fully unstructured one (like a "God class" -with enormous, non-modular functions). -Furthermore, for languages that are not statically typed, type annotations are highly beneficial. - -#### Start from a Clean State - -It is best to start a code generation task from a clean git state. Not only will -this make it easier for you to inspect the changes, but also the model itself will -have a chance of seeing what it has changed by calling `git diff` and thereby -correct itself or continue working in a followup conversation if needed. - -:warning: **Important**: since Serena will write to files using the system-native line endings -and it might want to look at the git diff, it is important to -set `git config core.autocrlf` to `true` on Windows. -With `git config core.autocrlf` set to `false` on Windows, you may end up with huge diffs -only due to line endings. It is generally a good idea to globally enable this git setting on Windows: - -```shell -git config --global core.autocrlf true -``` - -#### Logging, Linting, and Automated Tests - -Serena can successfully complete tasks in an _agent loop_, where it iteratively -acquires information, performs actions, and reflects on the results. -However, Serena cannot use a debugger; it must rely on the results of program executions, -linting results, and test results to assess the correctness of its actions. -Therefore, software that is designed to meaningful interpretable outputs (e.g. log messages) -and that has a good test coverage is much easier to work with for Serena. - -We generally recommend to start an editing task from a state where all linting checks and tests pass. - -### Prompting Strategies - -We found that it is often a good idea to spend some time conceptualizing and planning a task -before actually implementing it, especially for non-trivial task. This helps both in achieving -better results and in increasing the feeling of control and staying in the loop. You can -make a detailed plan in one session, where Serena may read a lot of your code to build up the context, -and then continue with the implementation in another (potentially after creating suitable memories). - -### Running Out of Context - -For long and complicated tasks, or tasks where Serena has read a lot of content, you -may come close to the limits of context tokens. In that case, it is often a good idea to continue -in a new conversation. Serena has a dedicated tool to create a summary of the current state -of the progress and all relevant info for continuing it. You can request to create this summary and -write it to a memory. Then, in a new conversation, you can just ask Serena to read the memory and -continue with the task. In our experience, this worked really well. On the up-side, since in a -single session there is no summarization involved, Serena does not usually get lost (unlike some -other agents that summarize under the hood), and it is also instructed to occasionally check whether -it's on the right track. - -Moreover, Serena is instructed to be frugal with context -(e.g., to not read bodies of code symbols unnecessarily), -but we found that Claude is not always very good in being frugal (Gemini seemed better at it). -You can explicitly instruct it to not read the bodies if you know that it's not needed. - -### Serena and GIT worktrees -[git-worktree](https://git-scm.com/docs/git-worktree) can be an excellent way to parallelize your work. More on this in [Anthropic: Run parallel Claude Code sessions with Git worktrees](https://docs.claude.com/en/docs/claude-code/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees). - -When it comes to serena AND git-worktree AND larger projects (that take longer to index), the recommended way is to COPY your `$ORIG_PROJECT/.serena/cache` to `$GIT_WORKTREE/.serena/cache`. After you have performed pre-indexing of your project described in [Project Activation & Indexing](#project-activation--indexing) section. To avoid having to re-index per each git work tree that you create. diff --git a/src/solidlsp/language_servers/intelephense.py b/src/solidlsp/language_servers/intelephense.py index 3f4f6e0b..dfac4eb5 100644 --- a/src/solidlsp/language_servers/intelephense.py +++ b/src/solidlsp/language_servers/intelephense.py @@ -33,7 +33,7 @@ class Intelephense(SolidLanguageServer): @override def is_ignored_dirname(self, dirname: str) -> bool: # For PHP projects, we should ignore: - # - vendor: third-party dependencies managed by Composer + # - vendor: third-party dependencies Date: Sat, 8 Nov 2025 12:33:29 +0100 Subject: [PATCH 15/21] Fix links in docs --- docs/01-about/010_llm-integration.md | 2 +- docs/01-about/020_programming-languages.md | 2 +- docs/02-usage/020_running.md | 5 +++-- docs/02-usage/040_workflow.md | 1 + docs/02-usage/050_configuration.md | 2 +- docs/02-usage/070_security.md | 2 +- docs/02-usage/999_additional-usage.md | 4 +++- 7 files changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/01-about/010_llm-integration.md b/docs/01-about/010_llm-integration.md index 874812b5..2fd10100 100644 --- a/docs/01-about/010_llm-integration.md +++ b/docs/01-about/010_llm-integration.md @@ -13,5 +13,5 @@ In general, Serena can be integrated with an LLM in several ways: * Extensions like Cline or Roo Code * Local clients like [OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp), [Jan](https://jan.ai/docs/mcp-examples/browser/browserbase#enable-mcp), [Agno](https://docs.agno.com/introduction/playground) and others * by using [mcpo to connect it to ChatGPT](../03-special-guides/serena_on_chatgpt.md) or other clients that don't support MCP but do support tool calling via OpenAPI. -* by incorporating Serena's tools into an agent framework of your choice, as illustrated [here](docs/custom_agent.md). +* by incorporating Serena's tools into an agent framework of your choice, as illustrated [here](../03-special-guides/custom_agent). Serena's tool implementation is decoupled from the framework-specific code and can thus easily be adapted to any agent framework. diff --git a/docs/01-about/020_programming-languages.md b/docs/01-about/020_programming-languages.md index 12137dc8..0e9eeb6c 100644 --- a/docs/01-about/020_programming-languages.md +++ b/docs/01-about/020_programming-languages.md @@ -61,4 +61,4 @@ With Serena, we provide direct, out-of-the-box support for: (requires installation of ZLS - Zig Language Server) Support for further languages can easily be added by providing a shallow adapter for a new language server implementation, -see Serena's [memory on that](.serena/memories/adding_new_language_support_guide.md). +see Serena's [memory on that](https://github.com/oraios/serena/blob/main/.serena/memories/adding_new_language_support_guide.md). diff --git a/docs/02-usage/020_running.md b/docs/02-usage/020_running.md index 0e79c4f7..73a04f72 100644 --- a/docs/02-usage/020_running.md +++ b/docs/02-usage/020_running.md @@ -41,9 +41,10 @@ Explore the CLI to see some of the customization options that serena provides (m uv run --directory /abs/path/to/serena serena ``` +(docker)= #### Using Docker (Experimental) -⚠️ Docker support is currently experimental with several limitations. Please read the [Docker documentation](DOCKER.md) for important caveats before using it. +⚠️ Docker support is currently experimental with several limitations. Please read the [Docker documentation](https://github.com/oraios/serena/blob/main/DOCKER.md) for important caveats before using it. You can run the Serena MCP server directly via docker as follows, assuming that the projects you want to work on are all located in `/path/to/your/projects`: @@ -60,7 +61,7 @@ Replace `/path/to/your/projects` with the absolute path to your projects directo Alternatively, use docker compose with the `compose.yml` file provided in the repository. -See the [Docker documentation](DOCKER.md) for detailed setup instructions, configuration options, and known limitations. +See the [Docker documentation](https://github.com/oraios/serena/blob/main/DOCKER.md) for detailed setup instructions, configuration options, and known limitations. #### Using Nix diff --git a/docs/02-usage/040_workflow.md b/docs/02-usage/040_workflow.md index fe2c5490..97b2064d 100644 --- a/docs/02-usage/040_workflow.md +++ b/docs/02-usage/040_workflow.md @@ -36,6 +36,7 @@ For instance, when using `uvx`, run After creation, you can adjust the project settings in the generated `.serena/project.yml` file. +(indexing)= #### Indexing Especially for larger project, it is advisable to index the project after creation (in order to avoid diff --git a/docs/02-usage/050_configuration.md b/docs/02-usage/050_configuration.md index ae149b12..edec95cf 100644 --- a/docs/02-usage/050_configuration.md +++ b/docs/02-usage/050_configuration.md @@ -17,7 +17,7 @@ Serena is configured in four places: (or use the `--directory` command version). 2. In the arguments passed to the `start-mcp-server` in your client's config (see below), - which will apply to all sessions started by the respective client. In particular, the [context](#contexts) parameter + which will apply to all sessions started by the respective client. In particular, the [context](contexts) parameter should be set appropriately for Serena to be best adjusted to existing tools and capabilities of your client. See for a detailed explanation. You can override all entries from the `serena_config.yml` through command line arguments. 3. In the `.serena/project.yml` file within your project. This will hold project-level configuration that is used whenever diff --git a/docs/02-usage/070_security.md b/docs/02-usage/070_security.md index de1a83f2..2b5478cd 100644 --- a/docs/02-usage/070_security.md +++ b/docs/02-usage/070_security.md @@ -9,4 +9,4 @@ Therefore, to reduce the risk of unintended consequences when using Serena, it i * monitor tool executions carefully (e.g. via your MCP client, provided that it supports it), * consider enabling read-only mode for your project (set `read_only: True` in project.yml) if you only want to analyze code without modifying it, * restrict the set of allowed tools via the [configuration](050_configuration), - * use a sandboxed environment for running Serena (e.g. by [using Docker](020_running.md#using-docker-experimental)). + * use a sandboxed environment for running Serena (e.g. by [using Docker](docker)). diff --git a/docs/02-usage/999_additional-usage.md b/docs/02-usage/999_additional-usage.md index 5bb9aac4..bb37f0ef 100644 --- a/docs/02-usage/999_additional-usage.md +++ b/docs/02-usage/999_additional-usage.md @@ -27,4 +27,6 @@ should not occur too often, unless the task is very large or complicated. [git-worktree](https://git-scm.com/docs/git-worktree) can be an excellent way to parallelize your work. More on this in [Anthropic: Run parallel Claude Code sessions with Git worktrees](https://docs.claude.com/en/docs/claude-code/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees). -When it comes to serena AND git-worktree AND larger projects (that take longer to index), the recommended way is to COPY your `$ORIG_PROJECT/.serena/cache` to `$GIT_WORKTREE/.serena/cache`. After you have performed pre-indexing of your project described in [Project Activation & Indexing](#project-activation--indexing) section. To avoid having to re-index per each git work tree that you create. +When it comes to serena AND git-worktree AND larger projects (that take longer to index), +the recommended way is to COPY your `$ORIG_PROJECT/.serena/cache` to `$GIT_WORKTREE/.serena/cache`. +Perform [pre-indexing of your project](indexing) to avoid having to re-index per each worktree you create. From 90e123726c790b3820f26bf398d1b24d1ca63c65 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Sat, 8 Nov 2025 12:36:43 +0100 Subject: [PATCH 16/21] Fix heading levels in docs --- docs/01-about/010_llm-integration.md | 2 +- docs/01-about/020_programming-languages.md | 2 +- docs/01-about/030_serena-in-action.md | 6 ++--- docs/01-about/035_tools.md | 2 +- .../040_comparison-to-other-agents.md | 8 +++---- docs/01-about/050_acknowledgements.md | 8 +++---- docs/02-usage/010_prerequisites.md | 6 ++--- docs/02-usage/020_running.md | 22 +++++++++---------- docs/02-usage/030_clients.md | 16 +++++++------- docs/02-usage/040_workflow.md | 22 +++++++++---------- docs/02-usage/050_configuration.md | 8 +++---- docs/02-usage/060_dashboard.md | 2 +- docs/02-usage/070_security.md | 2 +- docs/02-usage/999_additional-usage.md | 8 +++---- 14 files changed, 57 insertions(+), 57 deletions(-) diff --git a/docs/01-about/010_llm-integration.md b/docs/01-about/010_llm-integration.md index 2fd10100..0f9c75aa 100644 --- a/docs/01-about/010_llm-integration.md +++ b/docs/01-about/010_llm-integration.md @@ -1,4 +1,4 @@ -## LLM Integration +# LLM Integration Serena provides the necessary [tools](035_tools) for coding workflows, but an LLM is required to do the actual work, orchestrating tool use. diff --git a/docs/01-about/020_programming-languages.md b/docs/01-about/020_programming-languages.md index 0e9eeb6c..601c3def 100644 --- a/docs/01-about/020_programming-languages.md +++ b/docs/01-about/020_programming-languages.md @@ -1,4 +1,4 @@ -## Language Support +# Language Support Serena's semantic code analysis capabilities build on **language servers** using the widely implemented language server protocol (LSP). The LSP provides a set of versatile code querying diff --git a/docs/01-about/030_serena-in-action.md b/docs/01-about/030_serena-in-action.md index 31b26fba..d180c61d 100644 --- a/docs/01-about/030_serena-in-action.md +++ b/docs/01-about/030_serena-in-action.md @@ -1,12 +1,12 @@ -## Serena in Action +# Serena in Action -### Demonstration 1: Efficient Operation in Claude Code +## Demonstration 1: Efficient Operation in Claude Code A demonstration of Serena efficiently retrieving and editing code within Claude Code, thereby saving tokens and time. Efficient operations are not only useful for saving costs, but also for generally improving the generated code's quality. This effect may be less pronounced in very small projects, but often becomes of crucial importance in larger ones. https://github.com/user-attachments/assets/ab78ebe0-f77d-43cc-879a-cc399efefd87 -### Demonstration 2: Serena in Claude Desktop +## Demonstration 2: Serena in Claude Desktop A demonstration of Serena implementing a small feature for itself (a better log GUI) with Claude Desktop. Note how Serena's tools enable Claude to find and edit the right symbols. diff --git a/docs/01-about/035_tools.md b/docs/01-about/035_tools.md index 67078ded..17b84b53 100644 --- a/docs/01-about/035_tools.md +++ b/docs/01-about/035_tools.md @@ -1,4 +1,4 @@ -## List of Tools +# List of Tools Find the full list of Serena's tools below (output of ` tools list --all`). diff --git a/docs/01-about/040_comparison-to-other-agents.md b/docs/01-about/040_comparison-to-other-agents.md index f9baf158..df89149e 100644 --- a/docs/01-about/040_comparison-to-other-agents.md +++ b/docs/01-about/040_comparison-to-other-agents.md @@ -1,11 +1,11 @@ -## Comparison with Other Coding Agents +# Comparison with Other Coding Agents To our knowledge, Serena is the first fully-featured coding agent where the entire functionality is made available through an MCP server, thus not requiring additional API keys or subscriptions if access to an LLM is already available through an MCP-compatible client. -### Subscription-Based Coding Agents +## Subscription-Based Coding Agents Many prominent subscription-based coding agents are parts of IDEs like Windsurf, Cursor and VSCode. @@ -26,7 +26,7 @@ More technical differences are: * Serena is open-source and has a small codebase, so it can be easily extended and modified. -### API-Based Coding Agents +## API-Based Coding Agents An alternative to subscription-based agents are API-based agents like Claude Code, Cline, Aider, Roo Code and others, where the usage costs map directly @@ -40,7 +40,7 @@ The main difference between Serena and other API-based agents is that Serena can also be used as an MCP server, thus not requiring an API key and bypassing the API costs. -### Other MCP-Based Coding Agents +## Other MCP-Based Coding Agents There are other MCP servers designed for coding, like [DesktopCommander](https://github.com/wonderwhy-er/DesktopCommanderMCP) and [codemcp](https://github.com/ezyang/codemcp). diff --git a/docs/01-about/050_acknowledgements.md b/docs/01-about/050_acknowledgements.md index 6831e898..334a4e6e 100644 --- a/docs/01-about/050_acknowledgements.md +++ b/docs/01-about/050_acknowledgements.md @@ -1,6 +1,6 @@ -## Acknowledgements +# Acknowledgements -### Sponsors +## Sponsors We are very grateful to our [sponsors](https://github.com/sponsors/oraios), who help us drive Serena's development. The core team (the founders of [Oraios AI](https://oraios-ai.de/)) put in a lot of work in order to turn Serena into a useful open source project. @@ -13,13 +13,13 @@ If you find this project useful to your work, or would like to accelerate the de We are proud to announce that the Visual Studio Code team, together with Microsoft’s Open Source Programs Office and GitHub Open Source have decided to sponsor Serena with a one-time contribution! -### Community Contributions +## Community Contributions A significant part of Serena, especially support for various languages, was contributed by the open source community. We are very grateful for the many contributors who made this possible and who played an important role in making Serena what it is today. -### Technologies +## Technologies We built Serena on top of multiple existing open-source technologies, the most important ones being: diff --git a/docs/02-usage/010_prerequisites.md b/docs/02-usage/010_prerequisites.md index 5a59feeb..b408664e 100644 --- a/docs/02-usage/010_prerequisites.md +++ b/docs/02-usage/010_prerequisites.md @@ -1,11 +1,11 @@ -## Prerequisites +# Prerequisites -### Package Manager: uv +## Package Manager: uv Serena is managed by `uv`. If you do not have it yet, install it following the instructions [here](https://docs.astral.sh/uv/getting-started/installation/). -### Language-Specific Requirements +## Language-Specific Requirements Depending on the programming language you intend to use with Serena, you may need to install additional tools or SDKs if you intend to use the language server backend of Serena. diff --git a/docs/02-usage/020_running.md b/docs/02-usage/020_running.md index 73a04f72..5b778c01 100644 --- a/docs/02-usage/020_running.md +++ b/docs/02-usage/020_running.md @@ -1,4 +1,4 @@ -## Running Serena +# Running Serena Serena is a command-line tool with a variety of sub-commands. This section describes @@ -6,12 +6,12 @@ This section describes * how to run and configure the most important command, i.e. starting the MCP server * other useful commands. -### Ways of Running Serena +## Ways of Running Serena In the following, we will refer to the command used to run Serena as ``, which you should replace with the appropriate command based on your chosen method. -#### Using uvx +### Using uvx `uvx` is part of `uv`. It can be used to run the latest version of Serena directly from the repository, without an explicit local installation. @@ -19,7 +19,7 @@ which you should replace with the appropriate command based on your chosen metho Explore the CLI to see some of the customization options that serena provides (more info on them below). -#### Local Installation +### Local Installation 1. Clone the repository and change into it. @@ -42,7 +42,7 @@ Explore the CLI to see some of the customization options that serena provides (m ``` (docker)= -#### Using Docker (Experimental) +### Using Docker (Experimental) ⚠️ Docker support is currently experimental with several limitations. Please read the [Docker documentation](https://github.com/oraios/serena/blob/main/DOCKER.md) for important caveats before using it. @@ -63,7 +63,7 @@ Alternatively, use docker compose with the `compose.yml` file provided in the re See the [Docker documentation](https://github.com/oraios/serena/blob/main/DOCKER.md) for detailed setup instructions, configuration options, and known limitations. -#### Using Nix +### Using Nix If you are using Nix and [have enabled the `nix-command` and `flakes` features](https://nixos.wiki/wiki/flakes), you can run Serena using the following command: @@ -73,7 +73,7 @@ nix run github:oraios/serena -- [options] You can also install Serena by referencing this repo (`github:oraios/serena`) and using it in your Nix flake. The package is exported as `serena`. -### Running the MCP Server +## Running the MCP Server Given your preferred method of running Serena, you can start the MCP server using the `start-mcp-server` command: @@ -82,7 +82,7 @@ Given your preferred method of running Serena, you can start the MCP server usin Note that no matter how you run the MCP server, Serena will, by default, start a web-based dashboard on localhost that will allow you to inspect the server's operations, logs, and configuration. -#### Standard I/O Mode +### Standard I/O Mode The typical usage involves the client (e.g. Claude Code, Codex or Cursor) running the MCP server as a subprocess and using the process' stdin/stdout streams to communicate with it. @@ -105,7 +105,7 @@ necessarily has to be started by the client in order for communication to take p In other words, you do not need to start the server yourself. The client application (e.g. Claude Desktop) takes care of this and therefore needs to be configured with a launch command. -#### Streamable HTTP Mode +### Streamable HTTP Mode When using instead the *Streamable HTTP* mode, you control the server lifecycle yourself, i.e. you start the server and provide the client with the URL to connect to it. @@ -125,7 +125,7 @@ and then configure your client to connect to `http://localhost:9121/mcp`. ℹ️ Note that while SSE transport is also supported, its use is discouraged. (mcp-args)= -#### MCP Server Command-Line Arguments +### MCP Server Command-Line Arguments The Serena MCP server supports a wide range of additional command-line options. Use the command @@ -141,7 +141,7 @@ Some useful options include: * `--mode `: specify one or more [modes](modes) to enable (can be passed several times) * `--enable-web-dashboard `: enable or disable the web dashboard (enabled by default) -### Other Commands +## Other Commands Serena provides several other commands in addition to `start-mcp-server`, most of which are related to project setup and configuration. diff --git a/docs/02-usage/030_clients.md b/docs/02-usage/030_clients.md index 9f6dcc3e..6e0eb563 100644 --- a/docs/02-usage/030_clients.md +++ b/docs/02-usage/030_clients.md @@ -1,4 +1,4 @@ -## Configuring Your MCP Client +# Configuring Your MCP Client In the following, we provide default configurations for popular MCP-enabled clients. @@ -6,7 +6,7 @@ Depending on your needs, you might want to customize Serena's behaviour by * [adding command-line arguments](mcp-args) * [adjusting configuration](050_configuration). -### Claude Code +## Claude Code Serena is a great way to make Claude Code both cheaper and more powerful! @@ -32,7 +32,7 @@ Note: Be sure to use at least `v1.0.52` of Claude Code (as earlier versions do not read MCP server system prompts upon startup). -### Codex +## Codex Serena works with OpenAI's Codex CLI out of the box, but you have to use the `codex` context for it to work properly. (The technical reason is that Codex doesn't fully support the MCP specifications, so some massaging of tools is required.). @@ -59,7 +59,7 @@ that was already taken). > Codex will often show the tools as `failed` even though they are successfully executed. This is not a problem, seems to be a bug in Codex. Despite the error message, everything works as expected. -### Claude Desktop +## Claude Desktop On Windows and macOS there are official [Claude Desktop applications by Anthropic](https://claude.ai/download), for Linux there is an [open-source community version](https://github.com/aaddrick/claude-desktop-debian). @@ -119,9 +119,9 @@ After restarting, you should see Serena's tools in your chat interface (notice t For more information on MCP servers with Claude Desktop, see [the official quick start guide](https://modelcontextprotocol.io/quickstart/user). -### Other Clients +## Other Clients -#### Terminal-Based Clients +### Terminal-Based Clients There are many terminal-based coding assistants that support MCP servers, such as @@ -134,7 +134,7 @@ There are many terminal-based coding assistants that support MCP servers, such a They generally benefit from the symbolic tools provided by Serena. You might want to customize some aspects of Serena by writing your own context, modes or prompts to adjust it to the client's respective internal capabilities (and your general workflow). -#### MCP-Enabled IDEs and Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) +### MCP-Enabled IDEs and Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) Being an MCP Server, Serena can be included in any MCP Client. Most of the popular existing coding assistants (e.g. IDE extensions) and AI-enabled IDEs themselves support connections @@ -143,7 +143,7 @@ to MCP Servers. Serena generally boosts performance by providing efficient tools We generally **recommend to use the `ide-assistant` context** for these integrations by adding the arguments `--context ide-assistant` in order to reduce tool duplication. -#### Local GUIs and Agent Frameworks +### Local GUIs and Agent Frameworks Over the last months, several technologies have emerged that allow you to run a local GUI client and connect it to an MCP server. The respective applications will typically work with Serena out of the box. diff --git a/docs/02-usage/040_workflow.md b/docs/02-usage/040_workflow.md index 97b2064d..aca2143a 100644 --- a/docs/02-usage/040_workflow.md +++ b/docs/02-usage/040_workflow.md @@ -1,4 +1,4 @@ -## The Project Workflow +# The Project Workflow Serena uses a project-based workflow. A **project** is simply a directory on your filesystem that contains code and other files @@ -12,13 +12,13 @@ setting up a project with Serena typically involves the following steps: 3. **Onboarding**: Getting Serena familiar with the project (creating memories) 4. **Working on coding tasks**: Using Serena to help you with actual coding tasks in the project -### Project Creation & Indexing +## Project Creation & Indexing You can create a project either * implicitly, by just activating a directory as a project while already in a conversation; this will use default settings for your project (skip to the next section). * explicitly, using the project creation command, or -#### Explicit Project Creation +### Explicit Project Creation To explicitly create a project, use the following command while in the project directory: @@ -37,7 +37,7 @@ For instance, when using `uvx`, run After creation, you can adjust the project settings in the generated `.serena/project.yml` file. (indexing)= -#### Indexing +### Indexing Especially for larger project, it is advisable to index the project after creation (in order to avoid delays during MCP server startup or the first tool application): @@ -48,7 +48,7 @@ While in the project directory, run this command: Indexing has to be called only once. During regular usage, Serena will automatically update the index whenever files change. -### Project Activation +## Project Activation Project activation makes Serena aware of the project you want to work with. You can either choose to do this @@ -63,7 +63,7 @@ You can either choose to do this (e.g. when working on a fixed project in `ide-assistant` mode): `--project ` -### Onboarding & Memories +## Onboarding & Memories By default, Serena will perform an **onboarding process** when it is started for the first time for a project. @@ -87,11 +87,11 @@ provided, and the agent can decide to read them. We found that memories can significantly improve the user experience with Serena. -### Preparing Your Project +## Preparing Your Project When using Serena to work on your project, it can be helpful to follow a few best practices. -#### Structure Your Codebase +### Structure Your Codebase Serena uses the code structure for finding, reading and editing code. This means that it will work well with well-structured code but may perform poorly on fully unstructured one (like a "God class" @@ -100,14 +100,14 @@ with enormous, non-modular functions). Furthermore, for languages that are not statically typed, the use of type annotations (if supported) are highly beneficial. -#### Start from a Clean State +### Start from a Clean State It is best to start a code generation task from a clean git state. Not only will this make it easier for you to inspect the changes, but also the model itself will have a chance of seeing what it has changed by calling `git diff` and thereby correct itself or continue working in a followup conversation if needed. -##### Use Platform-Native Line Endings +### Use Platform-Native Line Endings **Important**: since Serena will write to files using the system-native line endings and it might want to look at the git diff, it is important to @@ -120,7 +120,7 @@ It is generally a good idea to globally enable this git setting on Windows: git config --global core.autocrlf true ``` -##### Logging, Linting, and Automated Tests +### Logging, Linting, and Automated Tests Serena can successfully complete tasks in an _agent loop_, where it iteratively acquires information, performs actions, and reflects on the results. diff --git a/docs/02-usage/050_configuration.md b/docs/02-usage/050_configuration.md index edec95cf..bf1a85f7 100644 --- a/docs/02-usage/050_configuration.md +++ b/docs/02-usage/050_configuration.md @@ -1,4 +1,4 @@ -## Configuration +# Configuration Serena is very flexible in terms of configuration. While for most users, the default configurations will work, you can fully adjust it to your needs by editing a few yaml files. You can disable tools, change Serena's instructions @@ -34,13 +34,13 @@ Serena is configured in four places: After the initial setup, continue with one of the sections below, depending on how you want to use Serena. -### Modes and Contexts +## Modes and Contexts Serena's behavior and toolset can be adjusted using contexts and modes. These allow for a high degree of customization to best suit your workflow and the environment Serena is operating in. (contexts)= -#### Contexts +### Contexts A **context** defines the general environment in which Serena is operating. It influences the initial system prompt and the set of available tools. @@ -69,7 +69,7 @@ You can manage contexts using the `context` command, where `` is [your way of running Serena](020_running). (modes)= -#### Modes +### Modes Modes further refine Serena's behavior for specific types of tasks or interaction styles. Multiple modes can be active simultaneously, allowing you to combine their effects. Modes influence the system prompt and can also alter the set of available tools by excluding certain ones. diff --git a/docs/02-usage/060_dashboard.md b/docs/02-usage/060_dashboard.md index 594a6fd4..73376926 100644 --- a/docs/02-usage/060_dashboard.md +++ b/docs/02-usage/060_dashboard.md @@ -1,4 +1,4 @@ -## The Dashboard and GUI Tool +# The Dashboard and GUI Tool Serena comes with built-in tools for monitoring and managing the current session: diff --git a/docs/02-usage/070_security.md b/docs/02-usage/070_security.md index 2b5478cd..12faabdf 100644 --- a/docs/02-usage/070_security.md +++ b/docs/02-usage/070_security.md @@ -1,4 +1,4 @@ -## Security Considerations +# Security Considerations As fundamental abilities for a coding agent, Serena contains tools for executing shell commands and modifying files. Therefore, if the respective tool calls are not monitored or restricted (and execution takes place in a sensitive environment), diff --git a/docs/02-usage/999_additional-usage.md b/docs/02-usage/999_additional-usage.md index bb37f0ef..275fd190 100644 --- a/docs/02-usage/999_additional-usage.md +++ b/docs/02-usage/999_additional-usage.md @@ -1,6 +1,6 @@ -## Additional Usage Pointers +# Additional Usage Pointers -### Prompting Strategies +## Prompting Strategies We found that it is often a good idea to spend some time conceptualizing and planning a task before actually implementing it, especially for non-trivial task. This helps both in achieving @@ -8,7 +8,7 @@ better results and in increasing the feeling of control and staying in the loop. make a detailed plan in one session, where Serena may read a lot of your code to build up the context, and then continue with the implementation in another (potentially after creating suitable memories). -### Running Out of Context +## Running Out of Context For long and complicated tasks, or tasks where Serena has read a lot of content, you may come close to the limits of context tokens. In that case, it is often a good idea to continue @@ -23,7 +23,7 @@ it's on the right track. Serena instructs the LLM to be economical in general, so the problem of running out of context should not occur too often, unless the task is very large or complicated. -### Serena and Git Worktrees +## Serena and Git Worktrees [git-worktree](https://git-scm.com/docs/git-worktree) can be an excellent way to parallelize your work. More on this in [Anthropic: Run parallel Claude Code sessions with Git worktrees](https://docs.claude.com/en/docs/claude-code/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees). From 2b9a45055935363b867886ca3aa13396529d8ffd Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Sat, 8 Nov 2025 12:39:28 +0100 Subject: [PATCH 17/21] Disable continuation on error --- .github/workflows/docs.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index e74752d5..dacfd077 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -46,8 +46,7 @@ jobs: - name: Build docs run: uv run poe doc-build - # TODO: change once errors are resolved - continue-on-error: true + continue-on-error: false - name: Upload Pages artifact uses: actions/upload-pages-artifact@v3 From db01516894390fe2679e5db3f332e65fb434ca3c Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Sat, 8 Nov 2025 13:05:54 +0100 Subject: [PATCH 18/21] Improve callouts --- docs/02-usage/020_running.md | 26 +++++++++++++++----------- docs/02-usage/030_clients.md | 4 +++- 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/docs/02-usage/020_running.md b/docs/02-usage/020_running.md index 5b778c01..3f57d77a 100644 --- a/docs/02-usage/020_running.md +++ b/docs/02-usage/020_running.md @@ -44,7 +44,9 @@ Explore the CLI to see some of the customization options that serena provides (m (docker)= ### Using Docker (Experimental) -⚠️ Docker support is currently experimental with several limitations. Please read the [Docker documentation](https://github.com/oraios/serena/blob/main/DOCKER.md) for important caveats before using it. +:::{warning} +Docker support is currently experimental with several limitations. +::: You can run the Serena MCP server directly via docker as follows, assuming that the projects you want to work on are all located in `/path/to/your/projects`: @@ -61,7 +63,7 @@ Replace `/path/to/your/projects` with the absolute path to your projects directo Alternatively, use docker compose with the `compose.yml` file provided in the repository. -See the [Docker documentation](https://github.com/oraios/serena/blob/main/DOCKER.md) for detailed setup instructions, configuration options, and known limitations. +See our [Docker Setup](https://github.com/oraios/serena/blob/main/DOCKER.md) documentation for more detailed setup instructions, configuration options, and known limitations. ### Using Nix @@ -88,6 +90,13 @@ The typical usage involves the client (e.g. Claude Code, Codex or Cursor) runnin the MCP server as a subprocess and using the process' stdin/stdout streams to communicate with it. In order to launch the server, the client thus needs to be provided with the command to run the MCP server. +:::{note} +MCP servers which use stdio as a protocol are somewhat unusual as far as client/server architectures go, as the server +necessarily has to be started by the client in order for communication to take place via the server's standard input/output streams. +In other words, you do not need to start the server yourself. The client application (e.g. Claude Desktop) takes care of this and +therefore needs to be configured with a launch command. +::: + Communication over stdio is the default for the Serena MCP server, so in the simplest case, you can simply run the `start-mcp-server` command without any additional options. @@ -96,14 +105,9 @@ case, you can simply run the `start-mcp-server` command without any additional o For example, to run the server in stdio mode via `uvx`, you would run: uvx --from git+https://github.com/oraios/serena serena start-mcp-server - -ℹ️ See the section ["Configuring Your MCP Client"](030_clients) for information on how to configure your MCP client (e.g. Claude Code, Codex, Cursor, etc.) -to connect to the Serena MCP server. - -ℹ️ Note that MCP servers which use stdio as a protocol are somewhat unusual as far as client/server architectures go, as the server -necessarily has to be started by the client in order for communication to take place via the server's standard input/output stream. -In other words, you do not need to start the server yourself. The client application (e.g. Claude Desktop) takes care of this and -therefore needs to be configured with a launch command. + +See the section ["Configuring Your MCP Client"](030_clients) for specific information on how to configure your MCP client (e.g. Claude Code, Codex, Cursor, etc.) +to use such a launch command. ### Streamable HTTP Mode @@ -122,7 +126,7 @@ you would run and then configure your client to connect to `http://localhost:9121/mcp`. -ℹ️ Note that while SSE transport is also supported, its use is discouraged. +Note that while the legacy SSE transport is also supported (via `--transport sse` with corresponding /sse endpoint), its use is discouraged. (mcp-args)= ### MCP Server Command-Line Arguments diff --git a/docs/02-usage/030_clients.md b/docs/02-usage/030_clients.md index 6e0eb563..b0ea27b4 100644 --- a/docs/02-usage/030_clients.md +++ b/docs/02-usage/030_clients.md @@ -113,7 +113,9 @@ If you are using paths containing backslashes for paths on Windows That's it! Save the config and then restart Claude Desktop. You are ready for activating your first project. -⚠️ Be sure to fully quit the Claude Desktop application, as closing Claude will just minimize it to the system tray – at least on Windows. +:::{attention} +Be sure to fully quit the Claude Desktop application via File / Exit, as regularly closing the application will just minimize it. +::: After restarting, you should see Serena's tools in your chat interface (notice the small hammer icon). From 55a041dffcb901d790933b440331cf4b9c8b0207 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Sat, 8 Nov 2025 13:12:35 +0100 Subject: [PATCH 19/21] Clean up docs task --- .github/workflows/docs.yaml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index dacfd077..527c4bfa 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -4,7 +4,6 @@ on: push: # TODO change branch to main once docs is merged branches: [ docs ] - # Manual trigger, as you have — you can also add "push" later if desired workflow_dispatch: permissions: @@ -19,11 +18,11 @@ concurrency: jobs: build: runs-on: ubuntu-latest - timeout-minutes: 10 # give yourself more headroom for builds + timeout-minutes: 10 steps: - name: Checkout - uses: actions/checkout@v4 # use latest v4 instead of v3 + uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 @@ -51,7 +50,7 @@ jobs: - name: Upload Pages artifact uses: actions/upload-pages-artifact@v3 with: - path: docs/_build # ✅ confirm this is your static HTML output directory + path: docs/_build deploy: environment: From ff5ac556dc40309dd4610bd2faa09f9f80c48a71 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Sat, 8 Nov 2025 14:14:20 +0100 Subject: [PATCH 20/21] Add CLI command examples --- docs/02-usage/020_running.md | 62 +++++++++++++++++++++++++++++++++++- 1 file changed, 61 insertions(+), 1 deletion(-) diff --git a/docs/02-usage/020_running.md b/docs/02-usage/020_running.md index 3f57d77a..1af40b13 100644 --- a/docs/02-usage/020_running.md +++ b/docs/02-usage/020_running.md @@ -41,6 +41,11 @@ Explore the CLI to see some of the customization options that serena provides (m uv run --directory /abs/path/to/serena serena ``` +:::{note} +Adding the `--directory` option results in the working directory being set to the Serena directory. +As a consequence, you will need to specify paths when using CLI commands that would otherwise operate on the current directory. +::: + (docker)= ### Using Docker (Experimental) @@ -158,6 +163,61 @@ To get help on a specific command, run: --help +In general, add `--help` to any command or sub-command to get information about its usage and available options. + Here are some examples of commands you might find useful: - # TODO +```bash +# get help about a sub-command + tools list --help + +# list all available tools + tools list --all + +# get detailed description of a specific tool + tools description find_symbol + +# creating a new Serena project in the current directory + project generate-yml + +# indexing the project in the current directory + project index + +# run a health check on the project in the current directory + project health-check + +# check if a path is ignored by the project + project is_ignored_path path/to/check + +# edit Serena's configuration file + config edit + +# list available contexts + context list + +# create a new context + context create my-custom-context + +# edit a custom context + context edit my-custom-context + +# list available modes + mode list + +# create a new mode + mode create my-custom-mode + +# edit a custom mode + mode edit my-custom-mode + +# list available prompt definitions + prompts list + +# create an override for internal prompts + prompts create-override prompt-name + +# edit a prompt override + prompts edit-override prompt-name +``` + +Explore the full set of commands and options using the CLI itself! \ No newline at end of file From 5dc5f5e5f063d0258f95b2cd559fad42a4e6c065 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Sat, 8 Nov 2025 15:05:02 +0100 Subject: [PATCH 21/21] Build docs for main branch --- .github/workflows/docs.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 527c4bfa..e62d5cd2 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -2,8 +2,7 @@ name: Docs Build on: push: - # TODO change branch to main once docs is merged - branches: [ docs ] + branches: [ main ] workflow_dispatch: permissions: