When agents code, they often leave “conversation residue” around the code. These traces are chain-of-thought leakage, appearing as references to closed sessions, narrations of version changes, or fragments discussing design decisions in documentation. Only people who were present at the time can understand these contents; typical reviewers may feel confused. cot-lint is specifically designed to detect and fix this leakage.

What Is It

cot-lint is a Linter for detecting chain-of-thought leakage in code repositories. It targets conversation residue left by AI assistants in documentation, comments, and JSDoc.

  • Category: admin-security
  • Maintainer: YuanyuanMa03
  • License: MIT
  • Positioning: A zero-dependency command-line tool that supports Node.js environments.

Core Features

  1. Detects chain-of-thought leakage: Identifies chain-of-thought residue in documentation and comments, which becomes incomprehensible once separated from the specific session context.
  2. Identifies stale references: Locates dead references, such as design-session references (for example, design §4.7), perspectives tied to a stack or PR, and version markers (such as v1 refactor).
  3. Includes a repair skill: The plugin has a built-in cot-trim repair skill for automatically cleaning up and correcting detected leakage.
  4. Zero dependencies: No extra dependencies need to be installed; compatible with Node.js >= 20.

Installation and Enablement

Install it through the DeepSeek Harness plugin system:

dsh plugin add cot-lint

After installation, the cot-trim skill is loaded through the plugin’s skill provider and can be used to automatically fix detected leakage.

Typical Usage

cot-lint supports multiple command-line parameters to fit different scanning scenarios.

Basic Scan

Scan Markdown and prose files in the repository:

npx cot-lint

Machine-Readable Output

For CI or Agent processing, output in JSON format:

npx cot-lint --json

Extended File Scan

Scan line by line with specified file extensions, for example TypeScript and Python:

npx cot-lint --ext ts,py

Deep Scan

Include hidden directories (such as .agents/):

npx cot-lint --hidden

Exit Code Explanation

  • 0: The repository check passes with no leakage.
  • 1: Leakage or issues requiring fixes were found.
  • 2: Usage error or parameter error.

Applicable Scenarios and Notes

  • Applicable scenarios: Any team using agent-assisted coding that needs to filter out temporary thinking traces before code review; or CI pipelines that need to keep documentation clean.
  • Notes:
    • The plugin runs with the permissions of the current dsh process.
    • Ensure the local environment has Node.js version >= 20.
    • The plugin exempts certain content by default to avoid false positives:
      • Issue references.
      • Content marked as TODO / FIXME / XXX.
      • § references to external standards such as RFCs.
      • Lines containing cot-lint-ignore comments.

Summary

cot-lint combines detection with repair (cot-trim). It uses strict rules to determine what content must be retained (such as standard RFC references) and what chain-of-thought residue must be removed. This helps keep documentation in the codebase clean and makes the code readable for future maintainers.