115 lines
5.1 KiB
Markdown
115 lines
5.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Development commands
|
|
|
|
- **Editable install:** `pip install -e .`
|
|
- **Run the CLI locally:** `python -m coinhunter --help`
|
|
- **Install for end users:** `./scripts/install_local.sh` (creates `~/.local/bin/coinhunter`)
|
|
- **Tests:** There is no test suite yet. The README lists next priorities as adding pytest coverage for runtime paths, state manager, and trigger analyzer.
|
|
- **Lint / type-check:** Not configured yet.
|
|
|
|
## CLI command routing
|
|
|
|
`src/coinhunter/cli.py` is the single entrypoint. It resolves aliases to canonical commands, maps canonical commands to Python modules via `MODULE_MAP`, then imports the module and calls `module.main()` after mutating `sys.argv` to match the display name.
|
|
|
|
Active commands live in `src/coinhunter/commands/` and are thin adapters that delegate to `src/coinhunter/services/`. A few legacy commands (`review_context.py`, `review_engine.py`) still live at the `src/coinhunter/` root and are imported directly by `cli.py`. Root-level backward-compat facades (e.g., `precheck.py`, `smart_executor.py`) re-export the moved commands.
|
|
|
|
## Architecture
|
|
|
|
### Layer responsibilities
|
|
|
|
- **CLI (`cli.py`)** — argument parsing, alias resolution, module dispatch.
|
|
- **Commands (`commands/`)** — thin, stateless adapters that call into services.
|
|
- **Services (`services/`)** — orchestration, domain logic, and exchange interaction.
|
|
- **Runtime (`runtime.py`)** — path resolution, env loading, hermes binary discovery.
|
|
- **Logger (`logger.py`)** — structured JSONL logging to `~/.coinhunter/logs/`.
|
|
|
|
### Runtime and environment
|
|
|
|
`runtime.py` defines `RuntimePaths` and `get_runtime_paths()`. User data lives in `~/.coinhunter/` by default (override with `COINHUNTER_HOME`). Credentials are loaded from `~/.hermes/.env` by default (override with `COINHUNTER_ENV_FILE`). Many modules eagerly instantiate `PATHS = get_runtime_paths()` at import time.
|
|
|
|
### Smart executor (`exec`)
|
|
|
|
`commands/smart_executor.py` → `services/smart_executor_service.py` → `services/trade_execution.py`.
|
|
|
|
Supported verbs: `bal`, `overview`, `hold`, `buy SYMBOL USDT`, `flat SYMBOL`, `rotate FROM TO`.
|
|
|
|
- `smart_executor_parser.py` normalizes legacy argv and exposes `parse_cli_args()`.
|
|
- `trade_common.py` holds a global dry-run flag (`set_dry_run` / `is_dry_run`).
|
|
- `execution_state.py` tracks decision IDs in JSON to prevent duplicate executions.
|
|
- `exchange_service.py` wraps `ccxt.binance` and handles symbol normalization.
|
|
- `portfolio_service.py` manages `positions.json` load/save/reconcile.
|
|
|
|
### Precheck
|
|
|
|
`commands/precheck.py` → `services/precheck_service.py`.
|
|
|
|
The precheck workflow:
|
|
1. Load and sanitize state (`precheck_state.py` — clears stale triggers and run requests).
|
|
2. Build a market snapshot (`precheck_snapshot.py` → `snapshot_builder.py`).
|
|
3. Analyze whether to trigger deep analysis (`precheck_analysis.py` → `trigger_analyzer.py`).
|
|
4. Update and save state (`precheck_state.update_state_after_observation`).
|
|
|
|
State is stored in `~/.coinhunter/state/precheck_state.json`.
|
|
|
|
### Review commands
|
|
|
|
- `review N` (`review_context.py`) — generates review context for the last N hours.
|
|
- `recap N` (`review_engine.py`) — generates a full review report by reading JSONL decision/trade/error logs, computing PnL estimates, missed opportunities, and saving a report to `~/.coinhunter/reviews/`.
|
|
|
|
### Logging model
|
|
|
|
`logger.py` writes JSONL to dated files in `~/.coinhunter/logs/`:
|
|
- `decisions_YYYYMMDD.jsonl`
|
|
- `trades_YYYYMMDD.jsonl`
|
|
- `errors_YYYYMMDD.jsonl`
|
|
- `snapshots_YYYYMMDD.jsonl`
|
|
|
|
Use `get_logs_last_n_hours(log_type, hours)` to query recent entries.
|
|
|
|
## Common command reference
|
|
|
|
```bash
|
|
# Diagnostics
|
|
python -m coinhunter diag
|
|
python -m coinhunter paths
|
|
python -m coinhunter api-check
|
|
|
|
# Execution (dry-run)
|
|
python -m coinhunter exec bal
|
|
python -m coinhunter exec overview
|
|
python -m coinhunter exec buy ENJUSDT 50 --dry-run
|
|
python -m coinhunter exec flat ENJUSDT --dry-run
|
|
|
|
# Precheck
|
|
python -m coinhunter precheck
|
|
python -m coinhunter precheck --ack "analysis completed"
|
|
python -m coinhunter precheck --mark-run-requested "reason"
|
|
|
|
# Review
|
|
python -m coinhunter review 12
|
|
python -m coinhunter recap 12
|
|
```
|
|
|
|
## Skill routing
|
|
|
|
When the user's request matches an available skill, ALWAYS invoke it using the Skill
|
|
tool as your FIRST action. Do NOT answer directly, do NOT use other tools first.
|
|
The skill has specialized workflows that produce better results than ad-hoc answers.
|
|
|
|
Key routing rules:
|
|
- Product ideas, "is this worth building", brainstorming → invoke office-hours
|
|
- Bugs, errors, "why is this broken", 500 errors → invoke investigate
|
|
- Ship, deploy, push, create PR → invoke ship
|
|
- QA, test the site, find bugs → invoke qa
|
|
- Code review, check my diff → invoke review
|
|
- Update docs after shipping → invoke document-release
|
|
- Weekly retro → invoke retro
|
|
- Design system, brand → invoke design-consultation
|
|
- Visual audit, design polish → invoke design-review
|
|
- Architecture review → invoke plan-eng-review
|
|
- Save progress, checkpoint, resume → invoke checkpoint
|
|
- Code quality, health check → invoke health
|