diff --git a/README.md b/README.md index 145d5498..ccc7f0c2 100644 --- a/README.md +++ b/README.md @@ -102,46 +102,47 @@ implementation. -* [Quick Start](#quick-start) +- [Quick Start](#quick-start) * [Running the Serena MCP Server](#running-the-serena-mcp-server) - * [Usage](#usage) - * [Using uvx](#using-uvx) + + [Usage](#usage) + - [Using uvx](#using-uvx) * [Local Installation](#local-installation) - * [Using Docker (Experimental)](#using-docker-experimental) - * [SSE Mode](#sse-mode) - * [Command-Line Arguments](#command-line-arguments) + - [Using Docker (Experimental)](#using-docker-experimental) + + [SSE Mode](#sse-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) +- [Detailed Usage and Recommendations](#detailed-usage-and-recommendations) * [Tool Execution](#tool-execution) - * [Shell Execution and Editing Tools](#shell-execution-and-editing-tools) + + [Shell Execution and Editing Tools](#shell-execution-and-editing-tools) * [Modes and Contexts](#modes-and-contexts) - * [Contexts](#contexts) - * [Modes](#modes) - * [Customization](#customization) + + [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) + + [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) * [Potential Issues in Code Editing](#potential-issues-in-code-editing) * [Running Out of Context](#running-out-of-context) * [Combining Serena with Other MCP Servers](#combining-serena-with-other-mcp-servers) * [Serena's Logs: The Dashboard and GUI Tool](#serenas-logs-the-dashboard-and-gui-tool) * [Troubleshooting](#troubleshooting) -* [Comparison with Other Coding Agents](#comparison-with-other-coding-agents) +- [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) -* [Customizing and Extending Serena](#customizing-and-extending-serena) -* [List of Tools](#list-of-tools) +- [Acknowledgements](#acknowledgements) +- [Customizing and Extending Serena](#customizing-and-extending-serena) +- [List of Tools](#list-of-tools) @@ -348,6 +349,33 @@ claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena 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), diff --git a/src/serena/resources/config/contexts/codex.yml b/src/serena/resources/config/contexts/codex.yml new file mode 100644 index 00000000..27a13673 --- /dev/null +++ b/src/serena/resources/config/contexts/codex.yml @@ -0,0 +1,26 @@ +description: Non-symbolic editing tools and general shell tool are excluded +prompt: | + You are running in IDE assistant context where file operations, basic (line-based) edits and reads, + and shell commands are handled by your own, internal tools. + The initial instructions and the current config inform you on which tools are available to you, + and how to use them. + Don't attempt to use any excluded tools, instead rely on your own internal tools + for achieving the basic file or shell operations. + + If serena's tools can be used for achieving your task, + you should prioritize them. In particular, it is important that you avoid reading entire source code files, + unless it is strictly necessary! Instead, for exploring and reading code in a token-efficient manner, + you should use serena's overview and symbolic search tools. The call of the read_file tool on an entire source code + file should only happen in exceptional cases, usually you should first explore the file (by itself or as part of exploring + the directory containing it) using the symbol_overview tool, and then make targeted reads using find_symbol and other symbolic tools. + For non-code files or for reads where you don't know the symbol's name path you can use the patterns searching tool, + using the read_file as a last resort. + +excluded_tools: + - create_text_file + - read_file + - execute_shell_command + - prepare_for_new_conversation + +tool_description_overrides: {} +