Introduction¶
The most common waste in long AI tasks is idle spinning: the same probe script is renamed and run repeatedly, failed commands are retried unchanged, and one or two hours pass with zero file changes. The plugin monitors these behaviors through hooks, and once a match is detected, forces the AI to perform a self-review against the original goal, deciding whether to continue, change its approach, or report.
Installation¶
DeepSeek Harness¶
The plugin page supports installation by directly pasting a Git repository URL. This repository is also a cordis bundle. It observes behavioral rhythm through tools/result / session/event events and injects reminders via agent.inject(), without requiring Python.
ZCode¶
The system must have a usable python command (3.8+). If the executable name is different, modify the four python entries in hooks/hooks.json.
Core Features¶
Trigger Detection¶
The plugin registers four session hooks. It does not intercept any tool calls; it only observes:
1. Exact duplicate command repetition: three out of the last five commands are exactly identical.
2. Similar commands: after normalization, three out of the last five are identical (filename sequence numbers are stripped).
3. Ultra-long zero output: the session has lasted more than 25 minutes with no file modifications.
4. Dense invocation zero output: there have been 30 invocations since the last reminder with no file modifications.
5. Failure loop: a tool has failed three consecutive times.
Local Clock Anchor¶
AI cannot reliably estimate duration. During idle runs, the hook injects real local time and requires the AI to use the actual clock as the basis for all duration estimates and reports. The interval starts at 5 minutes and doubles each time (5→10→20→40, capped at 60).
Independent Reviewer¶
When the idle-spin reminder triggers, an LLM reviewer is called in an independent context. It outputs a strict JSON verdict (on-track / drifting / stuck). Enabled by default on DSH (reuses the session llm service), disabled by default on ZCode (requires llm_api_key configuration).
Third Channel¶
It moves the review entirely out of the host and lets an independent process poll. It is disabled by default because it consumes the user’s own API quota. It is dispatched only at the final escalation level (the third reminder in the same session still does not improve) and after explicit configuration.
Slash Commands¶
/lookup-review— Manually trigger a full “look up” self-review./lookup-status— View the plugin’s monitoring statistics and verdicts for the current session./lookup-config— View / modify threshold configuration./lookup-watch— Manage the independent review watcher for the third channel.
Configuration and Files¶
Configuration file paths: ~/.zcode/ai-look-up. or <project>/.zcode/ai-look-up..
Configuration item precedence: built-in defaults ← project configuration ← environment variables.
Differences Between the Two Sides¶
| Capability | ZCode (Python) | DeepSeek Harness (JS) |
|---|---|---|
| Trigger detection | ✅ | ✅ |
| Local clock anchor | ✅ | ✅ |
| Independent reviewer | Requires API key (default off) | Reuses session (default on) |
| Third channel | ✅ | ✅ |
| State storage | Persisted to disk | In-memory (lost on restart) |
| LLM configuration | Applied | Not read (model follows session) |
Notes¶
- Python requirement: The ZCode side requires Python 3.8+; the DSH side does not require Python.
- API configuration:
llm_api_key/llm_api_base/llm_model/llm_timeout_secapply only to the ZCode side. - Third channel: Disabled by default; explicitly enabling it consumes the user’s API quota.
- State persistence: DSH-side state is in-memory and is lost when the host restarts.
