coinhunter-cli

The executable CLI layer for CoinHunter.
Runtime-safe trading operations, precheck orchestration, review tooling, and market probes.

Why this repo exists

CoinHunter is evolving from a loose bundle of automation scripts into a proper installable command-line tool.

This repository is the tooling layer:

• Code and executable behavior live here.
• User runtime state lives in ~/.coinhunter/ by default.
• Hermes skills can call this CLI instead of embedding large script collections.
• Runtime paths can be overridden with COINHUNTER_HOME, HERMES_HOME, COINHUNTER_ENV_FILE, and HERMES_BIN.

In short:

• coinhunter-cli = tool
• CoinHunter skill = strategy / workflow / prompting layer
• ~/.coinhunter = user data, logs, state, reviews

Current architecture

coinhunter-cli/
├── src/coinhunter/
│   ├── cli.py                  # top-level command router
│   ├── runtime.py              # runtime paths + env loading
│   ├── doctor.py               # diagnostics
│   ├── paths.py                # runtime path inspection
│   ├── commands/               # thin CLI adapters
│   ├── services/               # orchestration / application services
│   └── *.py                    # compatibility modules + legacy logic under extraction
└── README.md

The repo is actively being refactored toward a cleaner split:

• commands/ → argument / CLI adapters
• services/ → orchestration and application workflows
• runtime/ → paths, env, files, locks, config
• future domain/ → trading and precheck core logic

Implemented command/service splits

The first extraction pass is already live:

• smart-executor → commands.smart_executor + services.smart_executor_service
• precheck → commands.precheck + services.precheck_service
• precheck internals now also have dedicated service modules for:
  • services.precheck_state
  • services.precheck_snapshot
  • services.precheck_analysis

This keeps behavior stable while giving the codebase a cleaner landing zone for deeper refactors.

Installation

Editable install:

pip install -e .

Run directly after install:

coinhunter --help
coinhunter --version

Quickstart

Initialize user state:

coinhunter init

Inspect runtime wiring:

coinhunter paths
coinhunter doctor

Validate exchange credentials:

coinhunter check-api

Run precheck / gate plumbing:

coinhunter precheck
coinhunter precheck --mark-run-requested "external-gate queued cron run"
coinhunter precheck --ack "analysis finished"

Inspect balances or execute trading actions:

coinhunter smart-executor balances
coinhunter smart-executor status
coinhunter smart-executor hold
coinhunter smart-executor buy ENJUSDT 50
coinhunter smart-executor sell-all ENJUSDT

Generate review data:

coinhunter review-context 12
coinhunter review-engine 12

Probe external market data:

coinhunter market-probe bybit-ticker BTCUSDT
coinhunter market-probe bybit-klines BTCUSDT 60 20

Runtime model

Default layout:

~/.coinhunter/
├── accounts.json
├── config.json
├── executions.json
├── notes.json
├── positions.json
├── watchlist.json
├── logs/
├── reviews/
└── state/

Credential loading:

• Binance credentials are read from ~/.hermes/.env by default.
• COINHUNTER_ENV_FILE can point to a different env file.
• hermes is resolved from PATH first, then ~/.local/bin/hermes, unless HERMES_BIN overrides it.

Useful commands

Diagnostics

coinhunter doctor
coinhunter paths
coinhunter check-api

Trading and execution

coinhunter smart-executor balances
coinhunter smart-executor status
coinhunter smart-executor hold
coinhunter smart-executor rebalance FROMUSDT TOUSDT

Precheck and orchestration

coinhunter precheck
coinhunter external-gate
coinhunter rotate-external-gate-log

Review and market research

coinhunter review-context 12
coinhunter review-engine 12
coinhunter market-probe bybit-ticker BTCUSDT

Development notes

This project is intentionally moving in small, safe refactor steps:

1. Separate runtime concerns from hardcoded paths.
2. Move command dispatch into thin adapters.
3. Introduce orchestration services.
4. Extract reusable domain logic from large compatibility modules.
5. Keep cron / Hermes integration stable during migration.

That means some compatibility modules still exist, but the direction is deliberate.

Near-term roadmap

• Extract more logic from smart_executor.py into dedicated execution / portfolio services.
• Continue shrinking precheck.py by moving snapshot and analysis internals into reusable modules.
• Add domain/ models for positions, signals, and trigger analysis.
• Add tests for runtime paths, precheck service behavior, and CLI stability.
• Evolve toward a more polished installable CLI workflow.

Philosophy

CoinHunter should become:

• more professional
• more maintainable
• safer to operate
• easier for humans and agents to call
• less dependent on prompt-only correctness

This repo is where that evolution happens.