deeprefine-skill
DeepRefine workflow for refining Graphify / LLM-Wiki knowledge graphs inside Gemini CLI.
Open source Open in the app JSON README (API)
About
DeepRefine workflow for refining Graphify / LLM-Wiki knowledge graphs inside Gemini CLI.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- hkust-knowcomp
- Origin
- gemini
- Category
- ferramentas
- Version
- 1.0.0
- Stars
- 93
- Forks
- 7
- Open pull requests
- 2
- Last push
- 2026-08-23T11:40:54Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
hkust-knowcomp/deeprefine-skill
README
<div align="center">
# DeepRefine-Skill
<table style="border: none; margin: 0 auto; padding: 0; border-collapse: collapse;">
<tr>
<td align="center" style="vertical-align: middle; padding: 10px; border: none; width: 250px;">
<img src="./assets/icons3.png" alt="DeepRefine Logo" width="200" style="margin: 0; padding: 0; display: block;"/>
</td>
<td align="left" style="vertical-align: middle; padding: 10px 0 10px 30px; border: none;">
<pre style="font-family: 'Courier New', monospace; font-size: 16px; color: #0EA5E9; margin: 0; padding: 0; text-shadow: 0 0 10px #0EA5E9, 0 0 20px rgba(14,165,233,0.5); line-height: 1.2; transform: skew(-1deg, 0deg); display: block;">██████╗ ███████╗███████╗██████╗ ██████╗ ███████╗███████╗██╗███╗ ██╗███████╗
██╔══██╗██╔════╝██╔════╝██╔══██╗██╔══██╗██╔════╝██╔════╝██║████╗ ██║██╔════╝
██║ ██║█████╗ █████╗ ██████╔╝██████╔╝█████╗ █████╗ ██║██╔██╗ ██║█████╗
██║ ██║██╔══╝ ██╔══╝ ██╔═══╝ ██╔══██╗██╔══╝ ██╔══╝ ██║██║╚██╗██║██╔══╝
██████╔╝███████╗███████╗██║ ██║ ██║███████╗██║ ██║██║ ╚████║███████╗
╚═════╝ ╚══════╝╚══════╝╚═╝ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝╚══════╝</pre>
</td>
</tr>
</table>
[](https://pypi.org/project/deeprefine-cli/0.2.0/)
[](https://pypi.org/project/deeprefine-cli/0.2.0/)
[](https://arxiv.org/pdf/2605.10488)
[](https://github.com/HKUST-KnowComp/DeepRefine)
</div>
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](https://github.com/safishamsi/graphify)**) knowledge base.
<p align="center">
<img src="assets/demo-typing-deeprefine.svg" alt="Demo: /deeprefine" />
</p>
It refines your graphify knowledge graph for better future retrieval and Q&A quality.
Supported agent frameworks:
<p>
<a href="https://cursor.com" title="Cursor"><img src="./assets/cursor_CUBE_25D.png" alt="Cursor" height="40"/></a>
<a href="https://github.com/google-gemini/gemini-cli" title="Gemini CLI"><img src="./assets/gemini-cli-icon_full-color@4x.png" alt="Gemini CLI" height="40"/></a>
<a href="https://docs.github.com/en/copilot" title="GitHub Copilot CLI" style="text-decoration: none; color: inherit;"><img src="./assets/github-copilot__1_-removebg-preview.png" height="40" style="vertical-align: middle;" alt="Copilot Icon" /></a>
<a href="https://openai.com/codex/" title="Codex CLI" style="text-decoration: none; color: inherit;"><img src="./assets/codex-color.png" height="40" style="vertical-align: middle;" alt="Copilot Icon" /></a>
<a href="https://opencode.ai/" title="OpenCode" style="text-decoration: none; color: inherit;"><img src="./assets/opencode-logo-dark.png" height="40" style="vertical-align: middle;" alt="Copilot Icon" /></a>
<a href="https://claude.com/product/claude-code" title="Claude Code" style="text-decoration: none; color: inherit;"><img src="./assets/claudecode-color.png" height="40" style="vertical-align: middle;" alt="Copilot Icon" /></a>
</p>
---
## 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
```bash
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)
```bash
/graphify .
/graphify ./ --wiki
/graphify query "your question 1"
/graphify query "your question 2"
# ..
/deeprefine
```
### What `/deeprefine` does now (default queue behavior)
<details>
<summary><strong>Procedures:</strong></summary>
When you run `/deeprefine`, it should follow this order:
1. `deeprefine history sync-memory`
- import queries from `graphify-out/memory/query_*.md`
- write to `graphify-out/.deeprefine/history.jsonl`
2. load pending queries from `history.jsonl` (`refined != true`)
3. refine pending queries sequentially
4. for refinement-path queries, generate `<refinement>` actions and run `deeprefine review`
5. stop in dry-run mode and show the review report; do **not** modify `graph.json` yet
6. only after user approval, run `deeprefine apply --refresh-wiki` and then `deeprefine loop finish`
</details>
### Agent artifacts
```text
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
├── checkpoints/graph.checkpoint.<seq>.json # post-state graph after each apply
├── checkpoints.json # checkpoint timeline registry
├── 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:
```text
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
<details>
<summary><strong>Setup, commands, and session usage</strong></summary>
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
```bash
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:
```text
$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
```text
$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`](docs/codex.md) for details.
</details>
---
## Copilot CLI Integration
<details>
<summary><strong>Setup, commands, and session usage</strong></summary>
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
```bash
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:
```text
/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
```text
/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:
```text
[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.
</details>
---
## Gemini CLI Integration
<details>
<summary><strong>Setup, commands, and session usage</strong></summary>
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
```bash
cd /path/to/DeepRefine-Skill
pip install -e .
deeprefine gemini link
```
`deeprefine gemini link` calls Gemini CLI's official extension manager:
```bash
gemini extensions link /path/to/DeepRefine-Skill
```
Restart Gemini CLI after linking. Then check:
```text
/extensions list
/commands list
```
Expected commands:
```text
/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
```bash
gemini
```
Then run:
```text
/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`](docs/gemini-cli.md) for details.
</details>
## OpenCode Integration
<details>
<summary><strong>Setup, commands, and session usage</strong></summary>
### 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
```bash
# 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:
1. **Parallel query processing** — Multiple pending queries are dispatched to parallel subagents via `task()`, reducing wall-clock time to ~1 query's duration
2. **Phase-specific model routing** — Binary judgement uses a cheap model; complex abduction/refinement uses a strong model
3. **Structured progress tracking** — `todowrite()` replaces text checklists, enabling real-time progress visibility and cross-session resumption
4. **5-Oracle parallel review** — Five specialized oracle subagents audit refinement actions from orthogonal angles (completeness, correctness, safety, consistency, edge-cases) before any graph mutation
5. **Post-apply auto-verification** — After applying refinement actions, the original query is re-run to confirm the graph fix actually resolved the issue
6. **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
```bash
deeprefine opencode uninstall --project
```
</details>
---
## Claude Code Integration
<details>
<summary><strong>Setup, commands, and session usage</strong></summary>
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
```bash
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:
```text
/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
```text
/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.
</details>
---
## Terminal CLI (FAISS + API/vLLM)
<details>
<summary><strong>Requirements, environment, workflow, and commands</strong></summary>
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)
```bash
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
```bash
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` |
```bash
deeprefine --help
# Expect: cursor, copilot, codex, claude, opencode, gemini, history, index, refine, review, apply, loop
```
</details>
---
## License
MIT — see [LICENSE](./LICENSE).