Skip to content
ZoruaSamaPublic

About

[vscode-extension] Ducktor is a rubber duck who earns a doctor degree in software engineering.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

English | 中文

Ducktor

Ducktor: Use AI to generate code explanations and make reading easier with a VS Code extension.

Ducktor = Duck + Doctor

HomePage: https://zoruasama.github.io/Ducktor/

Overview

Ducktor stores code explanations in separate .ducktor files and displays them alongside source code in VS Code. It supports project onboarding, implementation walkthroughs, and code review without changing source code just to add explanations.

This repository contains two complementary components that can also be used independently:

Component Purpose Entry point
Ducktor Generator skill Guides an AI agent to read source code and generate or update .ducktor files at a requested scope and depth SKILL.md
Ducktor VS Code extension Reads .ducktor files and displays block explanations, terms, and line-by-line previews Extension directory

Workflow: source code → AI + generator skill → .ducktor files → VS Code extension → reading and navigation.

The extension is not an AI generator and does not require model or API-key configuration. Generation is handled by the AI host using the skill. You can also write .ducktor files manually and use only the extension.

Features

  • Layered generation: L1–L5 presets with independently configurable capabilities. Scope and depth are separate choices.
  • Block explanations: Read an overview through an end-of-line hint on a block's first line, or in a right-hand panel.
  • Term definitions: Dotted-underlined keywords reveal definitions on hover, with aliases and global, module, or local scopes.
  • Line-by-line reading: A standalone tab aligns complete read-only source code on the left with Markdown explanations on the right, with an overall-explanation view available.
  • Connected references: Navigate to source files, line ranges, workspace symbols, and external documentation.
  • Anchor-based positioning: Function, class, text, and other anchors help relocate blocks, with line ranges as a fallback.
  • Bilingual interface: English and Simplified Chinese notifications, diagnostics, and explanation panels. Explanation text follows the language requested during generation.

Screenshots

Generate explanations in Trae

Use the ducktor-generator skill with a source file to generate explanations at the requested depth.

Using the Ducktor generator skill in Trae

Code block hints

Ducktor adds end-of-line hints to explained blocks. This example shows OceanBase source code.

Ducktor hints in OceanBase source code

Hover explanations

Hover over a Ducktor hint to read the block overview and follow references to related code.

Ducktor block explanation on hover

Open the line-by-line preview

When valid line explanations are available, use the CodeLens entry at the top of the source file to open the standalone preview.

Line-by-line preview entry in the editor

Read source and explanations side by side

The standalone preview aligns source code with detailed line explanations and links to related implementations.

Source code and line-by-line explanations side by side

Diagrams in the right-hand panel

Read Mermaid diagrams in the right-hand explanation panel to understand code flow and relationships. Click mapped nodes to navigate to the corresponding source ranges.

OceanBase code explanations with Mermaid diagrams

Quick start

Ask your Agent to install the skill and extension

Copy this prompt into your Agent:

Please install the Ducktor skill and VSIX extension from https://github.com/ZoruaSama/Ducktor.
1. Detect the OS and installed VS Code-like IDEs (VS Code, Cursor, Qoder, Trae, CodeBuddy, and others). List names, versions, and available CLI or installation paths.
2. Ask which IDE(s) should receive the extension and which Agent(s) I use. Wait for my confirmation before installing.
3. Install the complete skill globally under my home directory, never in the project. Include SKILL.md and references/. Native paths: ~/.codex/skills/ducktor-generator/ for Codex, ~/.claude/skills/ducktor-generator/ for Claude Code, ~/.cursor/skills/ducktor-generator/ for Cursor.
4. For OpenSkills, check Node.js/npm, install npm install -g openskills if needed, then run openskills install ZoruaSama/Ducktor --global --universal and select ducktor-generator. Confirm the Agent can load ~/.agent/skills/; otherwise use its native global path. Update later with openskills update ducktor-generator.
5. Download the latest released VSIX from GitHub Releases. Use the selected IDE's supported installation method to install it into the current user's global extension directory, not the project or another IDE. Preserve existing settings. Ask before adding dependencies, elevating privileges, or overwriting files.
6. Verify the extension and complete skill are installed. Report actual paths and required IDE/Agent reloads. Never report unexecuted steps as successful.
7. End by showing the user these usage instructions:
Press Ctrl + Shift + P (macOS: ⌘ + Shift + P) to open the command palette. Search directly for these keywords, select the corresponding toggle commands, and make sure each feature is enabled:
hover: enable hover tooltips.
codelens: enable CodeLens.
inlay hints: enable inline hints.

1. Install the VS Code extension

Requires VS Code 1.85.0 or later.

Download the VSIX file from GitHub Releases, then run Extensions: Install from VSIX... in the VS Code command palette and select the downloaded file.

After installation, open the project folder you want to explore in VS Code, rather than opening only a standalone source file.

Ducktor is not yet published to the extension marketplace; use GitHub Releases. Press Ctrl + Shift + P (⌘ + Shift + P on macOS) to open the command palette. Search directly for hover, codelens, and inlay hints (or inline hints), select the corresponding toggle commands, and make sure Hover, CodeLens, and Inlay Hints are enabled. Alternatively, run Preferences: Open User Settings (JSON) and merge these entries into existing settings:

{
  "editor.inlayHints.enabled": "on",
  "editor.hover.enabled": true,
  "editor.codeLens": true
}

2. Load the generator skill

Install with OpenSkills

Install Node.js LTS (includes npm), then install OpenSkills and the complete skill globally:

npm install -g openskills
openskills install ZoruaSama/Ducktor --global --universal

Select ducktor-generator when prompted. --global --universal installs into ~/.agent/skills/; --universal alone is still project-level. Confirm your Agent can load the universal directory; otherwise use its native global skill directory above.

Update the installed skill from its original source:

openskills update ducktor-generator
openskills list

For Agents that read AGENTS.md, run openskills sync in the relevant project to register the globally installed skill. This updates project registration, not the skill's installation location. Other Agents follow their own loading conventions.

Manual installation

skills/ducktor-generator contains SKILL.md and its on-demand references/.

Copy the entire skill directory, including SKILL.md and references/, into your Agent's global skill directory under your home directory (~), not the project:

  • Codex: ~/.codex/skills/ducktor-generator/
  • Claude Code: ~/.claude/skills/ducktor-generator/
  • Cursor: ~/.cursor/skills/ducktor-generator/

Restart or reload the Agent as required. If it does not discover the skill, ask it to read skills/ducktor-generator/SKILL.md in your cloned repository and follow its procedure. The repository's skills/ directory is a distribution location, not an automatically discovered installation path.

Example requests:

Generate L3 Ducktor explanations for src/main.js in English, with verified references to related symbols.

Generate L5 explanations for the current function. Explain only the type members it uses, not the entire class.

Generate L4 + G explanations for functions affected by this change, focusing on line-by-line behavior and review concerns.

The skill reads current source code, verifies positions and references, and recursively creates the workspace-root .ducktor directory and required mirrored subdirectories when missing. Updates preserve valid content outside the requested scope.

3. Read explanations in source code

  • In the default hover mode, hover over the Ducktor end-of-line hint on a block's first line or a dotted-underlined term.
  • In panel mode, use end-of-line hints or term-hover links to read in the right-hand panel; explanation bodies are not shown in hovers.
  • When a file has valid lines entries, use its top-of-file line-by-line CodeLens to open the standalone two-column preview.
  • Click line numbers in the preview to return to and locate source code. Switch directly between overall and line-by-line explanations.

Enable both Inlay Hints and Hover in VS Code to see Ducktor's end-of-line hints and hover explanations or navigation links. Press Ctrl + Shift + P (⌘ + Shift + P on macOS), search directly for hover, codelens, and inlay hints (or inline hints), and use the corresponding toggle commands to ensure these features are enabled. Alternatively, add the following to your settings JSON:

{
  "editor.inlayHints.enabled": "on",
  "editor.hover.enabled": true
}

End-of-line hints require Inlay Hints, while hover content and links require Hover. Term underlines do not depend on Inlay Hints. The top-of-file line-by-line entry also requires CodeLens (editor.codeLens: true). If hints or hovers are missing, check whether workspace or language-specific settings override these options. The standalone preview is independent of ducktor.displayMode and can coexist with the right-hand panel.

4. Open the Ducktor File Explorer

Press Ctrl+Shift+P (Cmd+Shift+P on macOS), search for Ducktor: Open File Explorer / 打开文件目录, and run it. The command ID is ducktor.showIndex.

Ducktor File Explorer overview

The standalone page lists source files with Ducktor explanations in their original directory structure. Expand a file to browse line-by-line explanations, code snippets, and term explanations. Click a file name or an explanation entry to navigate to the original source and corresponding lines.

Search matches file names only, not directory paths or explanation content. Filter line explanations and diagrams independently by All / Present / Absent; both filters apply together. Use Refresh to reload the list.

Generation depth

Level Name Default content
L1 Overview A: responsibilities and results
L2 Usage A + B: important inputs, outputs, prerequisites, side effects, and failure behavior
L3 Understanding A + B + C: execution stages, branches, and data flow
L4 Line-by-line A + B + C + D: explanations for every meaningful source line
L5 Guided learning A + B + C + D + E + F: necessary symbols, relevant type members, and collaboration

G: review concerns is an independent switch, such as L4 + G. Custom combinations such as L1 + E and L3 + E are also supported.

L5 explains only members involved in the current function by default. It does not enumerate an entire class or recursively expand dependencies. Levels and capabilities are generation policies, not YAML fields in .ducktor files. See Capabilities and levels for the full policy.

File layout and minimal example

Mirror the source path relative to the workspace root and append the .ducktor extension:

my-project/
├── src/
│   └── main.js
└── .ducktor/
    └── src/
        └── main.js.ducktor

The extension reads mirrored files under the workspace-root .ducktor/ directory, not same-named files next to source code. Each folder in a multi-root workspace maintains its own .ducktor/ directory.

Given these three source lines in src/main.js:

function greet(name) {
  return `Hello, ${name}!`;
}

The corresponding .ducktor/src/main.js.ducktor can contain:

blocks:
  - range: "1-3"
    anchor:
      type: function
      name: greet
    content: |
      Return a greeting string using `name`, without modifying external state.
      See the return expression at [main.js#2].
    lines:
      - line: 1
        content: "Define the `greet` function with a `name` parameter."
      - line: 2
        content: "Build and return the greeting using a template literal."
terms:
  - symbol: name
    type: variable
    scope: local
    block: 1
    content: |
      The name supplied by the current caller, used to construct the greeting.

Key rules:

  • Use UTF-8 YAML. New files have top-level blocks and terms lists; use [] for an unused list.
  • range and lines.line use 1-based source line numbers. A local term's block is a 1-based index into the original blocks list.
  • content provides the overall explanation. Optional lines entries appear only in the standalone preview.
  • File references are relative to the source file's directory, not the .ducktor file's directory. [main.js#2] above targets line 2 of src/main.js.
  • Anchors help relocate a block that moves as a whole; edits inside a block still require updating line-by-line positions.
  • The extension does not generate, migrate, or maintain explanation paths when source files are renamed. The skill, user, or another external tool handles those operations.

See Ducktor format specification for the complete format. The generator skill provides focused, on-demand references for core format, Markdown and links, line explanations, terms and types, and validation. These reference documents are currently written in Chinese.

Extension settings and common commands

Setting Default Purpose
ducktor.enabled true Enable explanation display
ducktor.language en Interface language: en or zh-CN
ducktor.displayMode hover Overall-explanation display mode: hover or panel

Example VS Code settings JSON:

{
  "ducktor.enabled": true,
  "ducktor.language": "en",
  "ducktor.displayMode": "hover"
}

The language setting does not translate existing explanation content. Command titles and setting descriptions remain in English.

Command palette title Purpose
Ducktor: Refresh Code Explanations Refresh explanations manually
Ducktor: Show Explanation in Right-hand Panel Read explanations in the right-hand panel
Ducktor: Open Line-by-line Preview Open the current file's line-by-line preview
Ducktor: Clear Current Explanation File Delete the current source file's explanation file
Ducktor: Clear All Explanation Files Delete workspace explanation files after confirmation

Clear commands delete files; they do not just hide explanations. To temporarily disable display, set ducktor.enabled to false. The extension watches mirrored explanation files for creation, changes, and deletion. Refresh manually if the display is stale.

Repository structure and development

Ducktor/
├── README.md                     # English
├── README.zh-CN.md               # Chinese
├── rules.md                      # Complete file format specification
├── skills/
│   └── ducktor-generator/
│       ├── SKILL.md               # Generation procedure entry point
│       └── references/            # On-demand rules
└── vsc-plugin/
    ├── package.json              # Extension metadata and scripts
    ├── extension.js              # VS Code integration and interactions
    ├── core.js                   # Parsing, positioning, and term matching
    ├── rendering.js              # Markdown and preview rendering
    ├── localization.js           # Interface localization
    └── test/core.test.js          # Automated tests

Install Node.js and npm, then run these commands in vsc-plugin/ in order:

npm ci
npm run check
npm test
npm run package

check validates JavaScript syntax, test runs Node.js tests, and package builds a VSIX using VSCE. Packaging requires a Node.js version compatible with the development dependencies.

To debug, open vsc-plugin/ as the VS Code workspace and press F5 using the included Extension Host launch configuration. Open a test project containing .ducktor/ in the new window.

Questions and feedback: GitHub Issues.

About

[vscode-extension] Ducktor is a rubber duck who earns a doctor degree in software engineering.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages