DeepRefine-Skill

██████╗ ███████╗███████╗██████╗ ██████╗ ███████╗███████╗██╗███╗   ██╗███████╗
██╔══██╗██╔════╝██╔════╝██╔══██╗██╔══██╗██╔════╝██╔════╝██║████╗  ██║██╔════╝
██║  ██║█████╗  █████╗  ██████╔╝██████╔╝█████╗  █████╗  ██║██╔██╗ ██║█████╗
██║  ██║██╔══╝  ██╔══╝  ██╔═══╝ ██╔══██╗██╔══╝  ██╔══╝  ██║██║╚██╗██║██╔══╝
██████╔╝███████╗███████╗██║     ██║  ██║███████╗██║     ██║██║ ╚████║███████╗
╚═════╝ ╚══════╝╚══════╝╚═╝     ╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝╚═╝  ╚═══╝╚══════╝

DeepRefine-Skill plugs into agent workflows and use a single command /deeprefine in your agent (Cursor, Copilot CLI, Gemini CLI, Codex, OpenCode, Claude Code) to refine and evolve your LLM-Wiki (e.g., graphify) knowledge base.

It refines your graphify knowledge graph for better future retrieval and Q&A quality.

Supported agent frameworks:

News

[2026/7/10] v0.2.0 - Claude Code and OpenCode adapters: deeprefine claude install / deeprefine opencode install, bundled skill + command templates.
[2026/7/3] v0.1.9 - Release with Codex, Copilot CLI, and Gemini CLI skills bundled; dry-run-first refinement, evidence-aware action review (HIGH/MEDIUM/LOW), ambiguous-node warnings, and LOW-confidence apply guard.
[2026/6/24] v0.1.9 - Codex skill supported.
[2026/6/18] v0.1.9 - Gemini CLI and Copilot CLI supported.
[2026/6/17] v0.1.9 - Added dry-run-first refinement, evidence-aware action review, ambiguous-node warnings, and LOW-confidence apply guard.
[2026/6/15] v0.1.8 - Aligned interaction memory with LLM-Wiki (graphify) and fixed the single query refinement issue.
[2026/6/2] v0.1.7 — Cursor skill + deeprefine refine with configurable API. And strict DeepRefine agent loop.

Agent CLI (Recommended)

This is the default mode and the main workflow for this project.

One-time setup

pip install deeprefine-cli graphifyy

cd /path/to/your-kb-project
graphify cursor install

# for Cursor
deeprefine cursor install
# for Copilot CLI
deeprefine copilot install
# for Gemini CLI
deeprefine gemini install # or deeprefine gemini link
# for Codex
deeprefine codex install
# for Claude Code
deeprefine claude install
# for OpenCode
deeprefine opencode install

After upgrading the package, run the command again to refresh local skill files.

Typical session (Agent CLI)

/graphify .
/graphify ./ --wiki
/graphify query "your question 1"
/graphify query "your question 2"
# ..
/deeprefine

What `/deeprefine` does now (default queue behavior)

Procedures:

When you run /deeprefine, it should follow this order:

deeprefine history sync-memory
- import queries from graphify-out/memory/query_*.md
- write to graphify-out/.deeprefine/history.jsonl
load pending queries from history.jsonl (refined != true)
refine pending queries sequentially
for refinement-path queries, generate <refinement> actions and run deeprefine review
stop in dry-run mode and show the review report; do not modify graph.json yet
only after user approval, run deeprefine apply --refresh-wiki and then deeprefine loop finish

Agent artifacts

graphify-out/
├── graph.json                              # graphify main graph; unchanged until apply approval
├── memory/
│   └── query_*.md                          # graphify query logs (sync source)
└── .deeprefine/
    ├── history.jsonl                       # DeepRefine-maintained history queue
    ├── graph.json.bak                      # backup before first apply in this run
    ├── loop_trace_<query_id>.json          # per-query loop audit trace
    ├── refinement_results_<YYYYMMDD>.jsonl # per-day run log
    ├── refinement_actions_*.txt            # optional; only when refinement path is taken
    ├── proposed_refinement_actions_*.txt    # CLI dry-run proposed actions
    ├── proposed_refinement_review_*.md      # evidence-aware review report
    └── proposed_refinement_review_*.json    # optional structured review report

Agent-related commands

Run from your KB project root.

Command	Description
`deeprefine cursor install`	Install `/deeprefine` skill for Cursor (`.cursor/skills/deeprefine/`)
`deeprefine cursor install --user`	Install Cursor skill for all projects (`~/.cursor/skills/`)
`deeprefine copilot install`	Install `/deeprefine` skill for Copilot CLI (`.github/skills/deeprefine/`)
`deeprefine copilot install --user`	Install Copilot CLI skill for all projects (`~/.copilot/skills/`)
`deeprefine copilot uninstall`	Remove Copilot CLI skill
`deeprefine codex install`	Install `$deeprefine` skill for Codex (`.agents/skills/deeprefine/`)
`deeprefine codex install --user`	Install Codex skill for all projects (`~/.codex/skills/deeprefine/`)
`deeprefine codex uninstall`	Remove Codex skill
`deeprefine claude install`	Install `/deeprefine` skill for Claude Code (`.claude/skills/deeprefine/`)
`deeprefine claude install --user`	Install Claude Code skill for all projects (`~/.claude/skills/deeprefine/`)
`deeprefine claude uninstall`	Remove the Claude Code skill
`deeprefine opencode install`	Install `/deeprefine` skill + commands for OpenCode (`.opencode/`)
`deeprefine opencode install --user`	Install OpenCode skill for all projects (`~/.opencode/`)
`deeprefine opencode uninstall`	Remove the OpenCode skill and commands
`deeprefine gemini path`	Print the extension root used for Gemini CLI
`deeprefine gemini link`	Link the current source checkout with `gemini extensions link`
`deeprefine gemini install`	Install the bundled extension with `gemini extensions install`
`deeprefine gemini install --copy-only`	Manual fallback copy to `~/.gemini/extensions/deeprefine-skill`
`deeprefine gemini uninstall`	Remove the extension with Gemini CLI's manager
`deeprefine history sync-memory`	Import `graphify-out/memory/query_*.md` into DeepRefine history
`deeprefine history list --pending`	Show unrefined queue
`deeprefine loop init --query "..."`	Create `loop_trace_<id>.json` template
`deeprefine loop validate --trace-file T`	Validate trace against DeepRefine control flow
`deeprefine review --trace-file T --refinement-file F`	Review proposed actions with HIGH/MEDIUM/LOW evidence labels; no graph write
`deeprefine apply --refresh-wiki --trace-file T --refinement-file F`	Apply actions and regenerate `graphify-out/wiki` from the refined graph; graph + Wiki are committed together
`deeprefine apply --refresh-wiki --allow-low-confidence --trace-file T --refinement-file F`	Refresh the Wiki while explicitly overriding the LOW-confidence guard
`deeprefine loop finish --trace-file T [--refinement-file F]`	Persist results and mark history refined

Evidence-aware review and safe apply

/deeprefine should default to dry-run-first behavior. Proposed actions are reviewed before they can modify graphify-out/graph.json. Each action is labeled:

Label	Meaning
`HIGH`	Direct graph or code evidence exists.
`MEDIUM`	k-hop context supports the action, but direct code or exact-edge evidence is missing.
`LOW`	Node names are ambiguous, too broad, cross-community, or cannot be grounded in `graph.json`.

Bare function names such as main(), run(), train(), test(), and setup() are treated as ambiguous. Prefer file-qualified names:

BAD:  insert_edge("main()", "calls", "Trainer")
GOOD: insert_edge("pretraining/pretraining_CLIP_fine-grained.py::main()", "calls", "Trainer")

deeprefine apply refuses LOW-confidence actions by default. Use --allow-low-confidence only when the user explicitly accepts the risk.

When the knowledge base was created with Graphify Wiki output, use --refresh-wiki. DeepRefine stages the refined graph, regenerates the Wiki with graphify export wiki, validates wiki/index.md, and only then replaces the production graph and Wiki. If export fails, the existing graph and Wiki remain unchanged.

Codex Integration

Setup, commands, and session usage

DeepRefine works as a Codex skill. The installer writes the Codex-specific skill file to .agents/skills/deeprefine/SKILL.md and UI metadata to .agents/skills/deeprefine/agents/openai.yaml. It also installs focused references under .agents/skills/deeprefine/references/ for the refinement workflow, LLM prompts, and trace/command details.

One-time setup

cd /path/to/your-kb-project
pip install deeprefine-cli
deeprefine codex install --project

After upgrading the package, run deeprefine codex install --project again to refresh the local skill files. Restart or reload Codex, then invoke:

$deeprefine
/deeprefine

Codex commands

Command	Description
`deeprefine codex install`	Install the Codex skill into `.agents/skills/deeprefine/`
`deeprefine codex install --user`	Install the Codex skill into `~/.codex/skills/deeprefine/`
`deeprefine codex uninstall`	Remove the Codex skill

Codex session

$deeprefine

Codex runs the full agent-native refinement loop for pending queries, stops after deeprefine review, and presents the HIGH/MEDIUM/LOW report. Reply with an explicit apply/approve message only after reviewing the proposed actions.

See docs/codex.md for details.

Copilot CLI Integration

Setup, commands, and session usage

DeepRefine works as a GitHub Copilot CLI agent skill. The skill file is installed into .github/skills/deeprefine/SKILL.md and auto-discovered by Copilot. Shell commands are pre-approved via allowed-tools: shell.

One-time setup

cd /path/to/your-kb-project
pip install deeprefine-cli
deeprefine copilot install --project

After upgrading the package, run deeprefine copilot install --project again to refresh the local skill file. Start a Copilot CLI session and reload:

/skills reload
/skills info deeprefine

Mode detection

Copilot CLI does not natively support sub-commands, so the skill uses keyword-based mode detection in the SKILL.md preamble:

Mode	Trigger keywords	Behavior
Full workflow	`/deeprefine`, "refine", "improve", "fix"	Full refinement loop; stops after dry-run review; asks for approval
Review only	"review", "check", "audit", "inspect", "dry-run"	Reads trace + refinement file; shows HIGH/MEDIUM/LOW report; no graph writes
Apply only	"approve", "apply", "write", "go ahead"	Runs `deeprefine apply` only after a prior review; requires explicit user approval in the current message

Copilot CLI session

/deeprefine

The agent runs the full refinement loop for all pending queries. For refinement-path queries, it stops after the dry-run review and asks:

[HIGH] insert_edge("trainer.py::train_epoch()", "calls", "validate()")
Evidence: Direct code evidence in trainer.py.
[MEDIUM] insert_edge("data.py::load()", "imports", "torch")
Warning: No direct code evidence found.

Apply only after review. Approve?

Reply "apply" or "go ahead" to proceed; the agent will run deeprefine apply in the follow-up turn.

Gemini CLI Integration

Setup, commands, and session usage

DeepRefine can also be used as a Gemini CLI extension. This keeps the same safe, dry-run-first DeepRefine workflow while making /deeprefine available inside Gemini CLI.

One-time setup for local development

cd /path/to/DeepRefine-Skill
pip install -e .
deeprefine gemini link

deeprefine gemini link calls Gemini CLI's official extension manager:

gemini extensions link /path/to/DeepRefine-Skill

Restart Gemini CLI after linking. Then check:

/extensions list
/commands list

Expected commands:

/deeprefine
/deeprefine:review
/deeprefine:apply

Gemini CLI commands

Command	Description
`deeprefine gemini path`	Print the extension root used for Gemini CLI
`deeprefine gemini link`	Link the current source checkout with `gemini extensions link`
`deeprefine gemini install`	Install the bundled extension with `gemini extensions install`
`deeprefine gemini install --copy-only`	Manual fallback copy to `~/.gemini/extensions/deeprefine-skill`
`deeprefine gemini uninstall`	Remove the extension with Gemini CLI's manager

For normal source development, prefer deeprefine gemini link. It makes the extension visible to /extensions list, whereas copying files alone may not register the extension in newer Gemini CLI versions.

Gemini CLI session

gemini

Then run:

/deeprefine
/deeprefine:review "Why is the graph missing the data loading path?"
/deeprefine:apply "Apply the approved refinement actions from the valid trace."

The extension files are located at the repository root and are also bundled under deeprefine_skill/gemini_extension/ for wheel installs. See docs/gemini-cli.md for details.

OpenCode Integration

Setup, commands, and session usage

Prerequisites

OpenCode CLI installed and configured
graphify CLI available on your PATH
Python 3.10+ with deeprefine-cli installed
A graphify-out/graph.json knowledge graph in your project

Setup

# Install into the current project
deeprefine opencode install --project

# Install globally (all projects)
deeprefine opencode install --user

This installs 4 files:

Destination	Source	Purpose
`.opencode/skills/deeprefine/SKILL.md`	`SKILL_OPENCODE.md`	Agent harness with 6 OpenCode-native optimizations
`.opencode/commands/deeprefine.md`	`commands/opencode/deeprefine.md`	Full workflow entrypoint (`/deeprefine`)
`.opencode/commands/deeprefine-review.md`	`commands/opencode/deeprefine-review.md`	Review-only entrypoint (`/deeprefine-review`)
`.opencode/commands/deeprefine-apply.md`	`commands/opencode/deeprefine-apply.md`	Apply-only entrypoint (`/deeprefine-apply`)

Commands

Command	Description
`/deeprefine`	Full pipeline: sync → judge → abduction → refinement → 5-Oracle review → (await approval) → apply → post-apply verify
`/deeprefine-review`	Review only: read existing actions → 5-Oracle audit → evidence review → present results
`/deeprefine-apply`	Apply only: read reviewed actions → confirm → apply → post-apply verify → finish

Model Configuration

OpenCode supports per-phase model routing via environment variables:

Variable	Phase	Purpose
`DEEPREFINE_JUDGE_MODEL`	Judgement (`<judge>Yes/No</judge>`)	Fast, cheap model for binary classification (e.g., `gpt-4o-mini`)
`DEEPREFINE_REFINE_MODEL`	Abduction + Refinement	Strong reasoning model for complex causal analysis (e.g., `claude-sonnet-4-20250514`)

If either variable is unset, the session default model is used.

OpenCode-Native Optimizations

DeepRefine on OpenCode includes 6 platform-native optimizations not available in Cursor or Cline:

Parallel query processing — Multiple pending queries are dispatched to parallel subagents via task(), reducing wall-clock time to ~1 query's duration
Phase-specific model routing — Binary judgement uses a cheap model; complex abduction/refinement uses a strong model
Structured progress tracking — todowrite() replaces text checklists, enabling real-time progress visibility and cross-session resumption
5-Oracle parallel review — Five specialized oracle subagents audit refinement actions from orthogonal angles (completeness, correctness, safety, consistency, edge-cases) before any graph mutation
Post-apply auto-verification — After applying refinement actions, the original query is re-run to confirm the graph fix actually resolved the issue
Evidence ledger — Every phase boundary writes a structured JSONL entry (graphify-out/.deeprefine/ledger.jsonl) with timestamps, artifacts, and QA results for full auditability

Uninstall

deeprefine opencode uninstall --project

Claude Code Integration

Setup, commands, and session usage

DeepRefine works as a Claude Code Agent Skill. The installer writes the Claude-specific skill file to .claude/skills/deeprefine/SKILL.md, along with independently maintained references under .claude/skills/deeprefine/references/ for the refinement workflow, LLM prompts, and trace/command details.

One-time setup

cd /path/to/your-kb-project
pip install deeprefine-cli
deeprefine claude install --project

After upgrading the package, run deeprefine claude install --project again to refresh the local skill files. Restart Claude Code, then invoke:

/deeprefine

Claude Code commands

Command	Description
`deeprefine claude install`	Install the Claude Code skill into `.claude/skills/deeprefine/`
`deeprefine claude install --user`	Install the Claude Code skill into `~/.claude/skills/deeprefine/`
`deeprefine claude uninstall`	Remove the Claude Code skill

Claude Code session

/deeprefine

Claude Code runs the full refinement loop for pending queries, stops after deeprefine review, and presents the HIGH/MEDIUM/LOW report. Reply with an explicit apply/approve message only after reviewing the proposed actions.

Terminal CLI (FAISS + API/vLLM)

Requirements, environment, workflow, and commands

Use this section when you want a pure terminal workflow without Cursor /deeprefine.

Extra requirements

DeepRefine repository installed in atlastune
Inference backend configured (API or vLLM)

conda activate atlastune
cd /path/to/DeepRefine && pip install -e .
pip install deeprefine-cli

# Optional, if DeepRefine repo is elsewhere
export DEEPREFINE_REPO=/path/to/DeepRefine

Inference environment (CLI mode)

Variable	Default
`DEEPREFINE_LLM_URL`	(empty; SDK default)
`DEEPREFINE_EMBED_URL`	(empty; SDK default)
`DEEPREFINE_API_KEY`	fallback to `OPENAI_API_KEY`
`DEEPREFINE_LLM_API_KEY`	fallback to `DEEPREFINE_API_KEY`
`DEEPREFINE_EMBED_API_KEY`	fallback to `DEEPREFINE_API_KEY`
`DEEPREFINE_MODEL`	`gpt-4.1-mini`
`DEEPREFINE_EMBED_MODEL`	`text-embedding-3-small`

Terminal workflow

cd /path/to/your-kb-project

# Option A: import from graphify memory first (recommended)
deeprefine history sync-memory
deeprefine history list --pending
deeprefine refine          # dry-run: proposed actions + review, no graph write
deeprefine refine --apply  # optional: write accepted CLI refine changes

# Option B: add one explicit query
deeprefine history add --query "your question"
deeprefine refine          # dry-run by default

Terminal commands

Command	Description
`deeprefine history add --query "..."`	Append one query to history
`deeprefine history list`	List all history rows
`deeprefine history sync-memory`	Import graphify memory queries into history
`deeprefine history list --pending`	List only unrefined queries
`deeprefine refine`	Generate proposed actions for all pending queries; dry-run by default
`deeprefine refine --query "..."`	Generate proposed actions for a single query; dry-run by default
`deeprefine refine --apply`	Persist accepted CLI refine changes to `graph.json`
`deeprefine refine --rebuild-index`	Rebuild FAISS before refine
`deeprefine index --rebuild`	Rebuild FAISS cache only

Installation

Method	Command
PyPI	`pip install deeprefine-cli==0.2.0`
Source	`pip install -e /path/to/DeepRefine-Skill`

deeprefine --help
# Expect: cursor, copilot, codex, claude, opencode, gemini, history, index, refine, review, apply, loop

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 63 Commits
assets		assets
commands		commands
deeprefine_skill		deeprefine_skill
docs		docs
scripts		scripts
skills/deeprefine		skills/deeprefine
tests		tests
.gitignore		.gitignore
GEMINI.md		GEMINI.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
SKILL.md		SKILL.md
gemini-extension.json		gemini-extension.json
pyproject.toml		pyproject.toml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

DeepRefine-Skill

News

Agent CLI (Recommended)

One-time setup

Typical session (Agent CLI)

What /deeprefine does now (default queue behavior)

Agent artifacts

Agent-related commands

Evidence-aware review and safe apply

Codex Integration

One-time setup

Codex commands

Codex session

Copilot CLI Integration

One-time setup

Mode detection

Copilot CLI session

Gemini CLI Integration

One-time setup for local development

Gemini CLI commands

Gemini CLI session

OpenCode Integration

Prerequisites

Setup

Commands

Model Configuration

OpenCode-Native Optimizations

Uninstall

Claude Code Integration

One-time setup

Claude Code commands

Claude Code session

Terminal CLI (FAISS + API/vLLM)

Extra requirements

Inference environment (CLI mode)

Terminal workflow

Terminal commands

Installation

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

What `/deeprefine` does now (default queue behavior)

Packages