anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-21 17:56:33 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

Feature Request: Integrate Serena for Semantic Code Understanding #3918

New Issue
Open
opened 2026-02-16 17:41:56 -05:00 by yindo · 4 comments
yindo commented 2026-02-16 17:41:56 -05:00
Owner
Copy Link
Copy Source

Originally created by @layeddie on GitHub (Dec 27, 2025).

Originally assigned to: @thdxr on GitHub.

title: "[Feature Request] Integrate Serena for Semantic Code Understanding"
labels: ["enhancement", "mcp", "semantic-search"]

Feature Request: Integrate Serena for Semantic Code Understanding

Summary

Add support for Serena - a powerful coding agent toolkit providing semantic code retrieval and editing capabilities via Language Server Protocol (LSP).

Background

Currently, OpenCode has excellent file-level search capabilities but lacks semantic code understanding. When I ask questions like:

  • "Find all usages of this function"
  • "Go to definition of this symbol"
  • "Show me the class hierarchy"
  • "Where is error handling for API calls?"

These require understanding code structure and relationships, not just text matching.

Serena provides IDE-like semantic capabilities:

  • Symbol-level code understanding via LSP
  • Find references across codebase
  • Go to definition/declaration
  • Precise code edits at symbol level
  • Cross-language support

Why Serena?

  1. MCP Compatible: Serena works as MCP server - OpenCode already supports MCP
  2. Actively Maintained: 16.1K+ stars, active development
  3. Proven Technology: Used in production by teams building AI coding agents
  4. Token Efficient: Semantic retrieval reduces context needed vs grep/text search
  5. Framework Agnostic: Not tied to specific LLMs

Proposed Implementation

Option 1: MCP Server Integration (Recommended)

Add Serena as built-in MCP server in OpenCode:

// ~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "serena": {
      "type": "local",
      "command": "serena",
      "args": ["mcp"],
      "enabled": true
    }
  }
}

Benefits:

  • Users can enable/disable in config
  • Leverages existing MCP infrastructure
  • No breaking changes

Option 2: Direct Tool Integration

Add Serena as first-class OpenCode tool (similar to existing grep/ripgrep tools):

{
  name: "serena_find_symbols",
  description: "Find symbols and references using Serena LSP",
  parameters: {
    type: "object",
    properties: {
      query: { type: "string" },
      language: { type: "string" }
    }
  }
}

Option 3: Auto-Detection

Automatically detect and integrate Serena when:

  1. serena binary is in PATH
  2. serena MCP server is available
  3. Serena config exists in project

Use Cases

1. Semantic Code Search

User prompt: "Find all functions that handle user authentication"

Current behavior: Uses grep/ripgrep - matches text "authentication"
With Serena: Returns functions authenticateUser(), login(), verifyCredentials() with file locations and line numbers

2. Go to Definition

User prompt: "Show me the User schema definition"

Current behavior: Searches files for "User" and "schema"
With Serena: Jumps directly to User class/interface definition with import tree

3. Find References

User prompt: "Where is PaymentProcessor used?"

Current behavior: Text search for "PaymentProcessor"
With Serena: Returns list of all usages with context (imports, instantiations, method calls)

4. Cross-File Refactoring

User prompt: "Rename UserService to AccountService across all files"

Current behavior: Text search and replace (error-prone)
With Serena: Semantic rename across LSP-aware files (safely)

Technical Details

Serena Capabilities

From Serena README:

  • Symbol search and navigation
  • Cross-reference finding
  • Semantic code retrieval
  • Multi-language support (TypeScript, Python, Go, etc.)
  • LSP-based editing primitives

Integration Effort

  • MCP Path: Low (2-3 hours) - Serena has MCP support
  • Direct Path: Medium (1-2 days) - Needs tool registration
  • Auto-Detection: Medium (1 day) - Add detection logic

Alternatives Considered

  1. Keep using grep/ripgrep: Fast, but no semantic understanding
  2. Build custom LSP client: Higher effort, maintenance burden
  3. Use existing MCP servers: See below (directory-indexer, Codebase)

Related Issues

References

Acceptance Criteria

  • Serena can be added as MCP server in opencode.json
  • OpenCode can call Serena tools (symbol search, go-to-definition)
  • Documentation updated with Serena examples
  • User feedback from beta testing
  • Performance impact evaluated (should be minimal)

Questions for Maintainers

  1. Do you prefer MCP server integration or direct tool integration?
  2. Should Serena be opt-in or auto-detected?
  3. Are there concerns about adding another MCP server (token usage)?

Open these issues to discuss approach and implementation details!

Originally created by @layeddie on GitHub (Dec 27, 2025). Originally assigned to: @thdxr on GitHub. --- title: "[Feature Request] Integrate Serena for Semantic Code Understanding" labels: ["enhancement", "mcp", "semantic-search"] --- # Feature Request: Integrate Serena for Semantic Code Understanding ## Summary Add support for [Serena](https://github.com/oraios/serena) - a powerful coding agent toolkit providing semantic code retrieval and editing capabilities via Language Server Protocol (LSP). ## Background Currently, OpenCode has excellent file-level search capabilities but lacks **semantic code understanding**. When I ask questions like: - "Find all usages of this function" - "Go to definition of this symbol" - "Show me the class hierarchy" - "Where is error handling for API calls?" These require understanding code structure and relationships, not just text matching. Serena provides IDE-like semantic capabilities: - Symbol-level code understanding via LSP - Find references across codebase - Go to definition/declaration - Precise code edits at symbol level - Cross-language support ## Why Serena? 1. **MCP Compatible**: Serena works as MCP server - OpenCode already supports MCP 2. **Actively Maintained**: 16.1K+ stars, active development 3. **Proven Technology**: Used in production by teams building AI coding agents 4. **Token Efficient**: Semantic retrieval reduces context needed vs grep/text search 5. **Framework Agnostic**: Not tied to specific LLMs ## Proposed Implementation ### Option 1: MCP Server Integration (Recommended) Add Serena as built-in MCP server in OpenCode: ```json // ~/.config/opencode/opencode.json { "$schema": "https://opencode.ai/config.json", "mcp": { "serena": { "type": "local", "command": "serena", "args": ["mcp"], "enabled": true } } } ``` **Benefits:** - Users can enable/disable in config - Leverages existing MCP infrastructure - No breaking changes ### Option 2: Direct Tool Integration Add Serena as first-class OpenCode tool (similar to existing grep/ripgrep tools): ```javascript { name: "serena_find_symbols", description: "Find symbols and references using Serena LSP", parameters: { type: "object", properties: { query: { type: "string" }, language: { type: "string" } } } } ``` ### Option 3: Auto-Detection Automatically detect and integrate Serena when: 1. `serena` binary is in PATH 2. `serena` MCP server is available 3. Serena config exists in project ## Use Cases ### 1. Semantic Code Search **User prompt:** "Find all functions that handle user authentication" **Current behavior:** Uses grep/ripgrep - matches text "authentication" **With Serena:** Returns functions `authenticateUser()`, `login()`, `verifyCredentials()` with file locations and line numbers ### 2. Go to Definition **User prompt:** "Show me the User schema definition" **Current behavior:** Searches files for "User" and "schema" **With Serena:** Jumps directly to `User` class/interface definition with import tree ### 3. Find References **User prompt:** "Where is PaymentProcessor used?" **Current behavior:** Text search for "PaymentProcessor" **With Serena:** Returns list of all usages with context (imports, instantiations, method calls) ### 4. Cross-File Refactoring **User prompt:** "Rename UserService to AccountService across all files" **Current behavior:** Text search and replace (error-prone) **With Serena:** Semantic rename across LSP-aware files (safely) ## Technical Details ### Serena Capabilities From [Serena README](https://github.com/oraios/serena): - Symbol search and navigation - Cross-reference finding - Semantic code retrieval - Multi-language support (TypeScript, Python, Go, etc.) - LSP-based editing primitives ### Integration Effort - **MCP Path**: Low (2-3 hours) - Serena has MCP support - **Direct Path**: Medium (1-2 days) - Needs tool registration - **Auto-Detection**: Medium (1 day) - Add detection logic ## Alternatives Considered 1. **Keep using grep/ripgrep**: Fast, but no semantic understanding 2. **Build custom LSP client**: Higher effort, maintenance burden 3. **Use existing MCP servers**: See below (directory-indexer, Codebase) ## Related Issues - Split off MCP configuration: #1998 - MCP server documentation: [docs/mcp-servers](https://opencode.ai/docs/mcp-servers/) ## References - Serena repo: https://github.com/oraios/serena - Serena MCP integration: MCP server mode - OpenCode MCP docs: https://opencode.ai/docs/mcp-servers/ ## Acceptance Criteria - [ ] Serena can be added as MCP server in `opencode.json` - [ ] OpenCode can call Serena tools (symbol search, go-to-definition) - [ ] Documentation updated with Serena examples - [ ] User feedback from beta testing - [ ] Performance impact evaluated (should be minimal) ## Questions for Maintainers 1. Do you prefer MCP server integration or direct tool integration? 2. Should Serena be opt-in or auto-detected? 3. Are there concerns about adding another MCP server (token usage)? --- **Open these issues to discuss approach and implementation details!**
yindo added the mcp label 2026-02-16 17:41:56 -05:00
yindo commented 2026-02-16 17:41:56 -05:00
Author
Owner
Copy Link
Copy Source

@github-actions[bot] commented on GitHub (Dec 27, 2025):

This issue might be a duplicate or related to existing feature requests. Please check:

  • #3184: Semantic Indexing - Asks if OpenCode uses semantic indexing of the codebase like Cursor
  • #2681: Add some default semantic search/parsing capability - Proposes integrating semantic search tools (semtools) for better code understanding
  • #4986: Support for a local Relevance Index - Requests a local relevance index data structure to supplement source code with relevance weights for better AI assistance
  • #5831: How to make use of the LSP? - Discusses LSP support and how users can access LSP capabilities
  • #4410: Export LSP functionality through @opencode-ai/plugin for custom tools - Requests exposing LSP functionality for custom tools
  • #438: more LSP - General request for more LSP support

Feel free to ignore if none of these address your specific use case.

@github-actions[bot] commented on GitHub (Dec 27, 2025): This issue might be a duplicate or related to existing feature requests. Please check: - #3184: Semantic Indexing - Asks if OpenCode uses semantic indexing of the codebase like Cursor - #2681: Add some default semantic search/parsing capability - Proposes integrating semantic search tools (semtools) for better code understanding - #4986: Support for a local Relevance Index - Requests a local relevance index data structure to supplement source code with relevance weights for better AI assistance - #5831: How to make use of the LSP? - Discusses LSP support and how users can access LSP capabilities - #4410: Export LSP functionality through @opencode-ai/plugin for custom tools - Requests exposing LSP functionality for custom tools - #438: more LSP - General request for more LSP support Feel free to ignore if none of these address your specific use case.
yindo commented 2026-02-16 17:41:56 -05:00
Author
Owner
Copy Link
Copy Source

@gytis-ivaskevicius commented on GitHub (Jan 6, 2026):

Hi, can you elaborate how serena improves your workflow? Does it actually save tokens? I just wrote my mini review of this idea here https://github.com/anomalyco/opencode/issues/438#issuecomment-3715040617

@gytis-ivaskevicius commented on GitHub (Jan 6, 2026): Hi, can you elaborate how serena improves your workflow? Does it actually save tokens? I just wrote my mini review of this idea here https://github.com/anomalyco/opencode/issues/438#issuecomment-3715040617
yindo commented 2026-02-16 17:41:56 -05:00
Author
Owner
Copy Link
Copy Source

@layeddie commented on GitHub (Jan 7, 2026):

Hi, can you elaborate how serena improves your workflow? Does it actually save tokens? I just wrote my mini review of this idea here #438 (comment)

One of the main objects of my local AI coding assistant project was to focus on using tools that would reduce token count and I asked opencode to review mgrep and serena. What prompted me was seranas LSP like features. LSP's are now the focus in AI coding tools now. I have builtin mgrep and serana to my project now but cant report on the benefits yet.

I just saw your comment in #438
Also, on Serena, I reached the same conclusion than you, it would only work if LSP edits are part of OpenCode core (which I think is in progress and available as experimental feature)

I dont know if you mean LSP's are part of OpenCode core or Serena are in progress?
At the moment OpenCode has already got very good LSP support builtin. As I tend to do now - I ask opencode to give me the answer. I am just asking it to review my use of mgrep, serana and ElixirLS... and the answer is....

**Final Recommendation
Your current configuration is optimal for reducing token count while maintaining idiomatic Elixir code quality. The three tools complement each other perfectly:

  1. mgrep → Semantic discovery (plan/review)
  2. Serena → Symbolic precision (build/review)
  3. Expert → Diagnostics and OTP best practices (all modes)
    Minor optimization: Consider disabling OpenCode's built-in LSP when Serena is active to prevent conflicts, or use them selectively based on workflow.**

I am looking in to the suggestion.. I think using them selectively is the answer

@layeddie commented on GitHub (Jan 7, 2026): > Hi, can you elaborate how serena improves your workflow? Does it actually save tokens? I just wrote my mini review of this idea here [#438 (comment)](https://github.com/anomalyco/opencode/issues/438#issuecomment-3715040617) One of the main objects of my local AI coding assistant project was to focus on using tools that would reduce token count and I asked opencode to review mgrep and serena. What prompted me was seranas LSP like features. LSP's are now the focus in AI coding tools now. I have builtin mgrep and serana to my project now but cant report on the benefits yet. I just saw your comment in #438 _Also, on Serena, I reached the same conclusion than you, it would only work if LSP edits are part of OpenCode core (which I think is in progress and available as experimental feature)_ I dont know if you mean LSP's are part of OpenCode core or Serena are in progress? At the moment OpenCode has already got very good LSP support builtin. As I tend to do now - I ask opencode to give me the answer. I am just asking it to review my use of mgrep, serana and ElixirLS... and the answer is.... **Final Recommendation Your current configuration is optimal for reducing token count while maintaining idiomatic Elixir code quality. The three tools complement each other perfectly: 1. mgrep → Semantic discovery (plan/review) 2. Serena → Symbolic precision (build/review) 3. Expert → Diagnostics and OTP best practices (all modes) Minor optimization: Consider disabling OpenCode's built-in LSP when Serena is active to prevent conflicts, or use them selectively based on workflow.** I am looking in to the suggestion.. I think using them selectively is the answer
yindo commented 2026-02-16 17:41:56 -05:00
Author
Owner
Copy Link
Copy Source

@gytis-ivaskevicius commented on GitHub (Jan 7, 2026):

It's not my comment but close enough :D

So Serena states massive token savings which I was not able to reproduce even tho I basically got it almost perfectly integrated with custom system prompt. One of the issues is that LLMs strongly prefers using edit tool because that's what they are trained on

Few times I worked on a task and afterwards I asked LLM if Serena was worth it, it said no...

As for saving tokens, one of the conclusions I came to is that it's better to disable tools such as grep/glob and instead let it use bash. Minor improvement tho

@gytis-ivaskevicius commented on GitHub (Jan 7, 2026): It's not my comment but close enough :D So Serena states massive token savings which I was not able to reproduce even tho I basically got it almost perfectly integrated with custom system prompt. One of the issues is that LLMs strongly prefers using edit tool because that's what they are trained on Few times I worked on a task and afterwards I asked LLM if Serena was worth it, it said no... As for saving tokens, one of the conclusions I came to is that it's better to disable tools such as grep/glob and instead let it use bash. Minor improvement tho
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label mcp
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#3918
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?