refactor: decouple Coin Hunter from Hermes for cross-platform usage
- Add unified coinhunter_shim.py that accepts subcommands (pre/gate/review/rotate-log) - Update SKILL.md gate pseudocode to read optional ~/.coinhunter/platform.json - Split cron/setup examples into Hermes and OpenClaw variants across docs - Introduce platform.json schema in user-data-layout.md - Remove stale auto_trader.py/run_trader.sh references from auto-trading-guide.md - Keep legacy shims as backward-compatible wrappers
This commit is contained in:
106
README.md
106
README.md
@@ -37,29 +37,30 @@
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[System crontab<br/>every 5 min] -->|local python| B[External Gate]
|
||||
A[System crontab<br/>every 5 min] -->|coinhunter gate| B[External Gate]
|
||||
B --> C{should_analyze?}
|
||||
C -->|No| D[Silent exit<br/>zero cost]
|
||||
C -->|Yes| E[Trigger Hermes cron]
|
||||
C -->|Yes| E[Trigger platform cron]
|
||||
E --> F[LLM Deep Analysis]
|
||||
F --> G[smart_executor.py]
|
||||
F --> G[coinhunter exec]
|
||||
G --> H[Binance API]
|
||||
F --> I[logger.py]
|
||||
F --> I[coinhunter logs]
|
||||
I --> J[~/.coinhunter/logs/]
|
||||
K[review_engine.py<br/>hourly] --> J
|
||||
K[coinhunter recap<br/>hourly] --> J
|
||||
```
|
||||
|
||||
### Key components
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `scripts/market_probe.py` | Market data fetcher (ccxt + web search) |
|
||||
| `scripts/coinhunter_precheck.py` | **Lightweight gate** — computes adaptive thresholds and decides if analysis is needed |
|
||||
| `scripts/coinhunter_external_gate.py` | Optional **system-crontab wrapper** that runs the gate entirely outside Hermes |
|
||||
| `scripts/coinhunter_cli.py` | Unified CLI entrypoint for CoinHunter operations |
|
||||
| `scripts/smart_executor.py` | Order execution layer with idempotency & precision validation |
|
||||
| `scripts/logger.py` | Structured JSONL logging of every decision & trade |
|
||||
| `scripts/review_engine.py` | Hourly quality review & parameter optimization |
|
||||
All operations go through the installed `coinhunter` CLI. This skill provides the framework specification, reference playbooks, and Hermes cron shims.
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `coinhunter probe` | Market data fetcher (ccxt + web search) |
|
||||
| `coinhunter pre` | **Lightweight gate** — computes adaptive thresholds and decides if analysis is needed |
|
||||
| `coinhunter gate` | Optional **system-crontab wrapper** that runs the gate entirely outside Hermes |
|
||||
| `coinhunter exec` | Order execution layer with idempotency & precision validation |
|
||||
| `coinhunter review` | Generate compact review context for the agent |
|
||||
| `coinhunter recap` | Hourly quality review & parameter optimization |
|
||||
|
||||
---
|
||||
|
||||
@@ -72,10 +73,21 @@ git clone https://github.com/TacitLab/coinhunter.git
|
||||
cd coinhunter
|
||||
```
|
||||
|
||||
### 2. Set up your runtime directory
|
||||
### 2. Install the CLI tool
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.coinhunter/state ~/.coinhunter/logs ~/.hermes/scripts
|
||||
pipx install coinhunter
|
||||
# verify
|
||||
coinhunter --help
|
||||
```
|
||||
|
||||
### 3. Set up your runtime directory
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.coinhunter/state ~/.coinhunter/logs
|
||||
# Also create your platform's scripts directory if needed:
|
||||
# mkdir -p ~/.hermes/scripts
|
||||
# mkdir -p ~/.openclaw/scripts
|
||||
```
|
||||
|
||||
Create your initial `positions.json`:
|
||||
@@ -89,30 +101,64 @@ Create your initial `positions.json`:
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Build the gate
|
||||
### 4. Deploy the shims
|
||||
|
||||
Copy the precheck blueprint from [`SKILL.md`](./SKILL.md) into `~/.hermes/scripts/coinhunter_precheck.py`.
|
||||
It is ~100 lines of pure Python: reads your state, hashes positions, checks adaptive price/PnL thresholds, and outputs a tiny JSON decision.
|
||||
**Option A — unified shim (recommended for new setups and cross-platform):**
|
||||
|
||||
### 4. Configure the Hermes cron job
|
||||
Copy the single unified shim into your platform's scripts directory. It accepts the subcommand as its first argument:
|
||||
|
||||
```bash
|
||||
# Hermes
|
||||
cp templates/coinhunter_shim.py ~/.hermes/scripts/coinhunter_shim.py
|
||||
|
||||
# OpenClaw
|
||||
cp templates/coinhunter_shim.py ~/.openclaw/scripts/coinhunter_shim.py
|
||||
```
|
||||
|
||||
**Option B — legacy shims (existing Hermes users, unchanged behavior):**
|
||||
|
||||
The original individual shims are still provided for backward compatibility:
|
||||
|
||||
```bash
|
||||
cp templates/coinhunter_precheck_shim.py ~/.hermes/scripts/coinhunter_precheck.py
|
||||
cp templates/coinhunter_external_gate_shim.py ~/.hermes/scripts/coinhunter_external_gate.py
|
||||
cp templates/coinhunter_review_context_shim.py ~/.hermes/scripts/coinhunter_review_context.py
|
||||
cp templates/rotate_external_gate_log_shim.py ~/.hermes/scripts/rotate_external_gate_log.py
|
||||
```
|
||||
|
||||
### 5. Configure the platform cron job
|
||||
|
||||
**Hermes example (using the unified shim):**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "coinhunter-trade",
|
||||
"schedule": "*/15 * * * *",
|
||||
"prompt": "You are Coin Hunter. If injected context says should_analyze=false, respond with exactly [SILENT]. Otherwise read positions.json, run the scientific checklist, decide HOLD/SELL/REBALANCE/BUY, and execute.",
|
||||
"script": "~/.hermes/scripts/coinhunter_precheck.py",
|
||||
"script": "coinhunter_shim.py pre",
|
||||
"deliver": "telegram",
|
||||
"model": "kimi-for-coding"
|
||||
}
|
||||
```
|
||||
|
||||
### 5. (Optional) Add the external gate
|
||||
**OpenClaw example:**
|
||||
|
||||
Put this in your system crontab to run the precheck every **5 minutes** without ever waking the LLM:
|
||||
```json
|
||||
{
|
||||
"id": "coinhunter-trade",
|
||||
"schedule": "*/15 * * * *",
|
||||
"prompt": "You are Coin Hunter. If injected context says should_analyze=false, respond with exactly [SILENT]. Otherwise read positions.json, run the scientific checklist, decide HOLD/SELL/REBALANCE/BUY, and execute.",
|
||||
"script": "coinhunter_shim.py pre",
|
||||
"deliver": "webhook"
|
||||
}
|
||||
```
|
||||
|
||||
### 6. (Optional) Add the external gate
|
||||
|
||||
Put this in your system crontab to run the gate every **5 minutes** without ever waking the LLM:
|
||||
|
||||
```cron
|
||||
*/5 * * * * /usr/bin/python3 /home/user/.hermes/scripts/coinhunter_external_gate.py >> /home/user/.coinhunter/logs/external_gate.log 2>&1
|
||||
*/5 * * * * /usr/bin/env coinhunter gate >> /home/user/.coinhunter/logs/external_gate.log 2>&1
|
||||
```
|
||||
|
||||
---
|
||||
@@ -160,11 +206,13 @@ See the full step-by-step gate blueprint in [`SKILL.md`](./SKILL.md).
|
||||
coinhunter/
|
||||
├── README.md # You are here
|
||||
├── SKILL.md # Full framework spec + gate blueprint
|
||||
├── scripts/
|
||||
│ ├── market_probe.py # Market data fetcher
|
||||
│ ├── init_user_state.py # Bootstrap helper
|
||||
│ ├── auto_trader.py # Reference trading loop
|
||||
│ └── ... # Your gate scripts live in ~/.hermes/scripts/
|
||||
├── CLAUDE.md # Guidance for Claude Code
|
||||
├── templates/ # Platform cron shims (call the installed coinhunter CLI)
|
||||
│ ├── coinhunter_shim.py # Unified cross-platform shim (recommended)
|
||||
│ ├── coinhunter_precheck_shim.py
|
||||
│ ├── coinhunter_external_gate_shim.py
|
||||
│ ├── coinhunter_review_context_shim.py
|
||||
│ └── rotate_external_gate_log_shim.py
|
||||
└── references/
|
||||
├── short-term-trading-framework.md
|
||||
├── review-template.md
|
||||
|
||||
Reference in New Issue
Block a user