diff --git a/README.md b/README.md index d59dbd3c..16b6a6af 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ For example, **supercharge the performance of Claude Code** with a [one-line she Serena can be integrated with an LLM in several ways: -* by using the **model context protocol (MCP)**. +* 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, @@ -80,7 +80,7 @@ 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](docs/serena_on_chatgpt.md) or other clients that don't support MCP but do support tool calling. -* 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](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. ### Programming Language Support & Semantic Analysis Capabilities @@ -259,6 +259,16 @@ Alternatively, use docker compose with the `compose.yml` file provided in the re 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`. + #### SSE Mode ℹ️ Note that MCP servers which use stdio as a protocol are somewhat unusual as far as client/server architectures go, as the server @@ -395,7 +405,7 @@ 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 +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). @@ -467,7 +477,7 @@ That's it! Save the config and then restart Claude Desktop. You are ready for ac 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. +⚠️ 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 @@ -548,7 +558,7 @@ Serena comes with pre-defined contexts: * `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 `. +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`. @@ -622,7 +632,7 @@ We found that memories can significantly improve the user experience with Serena 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). +with enormous, non-modular functions). Furthermore, for languages that are not statically typed, type annotations are highly beneficial. #### Start from a Clean State @@ -670,7 +680,7 @@ line-level insertions are useful. Serena is instructed to double-check the line numbers and any code blocks that it will edit, but you may find it useful to explicitly tell it how to edit code if you run into -problems. +problems. We are working on making Serena's editing capabilities more robust. ### Running Out of Context diff --git a/flake.lock b/flake.lock new file mode 100644 index 00000000..728ba12a --- /dev/null +++ b/flake.lock @@ -0,0 +1,133 @@ +{ + "nodes": { + "flake-utils": { + "inputs": { + "systems": "systems" + }, + "locked": { + "lastModified": 1731533236, + "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=", + "owner": "numtide", + "repo": "flake-utils", + "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b", + "type": "github" + }, + "original": { + "owner": "numtide", + "repo": "flake-utils", + "type": "github" + } + }, + "nixpkgs": { + "locked": { + "lastModified": 1755615617, + "narHash": "sha256-HMwfAJBdrr8wXAkbGhtcby1zGFvs+StOp19xNsbqdOg=", + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "20075955deac2583bb12f07151c2df830ef346b4", + "type": "github" + }, + "original": { + "owner": "NixOS", + "ref": "nixos-unstable", + "repo": "nixpkgs", + "type": "github" + } + }, + "pyproject-build-systems": { + "inputs": { + "nixpkgs": [ + "nixpkgs" + ], + "pyproject-nix": [ + "pyproject-nix" + ], + "uv2nix": [ + "uv2nix" + ] + }, + "locked": { + "lastModified": 1755484659, + "narHash": "sha256-2FfbqsaHVQd12XFFUAinIMAuGO3853LONmva1gT3vKw=", + "owner": "pyproject-nix", + "repo": "build-system-pkgs", + "rev": "9778e87c2361810ff15e287ca5895c9da4a0e900", + "type": "github" + }, + "original": { + "owner": "pyproject-nix", + "repo": "build-system-pkgs", + "type": "github" + } + }, + "pyproject-nix": { + "inputs": { + "nixpkgs": [ + "nixpkgs" + ] + }, + "locked": { + "lastModified": 1755886095, + "narHash": "sha256-oMQ1YERKqiac28LB1cKjl4d0gjvK98SbGejFMfK0WGE=", + "owner": "pyproject-nix", + "repo": "pyproject.nix", + "rev": "7ea903d50c20d4d3ea45ccaad7ee0d21996780c9", + "type": "github" + }, + "original": { + "owner": "pyproject-nix", + "repo": "pyproject.nix", + "type": "github" + } + }, + "root": { + "inputs": { + "flake-utils": "flake-utils", + "nixpkgs": "nixpkgs", + "pyproject-build-systems": "pyproject-build-systems", + "pyproject-nix": "pyproject-nix", + "uv2nix": "uv2nix" + } + }, + "systems": { + "locked": { + "lastModified": 1681028828, + "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=", + "owner": "nix-systems", + "repo": "default", + "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e", + "type": "github" + }, + "original": { + "owner": "nix-systems", + "repo": "default", + "type": "github" + } + }, + "uv2nix": { + "inputs": { + "nixpkgs": [ + "nixpkgs" + ], + "pyproject-nix": [ + "pyproject-nix" + ] + }, + "locked": { + "lastModified": 1755887980, + "narHash": "sha256-MD1IhwuoDXQSYcQ/JfEpMxrk6pPl+aHPXSqZLOXLHks=", + "owner": "pyproject-nix", + "repo": "uv2nix", + "rev": "76778b5f457e416688324d19d8f02ec5e22cbe0c", + "type": "github" + }, + "original": { + "owner": "pyproject-nix", + "repo": "uv2nix", + "type": "github" + } + } + }, + "root": "root", + "version": 7 +} diff --git a/flake.nix b/flake.nix new file mode 100644 index 00000000..e92f1999 --- /dev/null +++ b/flake.nix @@ -0,0 +1,101 @@ +{ + description = "A powerful coding agent toolkit providing semantic retrieval and editing capabilities (MCP server & Agno integration)"; + + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + + flake-utils = { + url = "github:numtide/flake-utils"; + }; + + pyproject-nix = { + url = "github:pyproject-nix/pyproject.nix"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + + uv2nix = { + url = "github:pyproject-nix/uv2nix"; + inputs = { + pyproject-nix.follows = "pyproject-nix"; + nixpkgs.follows = "nixpkgs"; + }; + }; + + pyproject-build-systems = { + url = "github:pyproject-nix/build-system-pkgs"; + inputs = { + pyproject-nix.follows = "pyproject-nix"; + uv2nix.follows = "uv2nix"; + nixpkgs.follows = "nixpkgs"; + }; + }; + }; + + outputs = { + nixpkgs, + uv2nix, + pyproject-nix, + pyproject-build-systems, + flake-utils, + ... + }: + flake-utils.lib.eachDefaultSystem (system: let + pkgs = import nixpkgs {inherit system;}; + + inherit (pkgs) lib; + + workspace = uv2nix.lib.workspace.loadWorkspace {workspaceRoot = ./.;}; + + overlay = workspace.mkPyprojectOverlay { + sourcePreference = "wheel"; # or sourcePreference = "sdist"; + }; + + pyprojectOverrides = _final: _prev: {}; + + python = pkgs.python311; + + pythonSet = + (pkgs.callPackage pyproject-nix.build.packages { + inherit python; + }).overrideScope + ( + lib.composeManyExtensions [ + pyproject-build-systems.overlays.default + overlay + pyprojectOverrides + ] + ); + in rec { + formatter = pkgs.alejandra; + + packages = { + serena = pythonSet.mkVirtualEnv "serena" workspace.deps.default; + default = packages.serena; + }; + + apps.default = { + type = "app"; + program = "${packages.default}/bin/serena"; + }; + + devShells = { + default = pkgs.mkShell { + packages = [ + python + pkgs.uv + ]; + env = + { + UV_PYTHON_DOWNLOADS = "never"; + UV_PYTHON = python.interpreter; + } + // lib.optionalAttrs pkgs.stdenv.isLinux { + LD_LIBRARY_PATH = lib.makeLibraryPath pkgs.pythonManylinuxPackages.manylinux1; + }; + shellHook = '' + unset PYTHONPATH + ''; + }; + }; + }); +}