nexus AGENTS.md

Codex Context Document

Last Updated: 2026-04-04

Project Overview

• Name: Claudesidian MCP
• Version: 5.11.1
• Type: Obsidian Community Plugin
• Purpose: MCP integration for Obsidian with AI-powered vault operations
• Architecture: Agent-Tool pattern with domain-driven design
• Stack: TypeScript, Node.js, Obsidian Plugin API, MCP SDK

Obsidian Plugin Development Guidelines

This is an Obsidian community plugin that must follow official Plugin Guidelines. All code changes must adhere to these best practices.

Plugin Lifecycle

// Plugins extend the Plugin base class
export default class MyPlugin extends Plugin {
    async onload() {
        // Initialize UI, register commands, set up events
        // Use registration methods for auto-cleanup
    }

    async onunload() {
        // Clean up resources (most handled automatically)
    }
}

Key lifecycle rules:

• All registration methods (registerEvent, addCommand, registerView, registerInterval) auto-cleanup on unload
• Never store view references in the plugin instance (causes memory leaks)
• Use this.app.workspace.onLayoutReady() to defer startup operations

Styling - ALL STYLES IN styles.css

CRITICAL: All styles must be defined in styles.css, never inline in TypeScript/JavaScript.

// ❌ NEVER do this
element.style.color = 'white';
element.style.backgroundColor = 'red';
element.style.display = 'flex';

// ✅ ALWAYS do this
element.addClass('my-plugin-element');

/* In styles.css - use CSS variables for theme compatibility */
.my-plugin-element {
    color: var(--text-normal);
    background-color: var(--background-primary);
    display: flex;
}

Required CSS Variables (never hardcode colors):

Variable	Purpose
--text-normal, --text-muted, --text-faint	Text colors
--text-accent	Interactive/link text
--background-primary, --background-secondary	Background colors
--background-modifier-border	Borders
--background-modifier-error	Error states
--interactive-accent, --interactive-accent-hover	Buttons/interactive
--radius-s, --radius-m, --radius-l	Border radius