CLEAR: Clone-Localized, Embedding-Augmented Refactoring

A VS Code extension that detects code clones with NiCad and proposes compile-verified refactorings through an LLM. The acronym: Clone-detection, Localized, Embedding-driven, Augmented Refactoring.

Status: Research prototype. Tested on Ubuntu 24.04 with VS Code 1.96+. macOS and Windows likely work but are not verified.

Quick start

CLEAR depends on two external tools that must be installed before the extension can run: TXL (the parser engine) and NiCad (the clone detector that uses TXL). Order matters — TXL must be installed first.

For Ubuntu / Debian:

# 1. Install TXL (required by NiCad)
sudo apt update && sudo apt install -y txl
# Or download from https://txl.ca/txl-download.html for other platforms
which txl     # verify

# 2. Install NiCad 6.2
# Download from https://www.txl.ca/txl-nicaddownload.html
tar xzf NiCad-6.2.tar.gz
cd NiCad-6.2

# Modern GCC (≥14) needs an older-C flag for NiCad's bundled tools:
sed -i 's/^\tgcc -w -O /\tgcc -w -O -std=gnu89 -fcommon /' tools/Makefile
make

./nicad6      # verify usage prints
cd ..

# 3. Symlink so CLEAR's auto-detector finds NiCad
ln -s "$(pwd)/NiCad-6.2" ~/NiCad-6.2

# 4. Install Ollama and pull the recommended models
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5-coder:7b
ollama pull nomic-embed-text

# 5. Install the extension
code --install-extension clear-1.0.0.vsix --force

Reload VS Code, click the CLEAR icon in the Activity Bar, and the setup wizard will walk you through provider selection. Click Detect Clones on any workspace.

If you'd rather use a cloud LLM (Anthropic / OpenAI), skip step 4 — Ctrl+Shift+P → CLEAR: Set Anthropic API Key or CLEAR: Set OpenAI API Key, then pick the provider in the wizard.

Prerequisite check:

which txl && txl -version    # TXL is installed and responds
~/NiCad-6.2/nicad6           # NiCad runs and prints usage

If either fails, CLEAR cannot detect clones.

Requirements

Component	Why	How to get it
VS Code 1.96+	host editor	code.visualstudio.com
TXL 10.8+	NiCad's parser engine	`sudo apt install txl` or txl.ca
NiCad 6.2+	clone detector (requires TXL)	Download, extract, `make`
Node.js 20+	required only for building the extension from source	nodejs.org
Ollama (recommended)	local LLM + embeddings	ollama.com
Anthropic / OpenAI API key (optional)	cloud LLM alternative	set via `Ctrl+Shift+P → CLEAR: Set Anthropic API Key`
NVIDIA GPU (strongly recommended for local LLM)	local model inference	any modern NVIDIA card with ≥8 GB VRAM

The extension auto-detects NiCad in ~/NiCad-*, /opt/nicad*, $NICAD_HOME, or via which nicad6.

Installation

Option A — Install the pre-built VSIX (recommended)

Grab clear-1.0.0.vsix from the Releases page, then:

code --install-extension clear-1.0.0.vsix --force

In VS Code: Ctrl+Shift+P → Developer: Reload Window.

Option B — Build from source

git clone https://github.com/srlabUsask/CLEAR-Clone-Localized-Embedding-Augmented-Refactoring.git
cd clear
npm install
npx @vscode/vsce package
code --install-extension clear-1.0.0.vsix --force

For active development, open the folder in VS Code and press F5 to launch the Extension Development Host.

First run

CLEAR verifies TXL and NiCad are available before the wizard starts. If either check fails, the wizard shows a "Prerequisites not found" panel with the relevant install command.

Click the CLEAR icon in the Activity Bar.
The 4-step wizard guides you through:
- NiCad path (auto-detected).
- Language + granularity (functions / blocks / classes).
- Clone type (Type 1 / 2c / 3-1 / default near-miss).
- AI provider — Ollama (local) or OpenAI / Anthropic (cloud).
Click Detect Clones in the main view. NiCad runs against the workspace; the report shows clone classes ranked by refactor priority.
Click Refactor with AI on any class to open the Refactoring Assistant with a diff preview, then Apply or Reject.

Daily use

Action	How
Detect clones	Detect Clones in the CLEAR panel, or `Ctrl+Shift+P → Detect Code Clones`
Inspect a clone class	Click the class header. The score badge tooltip shows the per-factor breakdown.
Refactor	Refactor with AI on any class — opens the diff preview.
Apply / Reject	Buttons in the Refactoring Assistant. Reject prompts for an optional reason.
Switch AI provider	Click the CLEAR: <provider> item in the status bar
Toggle compile verification	Click the CLEAR Verify: on/off status bar item
Inspect LLM trace	`Ctrl+Shift+P → CLEAR: Show LLM Trace`
Warm up local model	`Ctrl+Shift+P → CLEAR: Warm Up Local Model`

On file save with nicad.detectOnSave enabled (default), NiCad re-runs in the background and clones in the saved file appear as inline diagnostics with a "Refactor this clone with AI" Quick Fix lightbulb.

Settings

Setting	Default	Description
`nicad.granularity`	`functions`	functions / blocks / classes
`nicad.language`	`java`	primary language
`nicad.modelProvider`	`openai`	`openai` / `ollama` / `anthropic`
`nicad.ollamaEndpoint`	`http://localhost:11434`	Ollama API endpoint
`nicad.ollamaModel`	`qwen2.5-coder:7b`	chat model for refactoring
`nicad.ollamaEmbeddingModel`	`nomic-embed-text`	embedding model for retrieval
`nicad.ragEnabled`	`true`	toggle RAG retrieval
`nicad.detectOnSave`	`true`	re-run NiCad on file save
`nicad.jitMode`	`true`	surface in-file clones as diagnostics
`nicad.verifier.enabled`	`false`	compile-verify suggestions before display
`nicad.timeout`	`300`	NiCad timeout (seconds)

Full settings list available in Ctrl+, → search "nicad".

Commands

Detect Code Clones — run NiCad on the workspace
Refactor Selected Clones — analyze the last detected clones
Send Clones to Refactoring Assistant — open the diff preview
Test Ollama Connection — ping Ollama and list models
CLEAR: Reset Setup Wizard — clear configuration and re-run the wizard
CLEAR: Clear Learned Refactoring Patterns — wipe accepted/rejected patterns
CLEAR: Switch AI Provider — change provider/model live
CLEAR: Warm Up Local Model — preload Ollama weights
CLEAR: Show LLM Trace — view full request/response history

Troubleshooting

Symptom	Fix
Setup wizard says "TXL not found"	`sudo apt install txl` (Debian/Ubuntu) or download from txl.ca. Verify with `which txl`.
Setup wizard says "NiCad executable not found"	Symlink: `ln -s /path/to/NiCad-6.2 ~/NiCad-6.2`, set `$NICAD_HOME`, or enter the path manually in the wizard.
Detect Clones finds nothing	Either the workspace language doesn't match `nicad.language` (reset the wizard via `Ctrl+Shift+P → CLEAR: Reset Setup Wizard`), or NiCad's tools aren't compiled (`cd ~/NiCad-6.2 && make`).
`nicad6: line 11: ./scripts/NiCadPair: No such file or directory`	NiCad's shell script uses relative paths; run it from its own directory (CLEAR handles this internally).
Modern GCC fails to compile NiCad	Run `sed -i 's/^\tgcc -w -O /\tgcc -w -O -std=gnu89 -fcommon /' tools/Makefile` in `NiCad-6.2` before `make`.
Ollama is "100% CPU" despite having a GPU	You installed via snap, which is sandboxed. Reinstall via `curl -fsSL https://ollama.com/install.sh \| sh` and verify with `ollama ps`.
First refactoring on Ollama is very slow	Cold model load (5–30 s). Run `Ctrl+Shift+P → CLEAR: Warm Up Local Model` before use.
Java verifier always returns `inconclusive`	Single-file `javac` can't resolve cross-class references. Compile the project once (`mvn compile` / `./gradlew classes`) — CLEAR auto-detects `target/classes` / `build/classes/java/main`. Or set `nicad.verifier.javacClasspath` explicitly.
Anthropic API returns HTTP 404	The configured model has been retired. Pick a current one via `Ctrl+Shift+P → CLEAR: Switch AI Provider`.
`CLEAR LLM Trace` channel is empty	Triggered lazily on first LLM call. Confirm `nicad.llmTrace.enabled: true`, or force-reveal via `Ctrl+Shift+P → CLEAR: Show LLM Trace`.

Development

git clone https://github.com/srlabUsask/CLEAR-Clone-Localized-Embedding-Augmented-Refactoring.git
cd clear
npm install
npm test                                  # 138 unit tests
npx @vscode/vsce package                  # builds clear-1.0.0.vsix
code --install-extension clear-1.0.0.vsix --force

The bundled samples in examples/sample-{java,python,c}-project/ contain small projects with intentional cross-file clones. Open one as a folder, run Detect Clones, and you should see a handful of ranked classes.

Issues and PRs welcome at https://github.com/srlabUsask/CLEAR-Clone-Localized-Embedding-Augmented-Refactoring.git. Please run npm test before opening a PR.

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.vscode		.vscode
examples		examples
media		media
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.vscodeignore		.vscodeignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
OLLAMA_SETUP.md		OLLAMA_SETUP.md
README.md		README.md
TESTING.md		TESTING.md
eval-results.json		eval-results.json
install.sh		install.sh
loading.html		loading.html
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

CLEAR: Clone-Localized, Embedding-Augmented Refactoring

Table of contents

Quick start

Requirements

Installation

Option A — Install the pre-built VSIX (recommended)

Option B — Build from source

First run

Daily use

Settings

Commands

Troubleshooting

Development

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

CLEAR: Clone-Localized, Embedding-Augmented Refactoring

Table of contents

Quick start

Requirements

Installation

Option A — Install the pre-built VSIX (recommended)

Option B — Build from source

First run

Daily use

Settings

Commands

Troubleshooting

Development

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages