SongXue – Blog

Hextra Shortcodes Cheat Sheet: Make Your Hugo Blog More Expressive

Wed, 17 Jun 2026 00:00:00 +0000

Hextra is a modern Hugo theme for documentation and blogs. Beyond standard Markdown, it ships with a rich set of shortcodes to enhance your content. This post covers the most useful ones with syntax and live rendered examples.

Collapsible Content (details)

Use to hide/show a block of content. Great for FAQ, supplementary notes, and long code snippets.

Expanded by Default

Click to collapse

This is expanded by default. It supports Markdown, including code, links, and lists.

{{% details title="Click to collapse" %}}
This is expanded by default. It supports **Markdown**.
{{% /details %}}

Collapsed by Default

Click to expand

This is hidden by default. Click the title to reveal.

{{% details title="Click to expand" closed="true" %}}
This is hidden by default.
{{% /details %}}

Note

Use {{% %}} delimiters (percent sign), otherwise Markdown inside won’t render.

Callouts

Use to display eye-catching notices within your content.

Default (Orange)

This is a default callout.

{{< callout >}}
  This is a default callout.
{{< /callout >}}

Info (Blue)

ℹ️

This is an info callout, for supplementary information.

{{< callout type="info" >}}
  This is an info callout, for supplementary information.
{{< /callout >}}

Warning (Yellow)

⚠️

This is a warning callout. Pay attention.

{{< callout type="warning" >}}
  This is a warning callout. Pay attention.
{{< /callout >}}

Error (Red)

🚫

This is an error callout. Dangerous operation.

{{< callout type="error" >}}
  This is an error callout. Dangerous operation.
{{< /callout >}}

Custom Emoji

👾

Use any emoji as the icon.

{{< callout emoji="👾" >}}
  Use any emoji as the icon.
{{< /callout >}}

GitHub-Style Alerts

Similar to callouts, but with lighter Markdown-only syntax.

Note

Supplementary info (blue).

Tip

Helpful suggestion (green).

Important

Key information (purple).

Warning

Caution needed (amber).

Caution

Dangerous operation (red).

> [!NOTE]
> Supplementary info (blue).

> [!TIP]
> Helpful suggestion (green).

When to use: Custom emoji → callout; simple labels → Alerts.

Tabs

Use to display parallel content, such as multi-language code or platform-specific steps.

{ "hello": "world" }

hello: world

hello = "world"

{{< tabs items="JSON,YAML,TOML" >}}
  {{< tab >}}
  ```json
  { "hello": "world" }
  ```
  {{< /tab >}}
  {{< tab >}}
  ```yaml
  hello: world
  ```
  {{< /tab >}}
  {{< tab >}}
  ```toml
  hello = "world"
  ```
  {{< /tab >}}
{{< /tabs >}}

Default selects the first tab. Use defaultIndex="1" to select the second.

Card Grid (cards + card)

Use for post recommendations, resource lists, and feature showcases. Supports icons, images, and tags.

Visit Blog

See all posts

About Me

Learn more

{{< cards cols="2" >}}
  {{< card link="/blog" title="Visit Blog" icon="pencil" subtitle="See all posts" >}}
  {{< card link="/about" title="About Me" icon="user" subtitle="Learn more" >}}
{{< /cards >}}

With tags:

With Tag

New

Warning

Alert

{{< card link="/blog" title="With Tag" tag="New" tagType="info" >}}
{{< card link="/blog" title="Warning" tag="Alert" tagType="warning" >}}

Steps

Use for tutorials, installation guides, and step-by-step instructions.

Step 1

Install Hugo: brew install hugo (macOS) or choco install hugo (Windows).

Step 2

Create a site: hugo new site myblog

Step 3

Choose a theme and deploy.

{{% steps %}}
### Step 1
Install Hugo: `brew install hugo` (macOS) or `choco install hugo` (Windows).

### Step 2
Create a site: `hugo new site myblog`

### Step 3
Choose a theme and deploy.
{{% /steps %}}

Note

Each step must be an H3 (###) header. Use {{% %}} delimiters.

Enhanced Code Blocks

Add {filename="filename"} after the language tag to display a filename label.

app.py

def hello():
    print("Hello, world!")

```python {filename="app.py"}
def hello():
    print("Hello, world!")
```

Mermaid Diagrams

Write Mermaid syntax in a code block to render SVG diagrams.

graph LR
    A[Start] --> B[Process]
    B --> C[End]

```mermaid
graph LR
    A[Start] --> B[Process]
    B --> C[End]
```

File Tree (filetree)

Use to display directory structures. Folders can be expanded/collapsed.

_index.md
- post1.md
- post2.md

{{< filetree/container >}}
  {{< filetree/folder name="content" state="open" >}}
    {{< filetree/file name="_index.md" >}}
    {{< filetree/folder name="blog" state="open" >}}
      {{< filetree/file name="post1.md" >}}
    {{< /filetree/folder >}}
  {{< /filetree/folder >}}
{{< /filetree/container >}}

state: "open" (default) or "closed".

Inline Badges

Small inline labels with 4 color variants.

Default:

Default

Info:

Info

Warning:

Warning

Error:

Error

{{< badge content="Default" >}}
{{< badge content="Info" type="info" >}}
{{< badge content="Warning" type="warning" >}}
{{< badge content="Error" type="error" >}}

With link and icon:

GitHub

{{< badge content="GitHub" link="https://github.com" icon="github" >}}

Inline Icons

Insert Heroicons inline with text.

GitHub, Academic, Edit

{{< icon "github" >}} GitHub

Note

Requires enableInlineShortcodes: true in site config.

PDF Embed

Embeds a PDF viewer in an iframe.

{{< pdf "path/to/file.pdf" >}}

Supports remote URLs and local file paths (in page bundles).

Jupyter Notebook

Renders .ipynb files inline with syntax-highlighted code cells, Markdown cells, and image output.

{{% jupyter "notebook.ipynb" %}}

Uses {{% %}} delimiters. Supports remote URLs.

Quick Reference

Need	Shortcode	Delimiter
Collapsible text	`details`	`{{% %}}`
Callout	`callout`	`{{< >}}`
Tabs	`tabs` + `tab`	`{{< >}}`
Steps	`steps`	`{{% %}}`
Card grid	`cards` + `card`	`{{< >}}`
File tree	`filetree/*`	`{{< >}}`
Embed PDF	`pdf`	`{{< >}}`
Embed Notebook	`jupyter`	`{{% %}}`
Inline icon	`icon`	`{{< >}}`
Badge	`badge`	`{{< >}}`
Diagrams	Mermaid	```mermaid
Code with filename	Code block attr	```lang {filename="..."}

For full parameter reference, see the Hextra Shortcodes Documentation.

🤖

AI disclosure: This article was written by the author with assistance from Claude (Anthropic) for drafting, bilingual translation, and formatting. The author has reviewed all content and takes full responsibility for its accuracy.

Claude Code + MIMO: Solving Multimedia Recognition with PreToolUse Hook

Wed, 03 Jun 2026 00:00:00 +0000

🙏

Acknowledgments: This tutorial builds on the mimo-media-recognition-mcp project developed by congxxx. Original article

Original repository: https://github.com/congxxx/mimo-media-recognition-mcp

This article extends the original solution with a PreToolUse Hook mechanism to prevent the Agent from directly reading multimedia files during long-task reasoning, which would otherwise cause errors.

1. Background

1.1 The Core Problem

Following up on the Claude Code setup tutorial, after connecting DeepSeek to Claude Code, a new problem emerged: DeepSeek V4pro is not a multimodal model, meaning it cannot natively process multimedia content — such as images, audio, or video.

1.2 The Original Solution

Through web search, I found an elegant architecture proposed by congxxx:

Claude Code (mimo-v2.5-pro)       ← Main conversation, strong reasoning
    ↓ Needs image/audio/video recognition
    ↓ Calls MCP
MIMO Media Recognition MCP        ← Dedicated multimedia recognition
    ↓ Calls MIMO API (mimo-v2-omni)
    ↓ Returns recognition result (text)
Claude Code continues              ← Context preserved

Via the MCP protocol, the main model (mimo-v2.5-pro in the original setup) retains its pro-level reasoning capability, while multimedia recognition is delegated to the omni model — each doing what it does best.

It sounded great. After adapting it to my local setup, I deployed it.

When explicitly instructing the Agent to use MCP for image understanding, the solution performed well. For instance, I asked the Agent to examine this model advantages overview image from the MIMO website:

The Agent called mcp__mimo-media__understand_image and returned a detailed text description: page structure (with navigation bar and headings), the content of four advantage cards (Native Omni-modal Perception, 1M Context, Omni-modal Agent Capability, Performance-Efficiency Balance), and specific values from the eight performance benchmark bars on the right (Image Understanding, Multimodal Agent, Video Understanding dimensions, with MiMo-V2.5 vs. competitor comparison data).

The entire process required no manual screenshot annotation — the Agent completed subsequent reasoning directly from the MCP-returned text.

1.3 The Remaining Problem: Agent’s “Self-Initiative”

However, during actual long-task reasoning, a thorny issue emerged:

⚠️

The Agent “takes matters into its own hands”

When the Agent encounters image/audio/video files during multi-step tasks, it tends to use the Read tool directly — rather than calling the MCP tools.

Since the main model is text-only, the binary data returned by Read cannot be understood, causing:

Errors: the model cannot process image input
Information loss: the Agent skips over multimedia content
Incomplete results: critical visual/audio information is ignored

Root cause: Claude Code’s Agent defaults to using the built-in Read tool for all files — it doesn’t “know” that the current model lacks multimodal support.

2. Solution: Two-Layer Defense

Layer 1: CLAUDE.md Soft Instructions

Explicitly tell the model in the global instructions file:

Which file types require MCP tools
Forbid using Read on multimedia files
Provide correct invocation examples

Limitation: Depends on the model “remembering” the instructions, which may be overlooked in complex reasoning chains.

Layer 2: PreToolUse Hook Hard Interception

Configure a Hook in settings.json that:

Intercepts all Read tool calls
Checks whether the target file is a multimedia format
If yes → blocks the call (exit 2) and returns an error with the correct MCP tool name

Advantage: System-level interception, independent of model compliance.

Workflow Diagram

Agent encounters image path "screenshot.png"
    │
    ├─ Layer 1: CLAUDE.md instruction guides
    │   "Should use mcp__mimo-media__understand_image"
    │
    ├─ If Agent still attempts Read("screenshot.png")
    │
    └─ Layer 2: PreToolUse Hook intercepts
        │
        ├── Detects .png extension
        ├── exit 2 (blocks the call)
        └── stderr: "BLOCKED: Use mcp__mimo-media__understand_image"
                │
                └── Agent sees feedback → switches to MCP tool
                    │
                    └── MCP returns text description → reasoning continues

3. Complete Configuration

3.1 Prerequisites

# Check Claude Code
claude --version

# Check Python
python --version

# Check Git
git --version

3.2 Install MCP Server (Same as Original)

# 1. Clone the project
git clone https://github.com/congxxx/mimo-media-recognition-mcp.git
cd mimo-media-recognition-mcp

# 2. Install dependencies
pip install uv
uv venv .venv
uv pip install -e .

3.3 Register MCP Server

claude mcp add mimo-media \
  --scope user \
  --env MIMO_API_KEY="your-api-key" \
  --env MIMO_API_BASE="https://token-plan-cn.xiaomimimo.com/v1" \
  --env MIMO_MODEL="mimo-v2.5" \
  -- "path/to/your/python" \
  -m mimo_media_recognition_mcp.server

# Optional: for short-audio real-time transcription, add:
# --env MIMO_ASR_MODEL="mimo-v2.5-asr" \
# --env MIMO_ASR_LANGUAGE="zh"

💡

Model selection notes:

MIMO_MODEL set to mimo-v2.5 (general multimodal understanding, default for audio transcription)
mimo-v2.5 uses chain-of-thought reasoning to produce high-quality, complete transcriptions — ideal for long recordings and meeting transcripts
ASR mode is not recommended by default: mimo-v2.5-asr tends to produce repetition loops on audio longer than ~2 minutes
Only enable MIMO_ASR_MODEL when you need real-time transcription of short audio clips

Verify the installation:

claude mcp get mimo-media
# Expected output: Status: ✓ Connected

3.4 Create PreToolUse Hook (New in This Solution)

3.4.1 Create the Hook Script

Create block_media_read.py in the ~/.claude/hooks/ directory:

"""
PreToolUse hook: Block Read tool on multimedia files.

When the agent tries to Read an image/audio/video file, this hook
blocks the call (exit 2) and instructs the model to use the
mimo-media MCP tools instead.
"""
import sys, json

MEDIA_MAP = {
    ".png": ("image", "understand_image"),
    ".jpg": ("image", "understand_image"),
    ".jpeg": ("image", "understand_image"),
    ".gif": ("image", "understand_image"),
    ".bmp": ("image", "understand_image"),
    ".webp": ("image", "understand_image"),
    ".svg": ("image", "understand_image"),
    ".mp3": ("audio", "understand_audio"),
    ".wav": ("audio", "understand_audio"),
    ".m4a": ("audio", "understand_audio"),
    ".ogg": ("audio", "understand_audio"),
    ".flac": ("audio", "understand_audio"),
    ".aac": ("audio", "understand_audio"),
    ".mp4": ("video", "understand_video"),
    ".mov": ("video", "understand_video"),
    ".avi": ("video", "understand_video"),
    ".mkv": ("video", "understand_video"),
    ".webm": ("video", "understand_video"),
    ".flv": ("video", "understand_video"),
}

try:
    data = json.load(sys.stdin)
except Exception:
    sys.exit(0)

tool_input = data.get("tool_input", {})
file_path = tool_input.get("file_path", "") or tool_input.get("path", "")
if not file_path:
    sys.exit(0)

ext = ""
if "." in file_path:
    ext = "." + file_path.rsplit(".", 1)[-1].lower()

if ext in MEDIA_MAP:
    media_type, mcp_tool = MEDIA_MAP[ext]
    print(
        f"BLOCKED: The Read tool cannot process {media_type} files. "
        f"Use the MCP tool `mcp__mimo-media__{mcp_tool}` instead. "
        f"Example: call mcp__mimo-media__{mcp_tool} with "
        f'{{"prompt": "describe this {media_type}", "{media_type}_path": "{file_path}"}}',
        file=sys.stderr
    )
    sys.exit(2)

sys.exit(0)

3.4.2 Register the Hook

Edit ~/.claude/settings.json and add the hooks field:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "python ~/.claude/hooks/block_media_read.py",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

💡

How the Hook works:

matcher: "Read" — matches all Read tool invocations
The Hook script receives the tool input JSON via stdin
Checks whether the file_path extension matches a multimedia format
Match → exit 2 (block the call) + stderr output with guidance
No match → exit 0 (pass through normally)

When the Hook returns exit 2, the Agent sees:

BLOCKED: The Read tool cannot process image files. Use the MCP tool mcp__mimo-media__understand_image instead.

Upon receiving this feedback, the Agent automatically switches to the correct MCP tool.

3.5 Update CLAUDE.md Instructions (New in This Solution)

Add the multimedia handling rules to the end of the global ~/.claude/CLAUDE.md:

## Multimedia File Handling (Mandatory)

The current reasoning model is text-only and **cannot directly understand images, audio, or video**.

### Rule: Always Use MCP for Multimedia Files

- **Images** (.png, .jpg, .jpeg, .gif, .bmp, .webp, .svg) → use `mcp__mimo-media__understand_image`
- **Audio** (.mp3, .wav, .m4a, .ogg, .flac, .aac) → use `mcp__mimo-media__understand_audio`
- **Video** (.mp4, .mov, .avi, .mkv, .webm, .flv) → use `mcp__mimo-media__understand_video`

### Forbidden

- Do **not** use the `Read` tool on the above formats (will be blocked by Hook)
- Do **not** attempt to "interpret" binary multimedia content on your own
- Do **not** assume the content of images/audio/video

### Correct Workflow

1. Identify a multimedia file path
2. Select the corresponding MCP tool based on the extension
3. Call the MCP tool to obtain the understanding result
4. Continue reasoning based on the MCP-returned text

### Example

```bash
# Wrong ❌
Read("screenshot.png")

# Correct ✅
mcp__mimo-media__understand_image(prompt="Describe this image", image_path="screenshot.png")
```

3.6 Verify the Configuration

# Verify MCP connection
claude mcp get mimo-media

# Test the Hook script
echo '{"tool_name": "Read", "tool_input": {"file_path": "test.png"}}' | \
  python ~/.claude/hooks/block_media_read.py 2>&1
# Expected output: BLOCKED: The Read tool cannot process image files...
# Expected exit code: 2

# Test that regular files are unaffected
echo '{"tool_name": "Read", "tool_input": {"file_path": "readme.md"}}' | \
  python ~/.claude/hooks/block_media_read.py 2>&1
# Expected output: (empty)
# Expected exit code: 0

4. Comparison with the Original

Dimension	Original (congxxx)	This Solution (+ Hook)
MCP Server	✅ Configured	✅ Configured (same as original)
Explicit MCP calls	✅ Works	✅ Works
CLAUDE.md instructions	—	✅ New, guides Agent to choose MCP proactively
PreToolUse Hook	—	✅ New, system-level interception of incorrect Read calls
Multimedia in long tasks	⚠️ Agent may bypass MCP	✅ Two-layer defense, ensures MCP path
Configuration complexity	Low	Medium (one extra Hook script + CLAUDE.md config)

5. Lessons Learned

5.1 Path Issues in the Hook Script

Symptom: The Hook script encounters inconsistent path separators on Windows.

Cause: Claude Code executes Hooks via Git Bash on Windows, where paths may appear in /c/Users/... format.

Solution: The Hook script only checks file extensions and does not depend on path format, so it remains unaffected.

5.2 Hook Not Taking Effect

Symptom: The Hook is configured but the Agent still directly Reads images.

Troubleshooting steps:

Verify the hooks field format in settings.json is correct
Confirm the Hook script path is accessible to Python
Restart the Claude Code session (Hook configuration requires reloading)

5.3 Audio Transcription Returning Placeholder / Unrelated Content (2026-07-06 Update)

Symptom: Calling understand_audio to transcribe Chinese audio consistently returned irrelevant English responses (e.g., a fake “coffee shop ordering” dialogue, “I cannot process audio files”), completely unrelated to the actual recording.

Investigation:

Confirmed file exists and format is valid (2.1MB MP3, ~9 minutes phone recording)
Verified API connectivity via the mimo://config MCP resource — normal
Read the MCP Server source code (server.py) directly, discovering two critical bugs:

Root Cause A: [:80] Truncation Bug

# server.py line 165 (before fix)
content_blocks.append({
    "type": "text",
    "text": f"[Audio file: {media_url[:80]}...]",  # ← Only first 80 chars!
})

A 2.1MB MP3 file produces ~3MB of base64-encoded data, but [:80] sends only the first 80 characters of the data URL: data:audio/mpeg;base64,//uQxAAA... — the model received a text marker with no actual audio data to process.

Root Cause B: Wrong API Format

After consulting the MIMO official documentation, we discovered that MIMO’s Anthropic API (/anthropic/v1/messages) only supports text and image content blocks — it does not natively support audio or video input.

The correct approach is to use the OpenAI-compatible endpoint (/v1/chat/completions) with input_audio content blocks:

// ❌ MCP Server old format (text wrapper, Anthropic endpoint)
{"type": "text", "text": "[Audio file: data:audio/mpeg;base64,<truncated>]"}
// API response: model cannot understand audio

// ✅ MIMO official format (input_audio, OpenAI endpoint)
{"type": "input_audio", "input_audio": {"data": "data:audio/mpeg;base64,<full base64>"}}
// API response: correct transcription text

The Fix:

An architecture-level rewrite of server.py:

Component	Before Fix	After Fix
Images	Anthropic endpoint (working)	Unchanged
Audio/Video	Anthropic endpoint + `type: "text"` + `[:80]` truncation	OpenAI endpoint + `type: "input_audio"/"input_video"` + full base64
ASR support	None	Via `MIMO_ASR_MODEL` and `MIMO_ASR_LANGUAGE` environment variables
Timeout	120s	300s (large audio files need more time)

A Note on ASR Model Suitability

After empirical comparison, mimo-v2.5-asr and mimo-v2.5 show significant differences in transcription tasks:

Dimension	`mimo-v2.5-asr`	`mimo-v2.5`
Long audio (>2 min)	❌ Severe repetition loops	✅ Complete and accurate
Short audio (<2 min)	✅ Fast real-time	✅ Comparable quality
Transcription method	End-to-end sequence decoding	Chain-of-thought reasoning
Output control	Weak (no prompt constraint)	Strong (prompt-controllable)

Recommendation: Keep MIMO_ASR_MODEL disabled by default. Let understand_audio use mimo-v2.5’s chain-of-thought transcription. Only enable ASR mode when real-time transcription of short clips is needed.

6. Configuration Reference

File Checklist

File	Purpose
`~/.claude/settings.json`	Hook registration + global settings
`~/.claude/CLAUDE.md`	Global instructions (including multimedia rules)
`~/.claude/hooks/block_media_read.py`	Hook script
MCP Server project directory	mimo-media-recognition-mcp

7. Summary

🎯

Core idea: Decouple multimedia recognition from the model itself and transform it into a tool-calling capability via the MCP protocol.

Key innovation: Building on the original MCP solution, add a PreToolUse Hook as a system-level safety net to ensure the Agent never bypasses MCP when handling multimedia files, under any circumstances.

Two-layer defense:

Soft instruction (CLAUDE.md) — guides the Agent to proactively choose the correct tool
Hard interception (PreToolUse Hook) — acts as a fallback, blocking incorrect tool calls

This “soft guidance + hard interception” pattern is not limited to multimedia scenarios — it can be generalized to any situation requiring enforced tool routing.

🤖

References

🔗 GitHub (Original MCP Server): https://github.com/congxxx/mimo-media-recognition-mcp
🔗 GitHub (This Solution’s Hook): https://github.com/SongXue-J/claude-code-multimedia-hook
📝 Original blog post: Solving multimedia recognition issues after connecting Claude Code to MIMO models
📖 MCP Documentation: https://modelcontextprotocol.io
📖 Claude Code Hooks Documentation: https://docs.anthropic.com/en/docs/claude-code/hooks

Claude Code + CC Switch + DeepSeek: Full Setup Guide for AI Agent

Tue, 26 May 2026 00:00:00 +0000

1. Why This Setup?

The primary reason is Anthropic’s increasingly strict access restrictions on accounts registered in mainland China, compounded by high subscription costs — though I’ve never actually subscribed due to the cumbersome process.

With CC Switch + DeepSeek, you get an AI Agent that is affordable, stable, and functionally comparable. This guide should help anyone getting started with this workflow — including my past self.

💡

Core Architecture: Positron IDE → Claude Code CLI → CC Switch Proxy → DeepSeek API (Anthropic-compatible endpoint)

Component	Role	Cost
Positron IDE	IDE frontend, runs Claude Code terminal & VS Code extensions	Free / Open source
Claude Code CLI	Anthropic’s official AI programming assistant	Free (API pay-per-use)
CC Switch	Provider switching GUI, routes API calls to third-party models	Free / Open source
DeepSeek API	Third-party LLM API with Anthropic-compatible endpoint	~¥2/M tokens (cache hit)

Why Positron?

My previous experience was mainly with R Studio for R, but its plugin support for AI Agents is still immature. Although packages like aisdk allow calling LLMs from R Studio, the ecosystem is far less developed than Claude Code’s.

Then came Positron, with native R/Python support and a Claude Code extension. While its GUI and some keyboard shortcuts differ from what I was used to in R Studio, the ability to seamlessly integrate Claude into my workflow makes this trade-off entirely acceptable.

2. Architecture Overview

┌──────────────────────────────────────────────────┐
│              Positron IDE (VS Code Fork)          │
│  ┌─────────────┐  ┌──────────────────────────┐   │
│  │ VS Code Ext  │  │  Terminal (claude cmd)   │   │
│  └──────┬──────┘  └───────────┬──────────────┘   │
└─────────┼─────────────────────┼──────────────────┘
          │                     │
          ▼                     ▼
┌──────────────────────────────────────────────────┐
│        Claude Code CLI (@anthropic-ai/claude-code)│
│        Reads env config from ~/.claude/settings   │
│        ANTHROPIC_BASE_URL → routes to DeepSeek    │
└──────────────────────┬───────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────┐
│            CC Switch Desktop App (v3.14+)         │
│   • Manages multiple provider configs             │
│     (DeepSeek/GLM/Xiaomi etc.)                    │
│   • Auto-writes ~/.claude/settings.json           │
│   • Balance check, model switching, local proxy   │
└──────────────────────┬───────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────┐
│     DeepSeek API (api.deepseek.com/anthropic)     │
│   • Anthropic Messages API compatible endpoint    │
│   • Model: deepseek-v4-pro (1M context)           │
│   • Model: deepseek-v4-flash (fast response)      │
└──────────────────────────────────────────────────┘

Data Flow

Enter / commands or natural language in the Claude Code plugin dialog within Positron’s terminal
Claude Code CLI reads environment variables from ~/.claude/settings.json, sends API requests to ANTHROPIC_BASE_URL
Requests arrive at DeepSeek’s Anthropic-compatible endpoint, processed in Anthropic Messages API format
After DeepSeek model inference, a response in Anthropic format is returned
Claude Code CLI parses the response and renders the output in the terminal/IDE

3. Prerequisites

3.1 System Requirements

Item	Requirement
OS	Windows 10+ / macOS 12+ / Linux
Node.js	v18.0.0 or above (LTS recommended)
Disk	~1GB (Node.js + Claude Code + CC Switch)
Network	Access to api.deepseek.com (direct from mainland China)

3.2 Register DeepSeek and Get API Key

Open your browser and visit platform.deepseek.com
Register an account and log in
Go to the “API Keys” page and click “Create API Key”
Copy the generated sk- prefixed key (shown only once — save it immediately)

⚠️

You must top up your balance before using the API. Start with ¥10–20 for testing. DeepSeek charges per use; API requests return 401 when balance is insufficient.

4. Installation

4.1 Install Claude Code

Runoob.com has a detailed and clear guide here, covering both the official script installation (recommended) and npm installation.

Below is the npm installation flow I used previously, for reference.

Install Node.js

Node.js is the runtime environment for Claude Code CLI.

Windows

Visit nodejs.org and download the LTS installer (.msi)
Run the installer with all default options
Restart your terminal and verify:

node -v   # Should show v18.x.x or v20.x.x or v22.x.x
npm -v    # Should show 9.x.x or 10.x.x

macOS

# Recommended: use Homebrew
brew install node@22
# Or download .pkg from nodejs.org

Common Issue: PowerShell Execution Policy

If Windows PowerShell reports: cannot be loaded because running scripts is disabled on this system

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Install Claude Code CLI

npm install -g @anthropic-ai/claude-code

Verify:

claude -v   # Shows version number

After installation, the global config directory is located at:

Windows: C:\Users\<username>\.claude\
macOS/Linux: ~/.claude/

Key config files:

settings.json — Main config (environment variables, permissions, etc.)
settings.local.json — Local overrides (not synced)
CLAUDE.md — Project or global coding guidelines

4.2 Download and Install CC Switch

Download

CC Switch is an open-source desktop app (GitHub: farion1231/cc-switch) for one-click model provider switching in Claude Code.

Releases: github.com/farion1231/cc-switch/releases

Platform	File	Install
Windows	`.msi` installer or `.zip` portable	Double-click .msi to install
macOS	`.dmg`	Drag to Applications
Linux	`.AppImage`	`chmod +x .AppImage && ./.AppImage`

Configure DeepSeek Provider

Open CC Switch, click the "+" button (top right) to add a provider
Select DeepSeek from presets, or fill in manually:

Setting	Value	Notes
Base URL	`https://api.deepseek.com/anthropic`	Must include /anthropic path
Auth Type	ANTHROPIC_AUTH_TOKEN	Token-based auth
API Key	`sk-xxxxxxxx`	Your DeepSeek key
API Format	Anthropic Messages	Anthropic-compatible format
Default Model	`deepseek-v4-pro[1m]`	Primary model, 1M context
Haiku Model	`deepseek-v4-flash`	Fast lightweight model
Sonnet Model	`deepseek-v4-pro`	Mid-tier tasks
Opus Model	`deepseek-v4-pro`	Complex tasks

Check “Write to common config”, click “Add”
Back on the main screen, select the newly added DeepSeek and click “Enable”

💡

What CC Switch does: It automatically writes the above configuration into the env field of ~/.claude/settings.json. Claude Code reads these environment variables on startup.

Manual settings.json (optional alternative)

If you prefer not to use the CC Switch GUI, you can edit the config file directly. Add the following to ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-your-deepseek-key",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_REASONING_MODEL": "deepseek-v4-pro"
  }
}

4.3 Install Positron IDE

Installation Steps

Visit positron.posit.co to download the installer for your platform
Launch Positron after installation
In the sidebar extensions page, install the Claude Code for VS Code extension — verify the publisher is Anthropic

Using Claude Code in Positron

Mode	Description	Best For
A. Terminal	Run `claude` directly in the terminal	Daily coding assistance, file operations, project search
B. VS Code Extension	Install Claude Code for VS Code extension, use from sidebar	IDE-integrated workflow, editor panel integration

A. Terminal Mode (Recommended)

claude

Start an interactive session:

> Refactor the validateInput function in src/utils.ts for better readability
> /memory    # View and manage memories
> /model     # Check current model
> /help      # Show all commands

5. Verify Configuration

5.1 Verify CLI Startup

claude

In the interactive session, ask:

> What model are you using?

✅

Expected response: Model is deepseek-v4-pro, context window 1,048,576 tokens (1M), provided by DeepSeek.

5.2 Verify API Connectivity

> Write a Python function to compute the Fibonacci sequence and print the first 20 terms

If it returns correct code and output, the API connection is working properly.

5.3 Model Selection Strategy

Scenario	Recommended Model	Why
Single-file scripts, log analysis	`deepseek-v4-flash`	Fast response (<800ms), very low cost
Multi-file refactoring, architecture	`deepseek-v4-pro[1m]`	1M context, understands 50+ files
Complex algorithms, deep technical analysis	`deepseek-v4-pro[thinking]`	Activates dynamic reasoning chain
Long documents + reasoning	`deepseek-v4-pro[1m][thinking]`	Max context + deep reasoning

In my experience, switching models via /model in the sidebar is unreliable. Editing model names or switching providers directly in CC Switch is more effective. After saving changes, wait 1–2 minutes before continuing.

6. Other Features

6.1 Multi-Provider Management

CC Switch supports configuring multiple providers simultaneously:

Provider	Endpoint	Notes
DeepSeek	`api.deepseek.com/anthropic`	Best value, V4-Pro 1M context
Zhipu GLM	`open.bigmodel.cn/api/anthropic`	GLM-5, strong general ability
Xiaomi MiMo	`api.xiaomimimo.com/anthropic`	MiMo-V2.5-Pro, lower price for coding

After adding multiple providers in CC Switch, you can switch between them at any time.

6.2 Skills and Plugins

Claude Code supports installing Skills (skill sets) to extend functionality. I may publish a separate article on using and building Skills in the future.

Many users publish their own Skills, but for security and usability reasons, I strongly recommend reading the documentation and reviewing the structure before installing any Skills.

7. Troubleshooting

Problem 1: `claude` command not found

npm list -g --depth=0
npm bin -g  # Add this path to your PATH

Problem 2: `401 Unauthorized`

Cause: Invalid API Key or insufficient balance. Check at platform.deepseek.com.

Problem 3: `Connection refused` or `model not found`

Base URL missing /anthropic path — Ensure it is https://api.deepseek.com/anthropic
Model name typo — Confirm: deepseek-v4-pro, deepseek-v4-flash

Problem 4: PowerShell script execution error

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

8. Security

⚠️

API Key is stored in ~/.claude/settings.json — never share or upload it to a public repository
Consider storing the key in settings.local.json instead of settings.json
Rotate your API Key periodically

Appendix: Core Config Reference

`~/.claude/settings.json`

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-your-deepseek-api-key",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_REASONING_MODEL": "deepseek-v4-pro"
  }
}

🤖

Resources

Resource	Link
Claude Code Docs	docs.anthropic.com/en/docs/claude-code
CC Switch GitHub	github.com/farion1231/cc-switch
DeepSeek Platform	platform.deepseek.com
Positron IDE	positron.posit.co
Node.js Download	nodejs.org

ADE Heatmap illustration

Mon, 17 Feb 2025 00:00:00 +0000

Introduciton

This R Markdown document describes how to merge multiple values from different assays to create heatmaps to visualize the features of each antibody-variant pair.

The following steps present how to read data from excel files, merge them together and use them to make a pretty heatmap.

Prepare R packages

I need readxl and writexl to input/output data, dplyr and scales to process data, and pheatmap, ggplot2, tidyverse to create graphs:

> library(readxl)
> library(writexl)
> library(scales)
> library(pheatmap)
> library(ggplot2)
> library(tidyverse)

Process data

set input file or folder path

> input_file_path = "./serum_dataset/vaccine serum samples-wt delta omi.xlsx"
> input_folder_path = "./serum_dataset"
> # replace it with your file or folder path

Usually, I’d like to export the graphs to the same folder as the input files :

> outputpath = paste0(dirname(input_file_path),"\\heatmap.pdf")

This outputpath will be named as “heatmap.pdf” in the same folder as the input file:

[1] "./serum_dataset\\heatmap.pdf"

If you chose folder path as input, the outputpath should be as same as the input_folder_path:

> outputpath = input_folder_path
> outputpath

read data

Importantly, make sure the data in your excel files looks like this:

sample	WT-1	WT-2	WT-3	WT-4	WT-5	WT-6	WT-7	WT-8	WT-9	Delta-1	Delta-2	Delta-3	Delta-4	Delta-5	Delta-6	Delta-7	Delta-8	Delta-9	Omicron-1	Omicron-2	Omicron-3	Omicron-4	Omicron-5	Omicron-6	Omicron-7	Omicron-8	Omicron-9
249	3490	3566	3701	3823	3796	3779	4106	6278	11691	2318	2265	2270	2361	2399	2625	4045	19085	42810	2688	2691	2608	2743	2742	2697	2756	3168	10036
NA	3236	3265	3310	3453	3100	2996	3179	10101	17397	2160	2154	2158	2899	2047	2424	6343	10983	41618	2550	2473	2521	2474	2317	2331	2356	3451	7322
230	2384	2528	2675	2620	2673	2764	4490	10318	18427	1879	2515	1857	1938	2726	4257	12521	23052	57013	2255	2264	2126	2276	2062	2187	2262	2363	5507
NA	2394	2296	2315	2243	2376	3073	5018	14496	18438	1852	1869	1849	1792	1907	4469	16023	23121	29738	2121	2088	2464	2183	2036	1983	1931	2320	4665
244	1958	1936	2026	2005	1976	2474	2137	4656	11394	1698	2007	1678	1796	1647	1795	3571	9030	30330	2038	1889	2044	1917	1911	2243	2243	2969	6628
NA	1832	1921	1920	1790	1854	1996	2062	3999	10572	1703	1662	1543	1523	1683	3228	3715	7058	20046	1858	1881	1799	1760	1749	1736	1984	2797	8719

The Sample column will be used as the key to merge data together. If your data format matches the example above, we can read it by these following commands:

If your data is stored in different excel files which contains only one sheet:

> file_names <- list.files(input_folder_path, pattern = "\\.xlsx$|\\.xls$", full.names = TRUE)
> merged.data = list()
> for (i in 1:length(file_names)) {
+     # read data in excel files
+     data <- read_excel(file_names[i])
+     colnames(data)[1] = "sample"
+     # merge data together 
+     merged.data[[i]] = data
+ }
> merged_df = merged.data[[1]]

Let’s take a look at the output merged_df:

It’s a dataframe:

> class(merged_df)
[1] "tbl_df"     "tbl"        "data.frame"

data processing

This merged_df will be used as the input to undergo further processing, including merge batches, omit NA value and normalization

merge batches and omit `NA` value

 [1] "sample"    "WT-1"      "WT-2"      "WT-3"      "WT-4"      "WT-5"     
 [7] "WT-6"      "WT-7"      "WT-8"      "WT-9"      "Delta-1"   "Delta-2"  
[13] "Delta-3"   "Delta-4"   "Delta-5"   "Delta-6"   "Delta-7"   "Delta-8"  
[19] "Delta-9"   "Omicron-1" "Omicron-2" "Omicron-3" "Omicron-4" "Omicron-5"
[25] "Omicron-6" "Omicron-7" "Omicron-8" "Omicron-9"

normalization using Z-score

Z-score is usually used to perform standardization. Here is a detailed explanation about its definition. Briefly, we here use (x-μ)/σ to calculate the z-score of Binding, Neutralization, ADE and Competition ELISA assays respectively.

> output.data = merged_df %>% na.omit()
> rownames(output.data) = output.data$sample
> output.data$sample = NULL

Take a look at the outout.data:

WT-1	WT-2	WT-3	WT-4	WT-5	WT-6	WT-7	WT-8	WT-9
3490	3566	3701	3823	3796	3779	4106	6278	11691
2384	2528	2675	2620	2673	2764	4490	10318	18427

Create Heatmap

Now you have already gotten your data for make heatmap, but there are still some more things to do.

annotate columns and rows

Note that the column annotations must match the order in your output.data.
So you may want to double-check how your output.data arranges:

> colnames(output.data)
 [1] "WT-1"      "WT-2"      "WT-3"      "WT-4"      "WT-5"      "WT-6"     
 [7] "WT-7"      "WT-8"      "WT-9"      "Delta-1"   "Delta-2"   "Delta-3"  
[13] "Delta-4"   "Delta-5"   "Delta-6"   "Delta-7"   "Delta-8"   "Delta-9"  
[19] "Omicron-1" "Omicron-2" "Omicron-3" "Omicron-4" "Omicron-5" "Omicron-6"
[25] "Omicron-7" "Omicron-8" "Omicron-9"

Now you are ready to set the annotation following the commands below:

>   annotation_col= data.frame(Datatype = factor(rep(c("WT","Delta","omi"),c(9,9,9))))
>   rownames(annotation_col) = colnames(output.data)
>   ann_colors = list(Datatype = c(WT="#3567E5",Delta="#B0E65E",omi="#91726B"))

set legend breaks

The break argument is quite important for the output format of your heatmap, as it determines the representative color for your data at certain scale. Here we use a bk factor to set it.

>  bk = seq(-2,5,by = 1)

draw your heatmap

Finally, we reach here.

>  #heatmap
>   p1 <- pheatmap(output.data,  # your prepared data
+                  color = c(colorRampPalette(c('#C6DAF1','white','red'),bias = 1.7)(6)), 
+                  # set colors, here I make 6 colors between light blue and red
+                  border_color = "black",  #set border color，NA means no border
+                  scale= "none", 
+                  # "column" indicates z-score standardization for each column,
+                  # "row" indicates z-score standardization for each row,
+                  # "none" indicates no standardization, 
+                  # we chose "none" here because we have done it in previous steps.
+                  cluster_rows = TRUE, # whether cluster by rows
+                  cluster_cols = FALSE, # whether cluster by columns
+                  legend = TRUE, # display legends or not
+                  breaks = bk, # set breaks here 
+                  legend_breaks = c(-2:5), # set legend breaks here 
+                  legend_labels = c(-2:5), # set labels at legend breaks
+                  show_rownames = FALSE, 
+                  show_colnames = FALSE, 
+                  display_numbers = FALSE,
+                  fontsize = 10, # set the font size
+                  annotation_col =annotation_col,
+                  annotation_colors = ann_colors,
+                  angle_col = 0,
+                  cutree_rows=4, # break heatmap by clustering result
+   )

We did it! Now enjoy your heatmap!

save your heatmap

>  ggsave(file = outputpath, plot = p1,width = 11,height = 10,dpi = 300)

🤖