CLAUDE.md Management
Relevant source files
The following files were used as context for generating this wiki page:
CLAUDE.md Management in opcode provides a dedicated suite of tools for editing and organizing "system prompts" and project-specific guidelines used by Claude Code. This system allows developers to maintain consistent AI behaviors across different environments by managing global system prompts (located in the user's home directory) and local configuration files within individual project directories.
The feature includes a built-in Markdown editor with live preview, a project scanner to locate existing configuration files, and seamless integration with the Rust-based backend for secure file operations. Sources: README.md:104-108, src/lib/api.ts:251-260
Architecture and Components
The CLAUDE.md management system follows a client-server architecture where the React frontend utilizes specialized editor components to interact with the Rust backend via a type-safe API layer.
System Components
| Component | Description |
|---|---|
MarkdownEditor | Handles the editing of the global system prompt located at ~/.claude/CLAUDE.md. |
ClaudeFileEditor | Manages project-specific CLAUDE.md files found within scanned project directories. |
API Layer | Orchestrates asynchronous calls between the UI and Tauri commands for file I/O. |
Rust Backend | Executes filesystem operations, including recursive directory scanning and file writing. |
Sources: src/components/MarkdownEditor.tsx:23-28, src/components/ClaudeFileEditor.tsx:32-37, src-tauri/src/commands/claude.rs:608-615
Data Flow for File Operations
The following sequence diagram illustrates the process of loading and saving a global CLAUDE.md file:
Project Scanner and File Discovery
Opcode includes a specialized scanner to identify project-specific configuration files. This is essential because while the global prompt defines general behavior, individual projects often require specific coding standards or context provided in local CLAUDE.md files.
File Metadata Structure
The system tracks files using the ClaudeMdFile interface:
export interface ClaudeMdFile {
relative_path: string; // Path from project root
absolute_path: string; // Full OS path
size: number; // Bytes
modified: number; // Unix timestamp
}
Sources: src/lib/api.ts:109-118
Recursive Search Logic
The backend implements a recursive search function find_claude_md_recursive that traverses the project directory while ignoring common noise directories like node_modules, .git, dist, and build to ensure performance and relevance. Sources: src-tauri/src/commands/claude.rs:618-653
Editor Implementation
The management system uses @uiw/react-md-editor to provide a robust editing experience with syntax highlighting and a "live" feel.
Editor Features
- Live Preview: Content is rendered in real-time as the user types. Sources: README.md:106
- Unsaved Changes Protection: The
ClaudeFileEditorcomponent includes logic to prevent accidental data loss by checking if thecontentstate differs from theoriginalContentstate before allowing navigation. Sources: src/components/ClaudeFileEditor.tsx:75-81 - Error Feedback: Both global and local editors utilize motion-animated error containers to display filesystem permission issues or I/O failures. Sources: src/components/MarkdownEditor.tsx:96-105
Global vs. Local Management
| Feature | Global Management (MarkdownEditor) | Local Management (ClaudeFileEditor) |
|---|---|---|
| Storage Path | ~/.claude/CLAUDE.md | Root or subdirectories of the opened project. |
| Discovery | Fixed path via home directory. | Recursive scan of the project folder. |
| API Endpoints | get_system_prompt, save_system_prompt | read_claude_md_file, save_claude_md_file |
| Context | Shared across all Claude sessions. | Specific to the active coding session environment. |
Sources: src/components/MarkdownEditor.tsx:47-73, src/components/ClaudeFileEditor.tsx:46-73, src-tauri/src/commands/claude.rs:514-531, src-tauri/src/commands/claude.rs:669-693
Conclusion
CLAUDE.md Management acts as the "command center" for the developer's interaction with Claude Code. By providing separate interfaces for global system prompts and granular project guidelines, Opcode ensures that AI assistance remains context-aware and strictly adheres to the unique requirements of every codebase. The combination of recursive scanning and a robust Markdown editor allows for easy maintenance of the instructions that drive the AI's autonomous capabilities. Sources: README.md:104-108, src/App.tsx:162-175