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 and then deeprefine loop finish

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 Reafiner 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

Codex session

$deeprefine

Codex runs the full agent-native Reafiner 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.

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:

Copilot CLI session

/deeprefine

The agent runs the full Reafiner 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.

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

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.

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:

Commands

Model Configuration

OpenCode supports per-phase model routing via environment variables:

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

deeprefine opencode uninstall --project

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 Reafiner 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

Claude Code session

/deeprefine

Claude Code runs the full Reafiner 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.

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)

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

Installation

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