mcpField
S
sherlog

sherlog

github.com/catoncatAgent workflows2842 installsUpdated 3w ago
Repository

About sherlog

Sherlog is a skill for searching and reviewing local agent session history with `shlog`. It explains how to select queries, verify evidence and coverage, and report uncertainty without overstating what the history proves.

Key features

  1. 01Guidance for `find`, `list`, and `stats`
  2. 02Read-only session history search
  3. 03Evidence-based history review
  4. 04Coverage checks for completeness claims
  5. 05Selector and error handling guidance

Use cases

  1. 01Find an earlier discussion by topic or phrase
  2. 02Verify details in a session transcript
  3. 03Assess whether a history search is complete

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/catoncat/sherlog --skill sherlog

After installing, type/sherlogin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
advanced-queries.md
cli-surface.md
failure-cookbook.md
json-schema.md
progressive-workflow.md

Details

From the project README

Sherlog

用 shlog 检索本机 agent session 历史。命令语法与默认值以 shlog --help 和 shlog <command> --help 为准；本 skill 只给 help 教不了的检索决策。

主循环

  1. 定位：按问题选 find / list / stats（usage 看 --help）。主题或关键词明确用 find；已知项目/时间、关键词弱用 list。默认不加 --json：文本输出每条 candidate 一个短块（日期 · source · cwd · 锚点、标题、摘要、命中片段）加一条可直接执行的 read: 命令，10 条约 2k token；--json 是同一结果的完整 contract，只在需要程序化解析字段时使用。前几条都不像时换更独特的词或 identifier（路径、命令、报错短语），而不是把整句自然语言追加进去。完成：有可读取的 candidate identity 和明确 scope。
  2. 取证：原样执行 candidate 的 read: 行（--json 时为 evidenceRead.command），或自行 read-range / read-page。完成：每个历史事实都有 read-* 返回内容支持；hasMore=true 且目标上下文未解决时继续翻页，抽样则说明边界。
  3. 证明范围：只在回答依赖 latest / completeness / miss 结论时，对相同 selector 跑 status --json。完成：按 recommendedAction 决定 query、同范围 sync，或说明无法证明。
  4. 报告：不确定处明确说明；不伪造完整性或不存在的证据。

直接执行匹配任务的只读命令，不用 status / sync 预检；失败时按宿主权限原样执行 recommended（或唯一）typed nextAction.commands[].command。不要自行重建命令，也不要把 cwd/root/selector 查询扩成 all(root)。

不变量

  • find/read/list/stats/cold list 只读；sync 是唯一 content writer；cold add/remove 只写 retention state。只读命令不隐式 sync/migrate。
  • 内容事实只能来自 read-*；title/summary/snippet/profile 命中只是 candidate。文本输出的 coverage: 行是 stored proof，不是 freshness。
  • message anchor 走 read-range；profile-only 命中不伪造 seq；anchor_not_found 时按 nextAction 回退。
  • find --cwd 构造 exact cwd selector；list --cwd 是 substring filter，两者 coverage 语义不同。
  • latest/completeness/miss 结论必须匹配同 selector 的 coverage proof。
  • 破坏性操作（sync --prune、cold remove）只在用户明确表达删除意图后执行。
  • 跨 source 读取使用 find 返回的 sessionRef，不从 UUID 猜 source。

References（按触发条件加载）

  • 遇到 typed error / zero results / 迁移升级：references/failure-cookbook.md
  • 需要跨命令语义陷阱或 selector 形状：references/cli-surface.md
  • 需要解析 evidenceRead / coverage / nextAction 字段：references/json-schema.md
  • 需要具体场景示例与完成标准：references/progressive-workflow.md
  • 需要 query/tokenizer 或只读 metadata SQL 细节：references/advanced-queries.md

Comments

Markdown supported