Intro
Recently, I started using Claude Code (terminal type AI coding agent tool by Anthoropic). I am using "Pro plan" which has a token limit every 5 hours. Claude Code always reaches the token limit right in the middle of a difficult coding task.🤯 So, my journey to use AI more efficiently started.🚀
I found that SuperClaude and Serena looked good for this purpose. I wanted to use it for free, but both are OSS and met my needs.🤑 Finally, I choose Serena because SuperClaude uses Serena inside, so I thought Serena was the more essential system to learn first. OK, let's look at what Serena can do.🔍
What is Serena?
Serena is a coding agent toolkit that provides semantic code retrieval and editing tools.
https://github.com/oraios/serena
Serena can not only save tokens but also speed up AI responses and improve response quality. You can use Serena at Claude Code, Cursor, Cline, VSCode and others as a MCP (Model Context Protocol). Serena supports programming language such as TypeScript, JavaScript, Python, Java, C# and more.
Usually, AI reads all the code before responding. On the other hand, Serena makes index first to read the code efficiently. Also, Serena will make some md files in ".serena/memories" to understand the project and use them to handle processes more efficiently. After that, Serena uses its own tools not to read the whole code but to read only the necessary code. Cursor already has an indexing system, but Claude Code does not, so using Serena will extremely boost your Claude Code.
Please note that Serena is more suitable for large projects, and may not perform the best on small projects.
I have seen people say Serena can save your tokens up to about 70%! In my experience, Serena does save tokens and extend the time before hitting Claude Code limit. Amazing!😀
How to use Serena
There are only 3 steps to use Serena.
1️⃣ Install
2️⃣ Onboarding
3️⃣ Indexing
1️⃣ Install
↓ Install and connect it with Claude Code
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)
↓ For install expect Claude Code, please check the official documentation.
https://github.com/oraios/serena?tab=readme-ov-file#quick-start
After installing Serena and running Claude Code, it automatically starts a log dashboard in your browser and makes a .serena folder in your root directory. Inside .serena, a project configuration file project.yml is also made.
↓ Dashboard image
2️⃣ Onboarding
When you use Serena for the first time, you need to run Onboarding. Onboarding is a process for Serena to read and understand the project and prepare for your coding. Onboarding makes memories (md files) in .serena\memories folder. This onboarding process reads many files and consumes many tokens, so be careful not to run out of tokens. To run Onboarding, you need to ask your Claude Code (or another tool) to start Serena Onboarding in the chat. Also, in my case, some part of the memories were not accurate, and I need to fix them.
3️⃣ Indexing
Onboarding process also made a cache file .serena\cache\typescript\document_symbols_cache_v23-06-25.pkl. When I open the cache with my Cursor editor, it was garbled but I could see the indexes ware made. However, the index did not seem to cover the whole project. So, I ran the command below and made the index for the whole project.
uvx --from git+https://github.com/oraios/serena serena project index
✅ Code Sample
I tried Serena onboarding with my project that I made last time.
↓ Next.js project for SSR API test by Playwright and Mock Service Worker (MSW)
https://dev.to/webdeveloperhyper/how-to-test-nextjs-ssr-api-playwright-msw-part-2-parallel-test-3akj
Serena read files such as package.json, playwright.config.ts, tsconfig.json, tests\example.spec.ts, mock-server.ts, and made project.yml (configuration file) and memories (md files) as follows.
↓ .serena/project.yml
# language of the project (csharp, python, rust, java, typescript, go, cpp, or ruby)
# * For C, use cpp
# * For JavaScript, use typescript
# Special requirements:
# * csharp: Requires the presence of a .sln file in the project folder.
language: typescript
# whether to use the project's gitignore file to ignore files
# Added on 2025-04-07
ignore_all_files_in_gitignore: true
# list of additional paths to ignore
# same syntax as gitignore, so you can use * and **
# Was previously called `ignored_dirs`, please update your config if you are using that.
# Added (renamed) on 2025-04-07
ignored_paths: []
# whether the project is in read-only mode
# If set to true, all editing tools will be disabled and attempts to use them will result in an error
# Added on 2025-04-18
read_only: false
# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
# Below is the complete list of tools for convenience.
# To make sure you have the latest list of tools, and to view their descriptions,
# execute `uv run scripts/print_tool_overview.py`.
#
# * `activate_project`: Activates a project by name.
# * `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_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
# * `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.
# * `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_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.
# * `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.
# * `remove_project`: Removes a project from the Serena configuration.
# * `replace_lines`: Replaces a range of lines within a file with new content.
# * `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.
excluded_tools: []
# initial prompt for the project. It will always be given to the LLM upon activating the project
# (contrary to the memories, which are loaded on demand).
initial_prompt: ""
project_name: "nextjs_playwright_msw_parallel"
↓ .serena\memories\code_style_and_conventions.md
# Code Style and Conventions
## TypeScript Configuration
- **Strict Mode**: Enabled with full type checking
- **Target**: ES2017
- **Module System**: ESNext with bundler resolution
- **Path Mapping**: `@/*` maps to `./src/*`
- **JSX**: Preserve mode for Next.js processing
## Code Style Patterns
- **Async/Await**: Used consistently for asynchronous operations
- **Function Components**: React functional components with TypeScript
- **Export Default**: Components exported as default functions
- **Destructuring**: Props and search parameters destructured in function signatures
- **Template Literals**: Used for dynamic strings and URLs
- **Error Boundaries**: Try-catch blocks for API error handling
## Naming Conventions
- **Components**: PascalCase (e.g., `Home`, `DemoTitle`)
- **Variables**: camelCase (e.g., `mockPort`, `pokemon`)
- **Files**: kebab-case for general files, PascalCase for React components
- **Constants**: UPPER_SNAKE_CASE for environment variables
## Import/Export Patterns
- **Named Imports**: Used for utilities and types
- **Default Exports**: Used for React components
- **Relative Imports**: Used for local modules
- **Absolute Imports**: Used with `@/` path mapping
## CSS/Styling
- **Tailwind CSS**: Utility-first CSS framework
- **Responsive Design**: Mobile-first approach
- **Component Styling**: Inline className attributes
- **Custom Fonts**: Geist Sans and Geist Mono loaded via next/font
↓ .serena\memories\project_overview.md
# Project Overview
## Purpose
This is a Next.js 15 demo application that demonstrates parallel testing with Playwright and MSW (Mock Service Worker). The app displays Pokemon data fetched from a mock API, with the ability to switch between different Pokemon through MSW's dynamic mocking capabilities.
## Key Features
- **Pokemon Display**: Shows Pokemon name, image, and ID number
- **Dynamic Mock Testing**: Tests can switch between different Pokemon data using MSW
- **Parallel Testing**: Supports multiple mock servers for parallel test execution
- **Error Handling**: Graceful error display when API calls fail
## Tech Stack
- **Frontend**: Next.js 15.5.2 with React 19.1.0
- **Styling**: Tailwind CSS 4
- **Testing**: Playwright with MSW for API mocking
- **TypeScript**: Full TypeScript support with strict mode
- **Build Tool**: Next.js built-in bundler
## Architecture
- `src/app/` - Next.js App Router structure
- `src/mocks/` - MSW handlers and server setup
- `tests/` - Playwright test files
- `mock-server.ts` - Bridge server for test-MSW communication
↓ .serena\memories\project_structure.md
# Project Structure
## Directory Layout
├── src/
│ ├── app/ # Next.js App Router
│ │ ├── favicon.ico # Website favicon
│ │ ├── globals.css # Global CSS styles
│ │ ├── layout.tsx # Root layout component
│ │ └── page.tsx # Home page component
│ └── mocks/ # MSW mock setup
│ ├── handlers.ts # API request handlers
│ └── server.ts # MSW server configuration
├── tests/ # Playwright test files
│ └── example.spec.ts # Pokemon API tests
├── tests-examples/ # Additional test examples
├── public/ # Static assets
├── mock-server.ts # Mock server bridge
├── playwright.config.ts # Playwright configuration
├── next.config.ts # Next.js configuration
├── tsconfig.json # TypeScript configuration
├── postcss.config.mjs # PostCSS configuration
├── package.json # Dependencies and scripts
└── README.md # Project documentation
## Key Files
- **src/app/page.tsx**: Main Pokemon display component with async data fetching
- **src/mocks/handlers.ts**: MSW request handlers for Pokemon API
- **src/mocks/server.ts**: MSW server setup with dynamic mock switching
- **mock-server.ts**: Bridge server that coordinates between tests and MSW
- **tests/example.spec.ts**: Comprehensive Playwright tests for Pokemon data
- **playwright.config.ts**: Test configuration with parallel execution support
## Architecture Patterns
- **App Router**: Next.js 15 App Router structure
- **Server Components**: Async server components for data fetching
- **Mock Service Worker**: API mocking in Node.js environment
- **Test Isolation**: Parallel test execution with separate mock server instances
↓ .serena\memories\suggested_commands.md
# Suggested Commands
## Development Commands
bash
# Start development server
npm run dev
# Build production version
npm run build
# Start production server
npm start
## Testing Commands
bash
# Run all Playwright tests
npx playwright test
# Run tests in headed mode (with browser UI)
npx playwright test --headed
# Run specific test file
npx playwright test tests/example.spec.ts
# Run tests with specific number of workers
MOCK_SERVER_COUNT=4 npx playwright test
# Generate test report
npx playwright show-report
## Mock Server Commands
bash
# Start single mock server
npx tsx mock-server.ts
# Start mock server on specific port
npx tsx mock-server.ts 3001
# Start multiple mock servers (set via environment)
MOCK_SERVER_COUNT=4 npx tsx mock-server.ts
## Utility Commands (Windows)
- **List files**: `dir` or `ls` (if Git Bash/WSL)
- **Change directory**: `cd`
- **Find files**: `where` or `find` (Git Bash)
- **Search in files**: `findstr` or `grep` (Git Bash)
- **Git operations**: `git status`, `git add`, `git commit`, etc.
## TypeScript Commands
bash
# Type check without compilation
npx tsc --noEmit
# Run TypeScript files directly
npx tsx filename.ts
↓ .serena\memories\task_completion_guidelines.md
# Task Completion Guidelines
## What to do when a task is completed
### 1. Code Quality Checks
Since this project doesn't have explicit linting or formatting commands in package.json, the following should be verified:
- **TypeScript compilation**: Run `npx tsc --noEmit` to check for type errors
- **Code style consistency**: Follow existing patterns in the codebase
- **Import organization**: Maintain consistent import order and structure
### 2. Testing Requirements
- **Run existing tests**: `npx playwright test` to ensure no regressions
- **Test new features**: Add appropriate Playwright tests for new functionality
- **Screenshot verification**: Tests generate screenshots for visual verification
- **Mock server compatibility**: Ensure changes work with the MSW setup
### 3. Build Verification
- **Development build**: Verify `npm run dev` works correctly
- **Production build**: Run `npm run build` to check for build errors
- **Type checking**: Ensure all TypeScript types are correct
### 4. Documentation Updates
- **Code comments**: Add inline documentation for complex logic
- **README updates**: Update README.md if adding new features or changing setup
- **Test documentation**: Document new test cases and their purpose
### 5. Git Workflow
- **Commit changes**: Create meaningful commit messages
- **Branch management**: Work on feature branches if applicable
- **Code review**: Review changes before merging
## Special Considerations
- **MSW Integration**: Test that mock server bridge still works correctly
- **Parallel Testing**: Ensure changes support parallel test execution
- **Environment Variables**: Check that MOCK_SERVER_COUNT handling is preserved
- **Port Management**: Verify port calculation for parallel workers remains functional
↓ .serena\memories\task_completion_guidelines.md
# Task Completion Guidelines
## What to do when a task is completed
### 1. Code Quality Checks
Since this project doesn't have explicit linting or formatting commands in package.json, the following should be verified:
- **TypeScript compilation**: Run `npx tsc --noEmit` to check for type errors
- **Code style consistency**: Follow existing patterns in the codebase
- **Import organization**: Maintain consistent import order and structure
### 2. Testing Requirements
- **Run existing tests**: `npx playwright test` to ensure no regressions
- **Test new features**: Add appropriate Playwright tests for new functionality
- **Screenshot verification**: Tests generate screenshots for visual verification
- **Mock server compatibility**: Ensure changes work with the MSW setup
### 3. Build Verification
- **Development build**: Verify `npm run dev` works correctly
- **Production build**: Run `npm run build` to check for build errors
- **Type checking**: Ensure all TypeScript types are correct
### 4. Documentation Updates
- **Code comments**: Add inline documentation for complex logic
- **README updates**: Update README.md if adding new features or changing setup
- **Test documentation**: Document new test cases and their purpose
### 5. Git Workflow
- **Commit changes**: Create meaningful commit messages
- **Branch management**: Work on feature branches if applicable
- **Code review**: Review changes before merging
## Special Considerations
- **MSW Integration**: Test that mock server bridge still works correctly
- **Parallel Testing**: Ensure changes support parallel test execution
- **Environment Variables**: Check that MOCK_SERVER_COUNT handling is preserved
- **Port Management**: Verify port calculation for parallel workers remains functional
↓ .serena\memories\tech_stack_and_dependencies.md
# Tech Stack and Dependencies
## Core Dependencies
- **next**: 15.5.2 - React framework with App Router
- **react**: 19.1.0 - UI library
- **react-dom**: 19.1.0 - React DOM bindings
## Development Dependencies
- **@playwright/test**: ^1.55.0 - End-to-end testing framework
- **@tailwindcss/postcss**: ^4 - Tailwind CSS PostCSS plugin
- **tailwindcss**: ^4 - Utility-first CSS framework
- **typescript**: ^5 - TypeScript compiler
- **@types/node**: ^20 - Node.js type definitions
- **@types/react**: ^19 - React type definitions
- **@types/react-dom**: ^19 - React DOM type definitions
- **msw**: ^2.11.1 - Mock Service Worker for API mocking
- **dotenv**: ^17.2.2 - Environment variable loading
- **tsx**: ^4.20.5 - TypeScript execution engine
## Configuration Files
- **tsconfig.json**: TypeScript configuration with strict mode, path mapping (@/* to src/*)
- **next.config.ts**: Next.js configuration
- **playwright.config.ts**: Playwright test configuration with parallel execution
- **postcss.config.mjs**: PostCSS configuration for Tailwind
- **package.json**: Project dependencies and scripts
Outro
Serena can reduce token usage and shorten response time and also improve code quality.👍 It is easy and free to use Serena, so why don't you give it a try.
I hope you learned something from this post.😊
Thank you for reading.
Happy AI coding!🤖
Top comments (0)