Claudian

https://github.com/yishentu/claudian
Admin
Claudian is an Obsidian plugin that embeds AI coding agents like Claude Code, Codex, and Opencode as...
Tokens:35,848
Snippets:496
Trust Score:8.5
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install and Run Development Environment

Source: https://github.com/yishentu/claudian/blob/main/CONTRIBUTING.md

Commands to install project dependencies and start the development server.

```bash
npm install
npm run dev
```

--------------------------------

### Example Plan Document

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/10-plan-mode.md

A sample Markdown document representing a plan for refactoring user authentication.

```markdown
## Plan: Refactor User Authentication

1. Extract auth logic into separate module
2. Add JWT support for stateless auth
3. Update tests to cover new code paths
4. Update documentation

Estimated effort: 2 hours
```

--------------------------------

### Manual Plugin Directory Path

Source: https://github.com/yishentu/claudian/blob/main/README.md

The target directory structure for manual installation of the plugin files.

```text
/path/to/vault/.obsidian/plugins/claudian/
```

--------------------------------

### session.execute

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/04-execution-system.md

Starts an execution turn and returns an event stream.

```APIDOC
## session.execute

### Description
Starts a turn and returns an event stream for the session.

### Parameters
- **request** (ProviderExecutionRequest) - Required - Request object containing input, configuration, toolPolicy, and signal.
```

--------------------------------

### Define Command Template

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/07-skills-and-commands.md

Example of a command template using variable substitution for user input and context.

```markdown
# Original command template
/code-review
---
Please review the following code for bugs and improvements:

{selectedText}

Focus on:
- Correctness
- Performance
- Readability
```

--------------------------------

### Configure MCP Servers in TOML

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/06-mcp-system.md

Example configuration for MCP servers using the standard MCP format and Claudian-specific metadata.

```toml
[mcpServers."filesystem"]
command = "npx"
args = ["@modelcontextprotocol/server-filesystem", "/tmp"]

[_claudian.servers."filesystem"]
enabled = true
contextSaving = true
description = "File system access"
disabledTools = []
```

--------------------------------

### Implement User Question Interaction

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/14-permission-system.md

Example of constructing a question request and retrieving the user's answer.

```typescript
const questions: AskUserQuestionItem[] = [
  {
    question: 'Which authentication method should we use?',
    header: 'Auth Method',
    options: [
      { label: 'OAuth', description: 'OAuth 2.0 flow' },
      { label: 'JWT', description: 'JSON Web Tokens' },
      { label: 'Basic Auth', description: 'Username/password' },
    ],
    multiSelect: false,
  },
];

const request: ProviderQuestionInteractionRequest = {
  executionId: 'exec-123',
  questions,
  signal: abortSignal,
};

const response = await interactionPort.askQuestion(request);
const answer = response.answers['Which authentication method should we use?'];
// answer = 'OAuth' | 'JWT' | 'Basic Auth'
```

--------------------------------

### Accessing Plugin and App Instances

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/12-plugin-host.md

Examples of accessing core Obsidian plugin and application properties via the host.

```typescript
const manifest = plugin.manifest;
const root = plugin.mainWorkspaceLeaf;
```

```typescript
const workspace = app.workspace;
const vault = app.vault;
```

--------------------------------

### Stdio Server Configuration

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/06-mcp-system.md

Defines the interface and TOML example for configuring a local stdio-based MCP server.

```typescript
interface McpStdioServerConfig {
  type?: 'stdio';
  command: string;
  args?: string[];
  env?: Record<string, string>;
}
```

```toml
[mcpServers.filesystem]
command = "npx"
args = ["@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
```

--------------------------------

### Example Skill Frontmatter

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/07-skills-and-commands.md

Shows the YAML frontmatter structure used in vault notes to define a skill.

```markdown
---
name: Code Review
description: Review code changes for bugs and improvements
tools:
  - bash
  - read
  - write
model: claude-opus-4-8
---

You are an expert code reviewer. Analyze the provided code for:
...
```

--------------------------------

### HTTP Server Configuration

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/06-mcp-system.md

Defines the interface and TOML example for configuring an HTTP-based MCP server.

```typescript
interface McpHttpServerConfig {
  type: 'http';
  url: string;
  headers?: Record<string, string>;
}
```

```toml
[mcpServers.local-api]
type = "http"
url = "http://localhost:3000"
```

--------------------------------

### SSE Server Configuration

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/06-mcp-system.md

Defines the interface and TOML example for configuring an SSE-based MCP server.

```typescript
interface McpSSEServerConfig {
  type: 'sse';
  url: string;
  headers?: Record<string, string>;
}
```

```toml
[mcpServers.remote]
type = "sse"
url = "https://example.com/mcp"

[mcpServers.remote.headers]
Authorization = "Bearer token"
```

--------------------------------

### Configure device-specific CLI paths

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/13-environment-variables.md

Defines host-specific CLI installation paths using a mapping of hostnames to file paths.

```typescript
interface HostnameCliPaths {
  [hostname: string]: string;
}

// Example in Claude settings
{
  "hostScopedFields": ["cliPath"],
  "cliPaths": {
    "my-macbook": "/Users/me/.volta/bin/claude",
    "my-linux-vm": "/home/me/.cargo/bin/claude",
    "my-windows": "C:\\Users\\me\\AppData\\Local\\Claude\\claude.exe",
  }
}
```

--------------------------------

### Manage Credentials via macOS Keychain

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/13-environment-variables.md

Example workflow for storing and retrieving API keys using the macOS security command-line tool before launching the application.

```bash
# Store API key in keychain
security add-generic-password -a claudian -s anthropic-api-key -w "sk-ant-..."

# Retrieve in shell startup
export ANTHROPIC_API_KEY=$(security find-generic-password -a claudian -s anthropic-api-key -w)

# Launch Obsidian
open -a Obsidian
```

--------------------------------

### Get Current Settings

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/12-plugin-host.md

Retrieves the current plugin settings from the coordinator.

```typescript
const settings = await host.settings.coordinator.loadSettings();
console.log(settings.model, settings.permissionMode);
```

--------------------------------

### TypeScript Interface Definition Example

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/README.md

Standard format for defining types within the documentation.

```typescript
interface ExampleType {
  field: string;
}
```

--------------------------------

### Verify CLI and Node.js installation paths

Source: https://github.com/yishentu/claudian/blob/main/README.md

Use these commands to check if the Claude CLI and Node.js are located in the same directory, which is necessary for proper plugin operation.

```bash
dirname $(which claude)
dirname $(which node)
```

--------------------------------

### Consume ProviderExecutionRun events

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/04-execution-system.md

Example of iterating over execution events to handle UI updates and tool calls.

```typescript
const session = backend.createSession(config);
const run = session.execute(request);

for await (const event of run.events) {
  if (event.type === 'text_delta') {
    updateUI(event.text);
  } else if (event.type === 'tool_started') {
    logToolCall(event.name, event.input);
  } else if (event.type === 'turn_completed') {
    break;
  }
}
```

--------------------------------

### Define Environment Variable Format

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/13-environment-variables.md

Standard format for multi-line environment variable files where lines starting with # are treated as comments.

```text
KEY1=value1
KEY2=value2
KEY3=value with spaces and special chars
```

--------------------------------

### Custom Model Registration

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/08-claude-provider.md

Example of how to register custom model options within the Claude provider configuration.

```typescript
// In src/providers/claude/modelOptions.ts
export const CUSTOM_MODELS: Record<string, ClaudeModelOption> = {
  'custom-claude-opus': {
    id: 'custom-claude-opus',
    name: 'Custom Opus Variant',
    tier: 'opus',
    contextWindow: 100000,
  },
};
```

--------------------------------

### initializeAll(plugin: ProviderHost): Promise<void>

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/03-provider-registry.md

Initializes all registered providers at plugin startup.

```APIDOC
## initializeAll(plugin: ProviderHost): Promise<void>

### Description
Initialize all registered providers at plugin startup.

### Parameters
- **plugin** (ProviderHost) - Required - Plugin host context.
```

--------------------------------

### Clone and Build from Source

Source: https://github.com/yishentu/claudian/blob/main/README.md

Commands to clone the repository and build the plugin from source code.

```bash
cd /path/to/vault/.obsidian/plugins
git clone https://github.com/YishenTu/claudian.git
cd claudian
```

```bash
npm install
npm run build
```

--------------------------------

### Run Verification Suite

Source: https://github.com/yishentu/claudian/blob/main/CONTRIBUTING.md

Commands to perform type checking, linting, testing, and building the project before submission.

```bash
npm run typecheck
npm run lint
npm run test
npm run build
```

--------------------------------

### host.settings.coordinator.loadSettings()

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/12-plugin-host.md

Retrieves the current plugin settings.

```APIDOC
## host.settings.coordinator.loadSettings()

### Description
Loads the current configuration settings for the plugin.

### Returns
- **settings** (Object) - The current settings object containing model and permissionMode.
```

--------------------------------

### Plugin Lifecycle Management

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/12-plugin-host.md

Demonstrates initializing and disposing of the ProviderHost within a plugin class.

```typescript
class ClaudianPlugin extends Plugin {
  host: ProviderHost;
  
  async onload() {
    this.host = createProviderHost(this);
    // Initialize features, register commands, etc.
  }
  
  async onunload() {
    await this.host.workspace.disposeInitialized();
    // Cleanup
  }
}
```

--------------------------------

### Development Build Commands

Source: https://github.com/yishentu/claudian/blob/main/README.md

Commands for running the plugin in watch mode or creating a production build.

```bash
# Watch mode
npm run dev

# Production build
npm run build
```

--------------------------------

### Development Lifecycle Commands

Source: https://github.com/yishentu/claudian/blob/main/AGENTS.md

Standard npm scripts for building, testing, and maintaining code quality in the project.

```bash
npm run dev
npm run build
npm run typecheck
npm run lint
npm run lint:fix
npm run test
npm run test:watch
npm run test:coverage
```

--------------------------------

### host.workspace.ensureInitialized(host, provider, context)

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/12-plugin-host.md

Ensures the workspace services for a specific provider are initialized.

```APIDOC
## host.workspace.ensureInitialized(host, provider, context)

### Description
Initializes workspace services for the given provider and context.
```

--------------------------------

### Create Execution Backend

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/12-plugin-host.md

Initializes a backend session for a specific provider.

```typescript
const backend = host.execution.getBackend('claude');
const session = backend.createSession(config);
```

--------------------------------

### ProviderExecutionBackend.createSession

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/04-execution-system.md

Initializes a new provider execution session using the provided configuration.

```APIDOC
## ProviderExecutionBackend.createSession

### Description
Creates a new session instance for provider execution.

### Method
Method call on ProviderExecutionBackend interface

### Parameters
- **config** (ProviderSessionConfig) - Required - Configuration object containing sessionInstanceId, interactionPort, and signal.
```

--------------------------------

### Handle Tool Approval Requests

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/14-permission-system.md

Demonstrates how to process a tool approval request and handle the resulting decision using a switch statement.

```typescript
const request: ProviderApprovalInteractionRequest = {
  executionId: 'exec-123',
  toolName: 'bash',
  input: {
    command: 'rm -rf /',  // Dangerous command
  },
  signal: abortSignal,
};

const response = await interactionPort.askApproval(request);

switch (response.decision) {
  case 'allow':
    // Execute this tool once
    executeToolNow();
    break;
  case 'allow-always':
    // Execute this tool and never ask again for 'bash'
    executeToolNow();
    persistAllowRule('bash');
    break;
  case 'deny':
    // Block this tool invocation
    cancelTool();
    break;
  case 'cancel':
    // Cancel entire execution
    session.cancel();
    break;
}
```

--------------------------------

### Initialize Execution Backend and Session

Source: https://github.com/yishentu/claudian/blob/main/src/core/AGENTS.md

Pattern for creating an execution backend and processing events from a session.

```typescript
const backend = ProviderRegistry.createExecutionBackend(plugin, providerId);
const session = backend.createSession(sessionConfig);
const run = session.execute(request);

for await (const event of run.events) {
  // Feature layer consumes provider-neutral execution events.
}
```

--------------------------------

### host.settings.subscribe(callback)

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/12-plugin-host.md

Registers a listener for settings changes.

```APIDOC
## host.settings.subscribe(callback)

### Description
Subscribes to changes in settings. Returns an unsubscribe function.

### Parameters
- **callback** (Function) - Function to execute when settings change.
```

--------------------------------

### Define a Skill via Markdown

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/07-skills-and-commands.md

Create a new skill by placing a markdown file with frontmatter in the .agents/skills/ directory.

```markdown
---
name: Typescript Type Checker
description: Check TypeScript for type errors
tools:
  - bash
model: claude-opus-4-8
---

You are a TypeScript type-checking expert. Analyze the provided code and:

1. Identify type errors
2. Suggest fixes
3. Explain why each error is incorrect
```

--------------------------------

### List core source code file paths

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/README.md

Displays the canonical file paths for the provider registry and Claude execution backend within the repository.

```text
src/core/providers/ProviderRegistry.ts
src/providers/claude/execution/ClaudeExecutionBackend.ts
```

--------------------------------

### Construct Plan Refinement Request

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/10-plan-mode.md

Format the provider execution request to include user feedback and existing plan context.

```typescript
const refinementRequest: ProviderExecutionRequest = {
  input: [
    { type: 'text', text: `User feedback on plan:\n${feedbackText}` },
  ],
  conversationHistory: [
    // Include plan in history
    { role: 'assistant', content: planContent, currentNote: null },
  ],
  // ...
};
```

--------------------------------

### Register a New Provider

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/03-provider-registry.md

Demonstrates the structure of a ProviderRegistration object and how to register it with the ProviderRegistry.

```typescript
// In src/providers/myprovider/registration.ts
import { ProviderRegistry } from '@/core/providers/ProviderRegistry';
import type { ProviderRegistration } from '@/core/providers/types';

const registration: ProviderRegistration = {
  displayName: 'My Provider',
  blankTabOrder: 99,
  isEnabled: (settings) => settings.myProviderEnabled === true,
  capabilities: {
    providerId: 'myprovider',
    supportsNativeHistory: true,
    supportsPlanMode: true,
    supportsRewind: true,
    supportsFork: true,
    supportsProviderCommands: true,
    supportsImageAttachments: true,
    supportsInstructionMode: true,
    supportsMcpTools: true,
    reasoningControl: 'effort',
  },
  chatUIConfig: {
    modelPicker: createMyProviderModelPicker(),
    settings: MyProviderSettingsTab,
  },
  settingsReconciler: {
    invalidateConversationSessions: (conversations) => conversations,
    reconcileModelWithEnvironment: (settings, conversations) => ({
      changed: false,
      invalidatedConversations: [],
    }),
    normalizeModelVariantSettings: (settings) => false,
  },
  createExecutionBackend: (plugin) => new MyProviderExecutionBackend(plugin),
  historyService: {
    loadConversations: async (plugin) => [],
    saveConversation: async (plugin, conversation) => {},
  },
  taskResultInterpreter: {
    interpretToolResult: (toolName, result, plugin) => result,
  },
};

// Register at startup (in src/providers/index.ts)
ProviderRegistry.register('myprovider', registration);
```

--------------------------------

### Full Verification Command

Source: https://github.com/yishentu/claudian/blob/main/AGENTS.md

The default command sequence for performing a comprehensive check of the codebase.

```bash
npm run typecheck && npm run lint && npm run test && npm run build
```

--------------------------------

### InlinePlanApproval

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/10-plan-mode.md

UI component class for presenting plan content and collecting user decisions.

```APIDOC
## InlinePlanApproval

### Description
UI component that renders plan content as markdown and provides interactive elements for user decisions.

### Methods
- **present(planContent: string, options?: ExitPlanModePresentationOptions): Promise<ExitPlanModeDecision | null>**
  - Displays the plan content and waits for user interaction.
- **dismiss(reason?: string): void**
  - Dismisses the plan approval UI.
```

--------------------------------

### Instruction Refinement Workflow

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/15-chat-view-ui.md

Demonstrates the process of refining user instructions before sending them to the controller.

```typescript
const mode = 'instruction';
// User types initial instruction
const userText = 'Review this code';

// Press Shift+Tab to enter refinement
const refined = await refinementService.refine(userText);
// Agent suggests improvements to the instruction
// User approves or edits

// Send refined instruction
controller.sendMessage(refined);
```

--------------------------------

### interactionPort.askApproval

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/14-permission-system.md

Requests approval from the user for a specific tool execution. The response determines whether the tool is allowed, allowed permanently, denied, or if the entire session should be cancelled.

```APIDOC
## askApproval

### Description
Requests user approval for a tool execution. The caller must handle the decision returned by the user.

### Request Parameters
- **executionId** (string) - The ID of the current execution.
- **toolName** (string) - The name of the tool being requested.
- **input** (object) - The input parameters for the tool.
- **signal** (AbortSignal) - Signal to abort the request.

### Response
- **decision** ('allow' | 'allow-always' | 'deny' | 'cancel') - The user's decision regarding the tool execution.
```

--------------------------------

### Invoke Context-Saving Tools

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/06-mcp-system.md

Syntax for invoking tools from a server configured with context-saving enabled.

```text
@filesystem list /tmp
```

--------------------------------

### Configure ProviderExecutionRequest with Tool Policy

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/04-execution-system.md

Demonstrates how to specify a tool policy within an execution request to restrict available tools.

```typescript
const request: ProviderExecutionRequest = {
  input: [{ type: 'text', text: 'Read src/main.ts' }],
  configuration: { systemInstructions: { kind: 'provider-default' } },
  toolPolicy: { kind: 'allow-list', names: ['bash', 'read'] },
  signal: abortSignal,
};
```

--------------------------------

### Implement Provider Capabilities

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/10-plan-mode.md

Configures the provider capabilities object to enable plan mode support and define the storage prefix.

```typescript
const capabilities: ProviderCapabilities = {
  providerId: 'claude',
  supportsPlanMode: true,
  planPathPrefix: '.plans/',
  // ...
};
```

--------------------------------

### Mocking ProviderHost for Testing

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/00-index.md

Use a partial implementation of ProviderHost to mock storage and settings dependencies during feature testing.

```typescript
const mockHost: Partial<ProviderHost> = {
  storage: { vault: mockVaultAdapter, ... },
  settings: { coordinator: mockCoordinator, ... },
};
```

--------------------------------

### ensureInitialized(plugin: ProviderHost, providerId: ProviderId, reason: string): Promise<void>

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/03-provider-registry.md

Lazy-initializes a specific provider when first needed.

```APIDOC
## ensureInitialized(plugin: ProviderHost, providerId: ProviderId, reason: string): Promise<void>

### Description
Lazy-initialize a specific provider when first needed.

### Parameters
- **plugin** (ProviderHost) - Required - Plugin host context.
- **providerId** (ProviderId) - Required - Provider to initialize.
- **reason** (string) - Required - Reason for initialization (for logging).
```

--------------------------------

### host.execution.getBackend(name)

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/12-plugin-host.md

Retrieves an execution backend by name.

```APIDOC
## host.execution.getBackend(name)

### Description
Gets an execution backend instance to manage sessions.

### Parameters
- **name** (string) - The identifier of the backend (e.g., 'claude').
```

--------------------------------

### getRuntimeEnvironmentText

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/13-environment-variables.md

Formats all applicable environment variables for a provider as shell export commands.

```APIDOC
## getRuntimeEnvironmentText(providerId, settings)

### Description
Formats all applicable environment variables for a provider as shell export commands.

### Parameters
- **providerId** (ProviderId) - Required - The ID of the provider.
- **settings** (Record<string, unknown>) - Required - Configuration settings.

### Returns
- **string** - A string containing shell export commands.
```

--------------------------------

### Access Provider Workspace Services

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/12-plugin-host.md

Ensures workspace initialization and retrieves the command catalog for a provider.

```typescript
await host.workspace.ensureInitialized(host, 'claude', 'chat-startup');
const commands = host.workspace.getIfInitialized('claude')?.commandCatalog;
if (commands) {
  const available = await commands.getAvailableCommands(settings);
}
```

--------------------------------

### HomeFileAdapter Interface

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/05-storage-system.md

Defines the contract for file operations within the user's home directory, used for provider configurations and session files.

```typescript
interface HomeFileAdapter {
  exists(path: string): Promise<boolean>;
  read(path: string): Promise<string>;
  write(path: string, content: string): Promise<void>;
  readBinary(path: string): Promise<ArrayBuffer>;
  writeBinary(path: string, data: ArrayBuffer): Promise<void>;
  listDirectoryRecursive(basePath: string): Promise<string[]>;
  mkdir(path: string): Promise<void>;
  delete(path: string): Promise<void>;
}
```

--------------------------------

### Execute Rewind Operation

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/11-rewind-fork.md

Demonstrates the process of previewing rewind conflicts and executing a rewind in replay mode.

```typescript
// User clicks rewind on message 'msg-10'
const targetMessageId = 'msg-10';

// Get preview
const preview = await session.getRewindPreview(targetMessageId);
if (preview.conflicts?.length) {
  // Show warnings to user
  showRewindConflicts(preview.conflicts);
}

// User confirms rewind in 'replay' mode
const result = await session.rewind(targetMessageId, 'replay');

if (result.success) {
  // Update conversation state
  conversation.messages = result.replayedMessages;
  conversation.resumeAtMessageId = targetMessageId;
  await saveConversation(conversation);
  
  // Refresh UI
  rerenderMessages();
}
```

--------------------------------

### Manage environment variable snippets

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/13-environment-variables.md

Creates and commits reusable environment variable templates to the settings configuration.

```typescript
const snippet: EnvSnippet = {
  id: 'openrouter-setup',
  name: 'OpenRouter Setup',
  description: 'Anthropic API via OpenRouter proxy',
  scope: 'shared',
  envVars: `ANTHROPIC_API_KEY=sk-or-...
ANTHROPIC_API_URL=https://openrouter.ai/api/v1`,
};

settings.envSnippets.push(snippet);
await settings.coordinator.commit({ kind: 'update', partial: { envSnippets: settings.envSnippets } });
```

--------------------------------

### Define Plan Storage Path

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/10-plan-mode.md

Defines the directory prefix and specific file path for storing plan documents in Markdown format.

```typescript
const planPathPrefix = capabilities.planPathPrefix;  // '.plans/' for Claude

const planPath = `.plans/${conversationId}/${turnId}.md`;
```

--------------------------------

### Define ClaudianSettings and EnvSnippet interfaces

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/13-environment-variables.md

Structures for storing global environment variables, snippets, and model-specific configurations.

```typescript
interface ClaudianSettings {
  // Global environment variables (env var format: KEY=VALUE)
  sharedEnvironmentVariables: string;
  
  // Saved snippets (named templates with optional per-provider scope)
  envSnippets: EnvSnippet[];
  
  // Custom context limits per model
  customContextLimits: Record<string, number>;
  
  // Custom display aliases for models
  customModelAliases: Record<string, string>;
}

interface EnvSnippet {
  id: string;
  name: string;
  description: string;
  envVars: string;  // Multi-line env var format
  scope?: EnvironmentScope;
  contextLimits?: Record<string, number>;
  modelAliases?: Record<string, string>;
}
```

--------------------------------

### Check Plan Mode Availability

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/10-plan-mode.md

Verify if Plan Mode is supported by capabilities and enabled in settings.

```typescript
const isPlanModeAvailable = 
  capabilities.supportsPlanMode && 
  settings.permissionMode === 'plan';
```

--------------------------------

### Define Provider Command Interfaces

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/07-skills-and-commands.md

Interfaces for cataloging and discovering commands provided by external sources.

```typescript
interface ProviderCommandCatalog {
  getAvailableCommands(settings: Record<string, unknown>): Promise<SlashCommand[]>;
  resolveCommand(name: string): Promise<SlashCommand | null>;
}

interface ProviderCommandDiscoveryResult {
  commands: SlashCommand[];
  discoveredAt: number;
  fingerprint: string;
}
```

--------------------------------

### getIfInitialized(providerId: ProviderId): ProviderWorkspaceServices | null

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/03-provider-registry.md

Synchronously accesses services only if already initialized.

```APIDOC
## getIfInitialized(providerId: ProviderId): ProviderWorkspaceServices | null

### Description
Synchronously access services only if already initialized. Returns null if provider not yet initialized.

### Parameters
- **providerId** (ProviderId) - Required - Provider to access.
```

--------------------------------

### host.mcp.testConnection(server)

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/12-plugin-host.md

Tests the connection to an MCP server.

```APIDOC
## host.mcp.testConnection(server)

### Description
Tests the connection to a managed MCP server.

### Parameters
- **server** (ManagedMcpServer) - The server configuration to test.
```

--------------------------------

### Project Directory Structure

Source: https://github.com/yishentu/claudian/blob/main/README.md

Visual representation of the source code organization and module responsibilities.

```text
src/
├── main.ts                      # Plugin entry point
├── app/                         # Shared defaults and plugin-level storage
├── core/                        # Provider-neutral runtime, registry, and type contracts
│   ├── runtime/                 # ChatRuntime interface and approval types
│   ├── providers/               # Provider registry and workspace services
│   ├── auxiliary/               # Shared provider auxiliary services
│   ├── bootstrap/               # Plugin bootstrap wiring
│   ├── security/                # Approval utilities
│   └── ...                      # commands, mcp, prompt, storage, tools, types
├── providers/
│   ├── claude/                  # Claude SDK adaptor, prompt encoding, storage, MCP, plugins
│   ├── codex/                   # Codex app-server adaptor, JSON-RPC transport, JSONL history
│   ├── grok/                    # Grok Build ACP adaptor, native history, models, and tools
│   ├── opencode/                # Opencode adaptor
│   ├── pi/                      # Pi RPC adaptor, model discovery, JSONL history
│   └── acp/                     # Agent Client Protocol shared transport
├── features/
│   ├── chat/                    # Sidebar chat: tabs, controllers, renderers
│   ├── inline-edit/             # Inline edit modal and provider-backed edit services
│   └── settings/                # Settings shell with provider tabs
├── shared/                      # Reusable UI components and modals
├── i18n/                        # Internationalization (10 locales)
├── types/                       # Shared ambient types
├── utils/                       # Cross-cutting utilities
└── style/                       # Modular CSS
```

--------------------------------

### Define ProviderExecutionBackend Interface

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/04-execution-system.md

Defines the contract for creating execution sessions and the configuration required for session initialization.

```typescript
interface ProviderExecutionBackend {
  createSession(config: ProviderSessionConfig): ProviderExecutionSession;
}

interface ProviderSessionConfig {
  sessionId?: string;
  sessionInstanceId: string;
  interactionPort: ProviderInteractionPort;
  signal: AbortSignal;
  resumeSeed?: ProviderNativeResumeSeed;
}
```

--------------------------------

### Mirroring Source Structure in Tests

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/00-index.md

Maintain a consistent directory structure between source files and their corresponding test files.

```text
src/core/providers/ProviderRegistry.ts
tests/unit/core/providers/ProviderRegistry.test.ts
```

--------------------------------

### Implement ProviderSettingsStorageAdapter

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/05-storage-system.md

Interface for providers to define how their settings are stored, migrated, and normalized.

```typescript
interface ProviderSettingsStorageAdapter {
  hostScopedFields?: string[];
  legacyTopLevelFields?: string[];
  runtimeOnlyFields?: string[];
  normalizeStored(
    target: Record<string, unknown>,
    stored: Record<string, unknown>,
  ): boolean;
}
```

--------------------------------

### Define Dependency Rules

Source: https://github.com/yishentu/claudian/blob/main/src/core/AGENTS.md

Visual representation of the module dependency hierarchy.

```text
types/ <- all modules
storage/ <- bootstrap/, provider workspace services
execution/ + providers/ <- provider implementations
features/ -> core contracts only
```

--------------------------------

### Accessing Provider Workspace Services

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/12-plugin-host.md

Lazy-initialization and access patterns for provider-specific workspace services.

```typescript
const catalog = workspace.getIfInitialized(providerId)?.commandCatalog;
const agents = workspace.getIfInitialized(providerId)?.agentMentionProvider;
```

--------------------------------

### register(providerId: ProviderId, registration: ProviderWorkspaceRegistration): void

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/03-provider-registry.md

Registers a provider's workspace services into the registry.

```APIDOC
## register(providerId: ProviderId, registration: ProviderWorkspaceRegistration): void

### Description
Registers a provider's workspace services.

### Parameters
- **providerId** (ProviderId) - Required - The identifier for the provider.
- **registration** (ProviderWorkspaceRegistration) - Required - The workspace services registration object.
```

--------------------------------

### host.storage.vault.read(path)

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/12-plugin-host.md

Reads a file from the vault.

```APIDOC
## host.storage.vault.read(path)

### Description
Reads the content of a file located in the vault.

### Parameters
- **path** (string) - The file path to read.
```

--------------------------------

### Configure keyboard navigation settings

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/15-chat-view-ui.md

Defines the key bindings for scrolling and input focus within the chat interface.

```typescript
interface KeyboardNavigationSettings {
  scrollUpKey: string;     // 'w' default
  scrollDownKey: string;   // 's' default
  focusInputKey: string;   // 'i' default
}
```

--------------------------------

### interactionPort.askQuestion

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/14-permission-system.md

Presents a set of questions to the user and collects their answers. Supports single or multi-select options and secret inputs.

```APIDOC
## askQuestion

### Description
Prompts the user with a list of questions and returns their provided answers.

### Request Parameters
- **executionId** (string) - The ID of the current execution.
- **questions** (Array<AskUserQuestionItem>) - List of questions to present.
- **signal** (AbortSignal) - Signal to abort the request.

### Response
- **answers** (AskUserAnswers) - Map of question identifiers to user responses.
- **error** (string, optional) - Error message if the interaction failed.
```

--------------------------------

### SharedAppStorage Interface

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/12-plugin-host.md

Interface for file adapters and conversation repository access.

```typescript
interface SharedAppStorage {
  vault: VaultFileAdapter;
  home: HomeFileAdapter;
  conversationRepository: ConversationRepository;
  loadSessionMetadata(options?): Promise<SessionMetadataScanResult>;
}
```

--------------------------------

### Resolve Workspace Services

Source: https://github.com/yishentu/claudian/blob/main/src/core/AGENTS.md

Retrieving registry services for commands, agent mentions, and CLI resolution.

```typescript
const catalog = ProviderWorkspaceRegistry.getCommandCatalog(providerId);
const agentMentions = ProviderWorkspaceRegistry.getAgentMentionProvider(providerId);
const cliResolver = ProviderWorkspaceRegistry.getCliResolver(providerId);
```

--------------------------------

### disposeInitialized(): Promise<void>

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/03-provider-registry.md

Cleans up all initialized provider services at plugin unload.

```APIDOC
## disposeInitialized(): Promise<void>

### Description
Clean up all initialized provider services at plugin unload.
```

--------------------------------

### McpTester Interface

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/06-mcp-system.md

Provides utilities for testing MCP server connectivity and discovering available tools and resources.

```typescript
interface McpTester {
  testServer(config: ManagedMcpServer): Promise<{
    success: boolean;
    error?: string;
    toolCount?: number;
    resourceCount?: number;
  }>;
  discoverTools(config: ManagedMcpServer): Promise<Tool[]>;
  discoverResources(config: ManagedMcpServer): Promise<Resource[]>;
}
```

--------------------------------

### Handle Plan Approval Interaction

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/10-plan-mode.md

Process user decisions regarding plan approval, feedback, or session abandonment using the interaction port.

```typescript
const { exitPlanModeCallback } = interactionPort;

const planContent = /* agent-generated plan string */;

const decision = await exitPlanModeCallback(
  { planContent },
  abortSignal,
  {
    allowAbandon: true,
    allowNewSession: true,
    approveLabel: 'Implement Plan',
    feedbackLabel: 'Refine Plan',
  },
);

if (!decision) {
  // User dismissed or aborted
  session.cancel();
  return;
}

switch (decision.type) {
  case 'approve':
    // Continue implementation with current session
    break;
  case 'feedback':
    // Send feedback back to provider
    const feedbackRequest: ProviderExecutionRequest = {
      // ... constructed from feedback
    };
    // Execute refinement request
    break;
  case 'approve-new-session':
    // Save plan, dispose current session, start new one
    await saveConversationCheckpoint(decision.planContent);
    await session.dispose();
    session = backend.createSession(config);
    break;
  case 'abandon':
    // Discard plan and start over
    session.cancel();
    break;
}
```

--------------------------------

### Define SharedAppStorage Interface

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/05-storage-system.md

Root storage contract for plugin-level state, providing access to file adapters and settings I/O.

```typescript
interface SharedAppStorage {
  vault: VaultFileAdapter;
  home: HomeFileAdapter;
  
  loadSettings(): Promise<Record<string, unknown>>;
  saveSettings(settings: Record<string, unknown>): Promise<void>;
  
  loadSessionMetadata(options?: SessionMetadataListOptions): Promise<SessionMetadataScanResult>;
  
  conversationRepository: ConversationRepository;
}
```

--------------------------------

### Create and execute a Claude request

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/08-claude-provider.md

Defines a ProviderExecutionRequest with input, context, and model configuration, then executes it via a session and iterates over events.

```typescript
const request: ProviderExecutionRequest = {
  input: [
    { type: 'text', text: 'Review this code for bugs' },
    { type: 'text', text: 'function add(a, b) { return a + b; }' },
  ],
  context: {
    currentNote: {
      path: 'src/main.ts',
      content: '...',
    },
  },
  configuration: {
    systemInstructions: {
      kind: 'explicit',
      instructions: 'You are a code reviewer.',
    },
    model: 'claude-opus-4-8',
    reasoning: '5000',  // Extended thinking token budget
    serviceTier: 'pro',
    enabledMcpServers: ['filesystem'],
  },
  toolPolicy: { kind: 'unrestricted' },
  signal: abortSignal,
};

const session = backend.createSession(sessionConfig);
const run = session.execute(request);

for await (const event of run.events) {
  if (event.type === 'text_delta') {
    console.log(event.text);
  }
}
```

--------------------------------

### plugin.settings.coordinator.commit(operation)

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/05-storage-system.md

Commits changes to the plugin settings. Supports replacing the entire settings object.

```APIDOC
## plugin.settings.coordinator.commit(operation)

### Description
Updates the plugin settings by committing a mutation operation.

### Parameters
- **operation** (object) - Required - The mutation operation to perform.
  - **kind** (string) - Required - The type of operation (e.g., "replace").
  - **settings** (object) - Required - The settings object to be saved.
```

--------------------------------

### File Context Interface

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/15-chat-view-ui.md

Defines the structure for files attached to chat inputs, including path, content, selection state, and order.

```typescript
interface FileContext {
  path: string;
  content?: string;  // Only if small enough
  isSelected: boolean;
  order: number;
}
```

--------------------------------

### Test and Save an MCP Server

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/06-mcp-system.md

Validates server connectivity before adding it to the persistent configuration list.

```typescript
const server: ManagedMcpServer = {
  name: 'my-api',
  config: {
    type: 'http',
    url: 'http://localhost:3000',
  },
  enabled: true,
  contextSaving: false,
  description: 'My local API',
};

// Test connectivity
const testResult = await mcpManager.testConnection(server);
if (!testResult.success) {
  throw new Error(`Server test failed: ${testResult.error}`);
}

// Save to configuration
const servers = await mcpManager.loadServers();
servers.push(server);
await mcpManager.saveServers(servers);
```

--------------------------------

### ProviderExecutionRun

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/04-execution-system.md

Represents an individual execution within a session, providing access to events and cancellation capabilities.

```APIDOC
## ProviderExecutionRun

### Description
An individual execution within a session. Provides an async iterable of events and a method to cancel the execution.

### Properties
- **executionId** (string) - Unique ID for this execution
- **turnId** (string) - Turn ID shared across requested and background events
- **events** (AsyncIterable<ProviderExecutionEvent>) - Async iterable of execution events

### Methods
- **cancel()** - Cancels the current execution run.
```

--------------------------------

### Create a Skill Programmatically

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/07-skills-and-commands.md

Define an AgentSkill object and persist it using the skillRepository.

```typescript
const skill: AgentSkill = {
  id: 'my-skill',
  name: 'my-skill',
  kind: 'skill',
  content: 'You are a helpful assistant...',
  source: 'vault',
  frontmatter: {
    name: 'My Skill',
    description: 'Does something useful',
    tools: ['bash', 'read'],
  },
};

await skillRepository.saveSkill(skill);
```

--------------------------------

### ProviderRegistry.register

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/03-provider-registry.md

Registers a new provider with the system using a unique identifier and a registration configuration object.

```APIDOC
## ProviderRegistry.register

### Description
Registers a new AI provider into the system registry. This method should be called during application startup to make the provider available for use.

### Signature
`ProviderRegistry.register(id: string, registration: ProviderRegistration)`

### Parameters
- **id** (string) - Required - A unique identifier for the provider.
- **registration** (ProviderRegistration) - Required - The configuration object defining the provider's capabilities, UI settings, and backend implementation.
```

--------------------------------

### InlinePlanApproval UI Component Interface

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/10-plan-mode.md

Interface for the UI component responsible for presenting plans and collecting user decisions.

```typescript
class InlinePlanApproval {
  present(
    planContent: string,
    options?: ExitPlanModePresentationOptions,
  ): Promise<ExitPlanModeDecision | null>;
  
  dismiss(reason?: string): void;
}
```

--------------------------------

### ProviderSettingsStorageAdapter

Source: https://github.com/yishentu/claudian/blob/main/_autodocs/05-storage-system.md

Interface for providers to implement custom settings storage logic and field normalization.

```APIDOC
## ProviderSettingsStorageAdapter

### Description
Interface used by providers to manage their own settings storage and handle data migration.

### Properties
- **hostScopedFields** (string[]) - Optional - Fields stored per-device.
- **legacyTopLevelFields** (string[]) - Optional - Fields migrated from root to provider config.
- **runtimeOnlyFields** (string[]) - Optional - Fields not persisted.

### Methods
- **normalizeStored(target: Record<string, unknown>, stored: Record<string, unknown>)**: boolean - Migrates stored format to the current version.
```
Tokens:
Raw