Skip to content
Back to search

ClawRec

ClawRec is a Claw-native recommender system.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rucaibox--clawrec/badge.svg)](/listings/rucaibox--clawrec)

HTML

<a href="/listings/rucaibox--clawrec"><img src="/api/listings/rucaibox--clawrec/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements

- Git - Python 3.9 or newer for evaluation utilities - An OpenClaw-compatible agent runtime with Skill support - A visible, user-authorized browser session for live observation and search

The evaluation scripts use only the Python standard library.

Clone the repository

git clone <REPOSITORY_URL> ClawRec
cd ClawRec

Install the Skills

With an OpenClaw CLI that exposes Skill installation:

for skill_dir in skills/clawrec-*; do
  openclaw skills install "$skill_dir"
done

openclaw skills check

If the runtime uses a different installation command, register every directory under `skills/` without changing its internal file structure.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 298 lines
  1. # ClawRec
  2. Official implementation and evaluation artifact for **ClawRec: A Claw-Native
  3. Recommender System**.
  4. ClawRec is an agentic recommender system that turns authorized cross-platform
  5. browser behavior into an evidence-linked user state. It plans retrieval by
  6. source role, acquires candidates through a visible browser session, curates a
  7. complementary recommendation slate, renders a local generative interface, and
  8. feeds explicit interaction signals back into the user state.
  9. ## Architecture
  10. ```mermaid
  11. flowchart LR
  12. A["Authorized browser behavior"] --> B["Unified events"]
  13. B --> C["Evidence-linked user state"]
  14. C --> D["Content planning"]
  15. D --> E["Cross-source acquisition"]
  16. E --> F["Marginal curation"]
  17. F --> G["Generative interface"]
  18. G --> H["Explicit feedback"]
  19. H --> C
  20. ```
  21. Each stage is implemented as an independent agent Skill with a narrow input and
  22. output contract:
  23. | Stage | Skill | Primary artifact |
  24. | --- | --- | --- |
  25. | Lifecycle routing | `clawrec-using-clawrec` | Selects the required stage sequence |
  26. | Behavior observation | `clawrec-observing-browser-behavior` | UnifiedEvent JSONL |
  27. | User-state synthesis | `clawrec-synthesizing-user-state` | `USER_STATE.md` |
  28. | Retrieval planning | `clawrec-making-content-plan` | `PLAN.md` |
  29. | Search orchestration | `clawrec-orchestrating-search-execution` | Search task results |
  30. | Source execution | `clawrec-executing-search-instruction` | Verified source records |
  31. | Recommendation curation | `clawrec-curating-display-data` | `display-data.json` |
  32. | Interface rendering | `clawrec-rendering-generative-interface` | Local HTML interface |
  33. | Feedback collection | `clawrec-collecting-display-feedback` | Feedback packets |
  34. The detailed artifact boundaries are documented in
  35. [`docs/architecture.md`](docs/architecture.md).
  36. ## Repository layout
  37. ```text
  38. .
  39. ├── skills/ # ClawRec method implementation
  40. ├── clawrec-simbench/
  41. │ ├── review_md/ # Simulated intent specifications
  42. │ └── cases/ # GUI-grounded event cases
  43. ├── evaluation/
  44. │ ├── prompts/ # Versioned LLM-judge prompts
  45. │ ├── scs/ # User-state evaluation
  46. │ └── trajectory/ # Final recommendation evaluation
  47. └── docs/
  48. ```
  49. ## Installation
  50. ### Requirements
  51. - Git
  52. - Python 3.9 or newer for evaluation utilities
  53. - An OpenClaw-compatible agent runtime with Skill support
  54. - A visible, user-authorized browser session for live observation and search
  55. The evaluation scripts use only the Python standard library.
  56. ### Clone the repository
  57. ```bash
  58. git clone <REPOSITORY_URL> ClawRec
  59. cd ClawRec
  60. ```
  61. ### Install the Skills
  62. With an OpenClaw CLI that exposes Skill installation:
  63. ```bash
  64. for skill_dir in skills/clawrec-*; do
  65. openclaw skills install "$skill_dir"
  66. done
  67. openclaw skills check
  68. ```
  69. If the runtime uses a different installation command, register every directory
  70. under `skills/` without changing its internal file structure.
  71. ## Quick start
  72. Run commands from the workspace where ClawRec should create its `.clawrec/`
  73. state.
  74. ### Run one full recommendation cycle
  75. 1. Open a visible browser session and sign in only to sources you authorize
  76. ClawRec to use.
  77. 2. Start the OpenClaw interactive interface:
  78. ```bash
  79. openclaw tui
  80. ```
  81. 3. Enter the following prompt in the TUI:
  82. ```text
  83. Use clawrec-using-clawrec to run one full ClawRec recommendation cycle.
  84. ```
  85. The lifecycle routes through observation, state synthesis, retrieval planning,
  86. search execution, curation, and interface rendering. Headless browsing is not
  87. used.
  88. ### Refresh state only
  89. Start `openclaw tui`, then enter:
  90. ```text
  91. Use clawrec-using-clawrec to refresh my ClawRec user state from browser behavior I authorize.
  92. ```
  93. ### Generate recommendations from an existing state
  94. Start `openclaw tui`, then enter:
  95. ```text
  96. Use clawrec-using-clawrec to generate a recommendation page from the current ClawRec user state.
  97. ```
  98. ## Expected output
  99. A successful full cycle writes the following artifacts under the active
  100. workspace:
  101. ```text
  102. .clawrec/
  103. ├── clawrec-unified-events/
  104. │ └── latest/
  105. │ ├── evidence.jsonl
  106. │ └── meta.json
  107. ├── clawrec-user-state/
  108. │ ├── USER_STATE.md
  109. │ ├── STATE_UPDATES.md
  110. │ ├── NEGATIVE_SIGNALS.md
  111. │ └── latest-update-packets.md
  112. ├── clawrec-content-plan/
  113. │ └── latest/
  114. │ └── PLAN.md
  115. ├── clawrec-search-execution/
  116. │ └── latest/
  117. │ ├── RUN.md
  118. │ ├── tasks.jsonl
  119. │ ├── results.jsonl
  120. │ ├── errors.jsonl
  121. │ └── meta.json
  122. ├── clawrec-display-data/
  123. │ └── latest/
  124. │ ├── display-data.json
  125. │ ├── candidates.jsonl
  126. │ ├── excluded.jsonl
  127. │ ├── CURATION.md
  128. │ └── meta.json
  129. └── clawrec-generative-interface/
  130. └── <session_id>/
  131. ├── content/
  132. │ └── *.html
  133. └── state/
  134. ├── displayed-cards.json
  135. └── events/
  136. ```
  137. The main rendering input, `display-data.json`, has sectioned recommendation
  138. cards:
  139. ```json
  140. {
  141. "sections": [
  142. {
  143. "label": "Section label",
  144. "topic": "Recommendation topic",
  145. "cards": [
  146. {
  147. "title": "Item title",
  148. "source": "Source name",
  149. "href": "https://example.com/item",
  150. "summary": "Why this item is useful now"
  151. }
  152. ]
  153. }
  154. ]
  155. }
  156. ```
  157. After explicit interaction collection, feedback artifacts appear under:
  158. ```text
  159. .clawrec/clawrec-feedback/latest/
  160. ├── feedback.jsonl
  161. ├── section-feedback.jsonl
  162. ├── feedback-packets.md
  163. ├── COLLECTION.md
  164. └── meta.json
  165. ```
  166. ## ClawRec-SimBench
  167. [`clawrec-simbench/`](clawrec-simbench/README.md) contains the simulated intent
  168. specifications and GUI-grounded event cases used by the evaluation protocol.
  169. Each case separates:
  170. - `input/`: evidence and constraints visible to the system;
  171. - `private/`: held-out targets available only to the evaluator.
  172. To create writable runtime cases without exposing evaluator-only files:
  173. ```bash
  174. mkdir -p .local/cases
  175. rsync -a --exclude='private/' \
  176. clawrec-simbench/cases/ \
  177. .local/cases/
  178. ```
  179. Process events in numeric order within each workspace and preserve that
  180. workspace's `.clawrec/` state between events. See
  181. [`docs/reproduction.md`](docs/reproduction.md) for the experiment boundary.
  182. ## Evaluation
  183. The repository provides two OpenAI-compatible LLM-judge pipelines.
  184. ### State Consistency Score
  185. ```bash
  186. python3 evaluation/scs/build_scs_judge_inputs.py \
  187. --cases-dir .local/cases
  188. OPENAI_API_KEY=... python3 evaluation/scs/run_scs_llm_judge.py \
  189. --model deepseek-v4-flash \
  190. --concurrency 4
  191. python3 evaluation/scs/aggregate_scs_judgments.py
  192. ```
  193. Expected aggregate outputs:
  194. ```text
  195. .local/artifacts/eval/scs/runs/<run_id>/
  196. ├── judge_inputs.jsonl
  197. ├── input_problems.jsonl
  198. ├── input_manifest.json
  199. ├── judgments.jsonl
  200. ├── raw_responses.jsonl
  201. ├── judge_errors.jsonl # Present when requests or responses fail
  202. ├── scores.csv
  203. └── summary.json
  204. ```
  205. ### Final recommendation trajectory
  206. ```bash
  207. python3 evaluation/trajectory/build_trajectory_judge_inputs.py \
  208. --cases-dir .local/cases \
  209. --k 20
  210. OPENAI_API_KEY=... python3 evaluation/trajectory/run_trajectory_llm_judge.py \
  211. --model deepseek-v4-flash \
  212. --concurrency 4
  213. python3 evaluation/trajectory/aggregate_trajectory_judgments.py
  214. ```
  215. Expected aggregate outputs:
  216. ```text
  217. .local/artifacts/eval/trajectory/runs/<run_id>/
  218. ├── judge_inputs.jsonl
  219. ├── input_problems.jsonl
  220. ├── input_manifest.json
  221. ├── judgments.jsonl
  222. ├── raw_responses.jsonl
  223. ├── judge_errors.jsonl # Present when requests or responses fail
  224. ├── card_scores.csv
  225. ├── scores.csv
  226. └── summary.json
  227. ```
  228. Set `OPENAI_BASE_URL`, `OPENAI_API_KEY`, and `OPENAI_MODEL` to use another
  229. OpenAI-compatible endpoint. Detailed options are listed in
  230. [`evaluation/README.md`](evaluation/README.md).
  231. ## Results
  232. ClawRec achieves an NDCG@20 of **0.6134** and a Hit@20 of **0.6944** on
  233. ClawRec-SimBench. See the paper for comparisons, ablations, and diagnostics.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.