# How to Use Custom System Prompts and Instruction Mode in Claudian

> Learn to customize Claude's behavior in Claudian using custom system prompts and Instruction Mode. Tailor AI responses for better results.

- Repository: [YishenTu/claudian](https://github.com/YishenTu/claudian)
- Tags: how-to-guide
- Published: 2026-03-17

---

**You can customize Claude's behavior in Claudian by appending static instructions via the settings panel or dynamically adding temporary directives through Instruction Mode triggered by typing `#` in the chat.**

Claudian is an Obsidian plugin that integrates Claude Code into your note-taking workflow. The plugin allows you to modify Claude's underlying system prompt—the hidden instructions that shape every response—using either persistent custom settings or on-the-fly adjustments. Mastering **custom system prompts and Instruction Mode** lets you tailor the AI's personality, output format, and operational constraints to match your specific research or writing needs.

## How System Prompts Work in Claudian

### The Base Prompt Architecture

Every query to Claude begins with a system prompt constructed by the `buildSystemPrompt()` function in **[`src/core/prompts/mainAgent.ts`](https://github.com/YishenTu/claudian/blob/main/src/core/prompts/mainAgent.ts)**. This function assembles a composite instruction set that includes your vault path, username, media handling rules, and export permissions. Crucially, it checks for a `customPrompt` value and appends it under a dedicated header.

```typescript
export function buildSystemPrompt(settings: SystemPromptSettings = {}): string {
  const allowExternalAccess = settings.allowExternalAccess ?? false;
  let prompt = getBaseSystemPrompt(settings.vaultPath, settings.userName, allowExternalAccess);
  prompt += getImageInstructions(settings.mediaFolder || '');
  prompt += getExportInstructions(settings.allowedExportPaths || [], allowExternalAccess);
  if (settings.customPrompt?.trim()) {
    // Custom system prompt is inserted here
    prompt += '\n\n## Custom Instructions\n\n' + settings.customPrompt.trim();

  }
  return prompt;
}

```

*Source:* [mainAgent.ts L48-L61](https://github.com/YishenTu/claudian/blob/main/src/core/prompts/mainAgent.ts#L48-L61)

The `QueryOptionsBuilder` class in **[`src/core/agent/QueryOptionsBuilder.ts`](https://github.com/YishenTu/claudian/blob/main/src/core/agent/QueryOptionsBuilder.ts)** (lines 144-169) invokes this function on every request, passing `ctx.settings.systemPrompt` as the `customPrompt` parameter.

### Settings Storage

The custom prompt setting is defined in **[`src/core/types/settings.ts`](https://github.com/YishenTu/claudian/blob/main/src/core/types/settings.ts)** (lines 260-329) with a default value of an empty string. This value persists in the plugin's [`settings.json`](https://github.com/YishenTu/claudian/blob/main/settings.json) file and survives across Obsidian restarts.

## Method 1: Static Custom Prompts

### Editing via the Settings UI

For permanent behavioral changes, modify the system prompt directly in Claudian's settings panel. The UI implementation in **[`src/features/settings/ClaudianSettings.ts`](https://github.com/YishenTu/claudian/blob/main/src/features/settings/ClaudianSettings.ts)** (lines 170-178) provides a textarea bound to `plugin.settings.systemPrompt`:

```typescript
new Setting(containerEl)
  .setName(t('settings.systemPrompt.name'))
  .setDesc(t('settings.systemPrompt.desc'))
  .addTextArea(text => text
    .setPlaceholder(t('settings.systemPrompt.name'))
    .setValue(this.plugin.settings.systemPrompt)
    .onChange(async (value) => {
      this.plugin.settings.systemPrompt = value;
      await this.plugin.saveSettings();
    }));

```

Any markdown entered here is stored verbatim and appended to the base prompt on subsequent queries.

### Programmatic Updates

You can also update the system prompt from other plugins or scripts by accessing the Claudian plugin instance directly:

```typescript
// Assuming you have a reference to the Claudian plugin instance
const safetyRule = `\n- Never delete files unless the user explicitly confirms.\n`;
claudian.settings.systemPrompt += safetyRule;
await claudian.saveSettings();
// Changes take effect on the next query

```

## Method 2: Using Instruction Mode

Instruction Mode provides a chat-based interface for incrementally adding to your custom system prompt without opening the settings panel.

### Triggering Instruction Mode

When you type `#` in an empty chat input, the `InstructionModeManager` in **[`src/features/chat/ui/InstructionModeManager.ts`](https://github.com/YishenTu/claudian/blob/main/src/features/chat/ui/InstructionModeManager.ts)** activates. Lines 34-40 detect the trigger key and swap the textarea placeholder to "# Save in custom system prompt", while lines 82-100 manage the text capture and submission states.

Press **Enter** to submit your instruction or **Escape** to clear the mode.

### Refinement and Persistence

After submission, `InputController.handleInstructionSubmit()` in **[`src/features/chat/controllers/InputController.ts`](https://github.com/YishenTu/claudian/blob/main/src/features/chat/controllers/InputController.ts)** (lines 81-98) coordinates the refinement workflow:

1. The raw instruction is sent to `InstructionRefineService`, which uses a dedicated refinement prompt to polish your directive
2. A modal dialog displays the refined version for your approval
3. Upon acceptance, the system appends the instruction to your stored prompt:

```typescript
const currentPrompt = plugin.settings.systemPrompt;
plugin.settings.systemPrompt = appendMarkdownSnippet(currentPrompt, finalInstruction);
await plugin.saveSettings();
new Notice('Instruction added to custom system prompt');

```

This workflow ensures that even hastily typed directives (`#be more concise`) are expanded into properly formatted instructions before persistence.

## Technical Implementation Details

### Prompt Assembly and Change Detection

The final system prompt is rebuilt for every query, but Claudian optimizes performance by detecting changes. In **[`src/core/agent/QueryOptionsBuilder.ts`](https://github.com/YishenTu/claudian/blob/main/src/core/agent/QueryOptionsBuilder.ts)** (lines 112-115), the system generates a `systemPromptKey` based on the current settings. If this key differs from the previous query's key—indicating the custom prompt has changed—the plugin forces a **session restart** to ensure Claude receives the new instructions immediately.

### When Changes Take Effect

- **Static edits** via the settings UI apply to the very next message you send
- **Instruction Mode** additions apply immediately after the refinement modal closes and the "Instruction added" notice appears
- **Session restarts** occur automatically when the `systemPromptKey` comparison detects a mismatch, ensuring no stale context persists

## Summary

- **Custom system prompts** in Claudian are persistent instructions stored in [`settings.json`](https://github.com/YishenTu/claudian/blob/main/settings.json) and appended to every Claude request under the `## Custom Instructions` header.

- **Instruction Mode**, triggered by typing `#` in the chat, offers a streamlined workflow for refining and appending new directives without leaving the conversation context.
- The `buildSystemPrompt()` function in [`src/core/prompts/mainAgent.ts`](https://github.com/YishenTu/claudian/blob/main/src/core/prompts/mainAgent.ts) handles the final assembly, while `QueryOptionsBuilder` detects changes and manages session lifecycle.
- Changes take effect immediately for subsequent queries, with automatic session restarts ensuring consistency.

## Frequently Asked Questions

### Where is the custom system prompt stored in Claudian?

The custom system prompt is stored in the plugin's [`settings.json`](https://github.com/YishenTu/claudian/blob/main/settings.json) file as the `systemPrompt` property, defined in **[`src/core/types/settings.ts`](https://github.com/YishenTu/claudian/blob/main/src/core/types/settings.ts)**. You can edit this value directly through the Claudian settings panel or programmatically via the plugin API.

### How does Instruction Mode differ from editing the settings directly?

Instruction Mode provides an inline, chat-based interface for adding instructions that includes an AI refinement step. When you submit an instruction via `#`, the `InstructionRefineService` rewrites your directive for clarity before appending it to the existing custom prompt. Direct settings editing bypasses this refinement layer and replaces the content immediately.

### Do changes to the system prompt take effect immediately?

Yes. The plugin detects changes via a `systemPromptKey` comparison in **[`src/core/agent/QueryOptionsBuilder.ts`](https://github.com/YishenTu/claudian/blob/main/src/core/agent/QueryOptionsBuilder.ts)**. If the custom prompt differs from the previous query, the system initiates a new Claude session to ensure the updated instructions are active for your next message.

### Can Instruction Mode replace the entire system prompt?

No. Instruction Mode in Claudian is strictly additive. It appends new instructions to your existing custom prompt using the `appendMarkdownSnippet()` function. To replace or clear the entire custom prompt, you must use the settings UI in **[`src/features/settings/ClaudianSettings.ts`](https://github.com/YishenTu/claudian/blob/main/src/features/settings/ClaudianSettings.ts)** and manually delete the contents.